document postgresql_nulls_not_distinct

<!-- Provide a general summary of your proposed changes in the Title field above -->

### Description
<!-- Describe your changes in detail -->

https://github.com/sqlalchemy/sqlalchemy/issues/8240 and https://github.com/sqlalchemy/sqlalchemy/pull/9834 added support for `NULLS NOT DISTINCT` to the PostgreSQL dialect, but didn't add it to the docs (only the change log). This adds a section to the "Constraint Options" section of the PostgreSQL dialect docs.

### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)

-->

This pull request is:

- [x] A documentation / typographical / small typing error fix
	- Good to go, no issue or tests are needed
- [ ] A short code fix
	- please include the issue number, and create an issue if none exists, which
	  must include a complete example of the issue.  one line code fixes without an
	  issue and demonstration will not be accepted.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.   one line code fixes without tests will not be accepted.
- [ ] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

**Have a nice day!**

Closes: #13279
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/13279
Pull-request-sha: cdc858cd88

Change-Id: I3f2c8fe346d3235fa8ba12c4d9ab712ddb840230
This commit is contained in:
David Lord
2026-05-17 16:09:16 -04:00
committed by sqla-tester
parent f55557e96a
commit 57dcfdacaa
2 changed files with 24 additions and 1 deletions
+1 -1
View File
@@ -4118,7 +4118,7 @@
:tags: usecase, postgresql
:tickets: 8240
Added support for PostgreSQL 10 ``NULLS NOT DISTINCT`` feature of
Added support for PostgreSQL 15 ``NULLS NOT DISTINCT`` feature of
unique indexes and unique constraint using the dialect option
``postgresql_nulls_not_distinct``.
Updated the reflection logic to also correctly take this option
@@ -1528,6 +1528,29 @@ database to use its default of ``VIRTUAL``; on PostgreSQL 17 and earlier,
``NULLS NOT DISTINCT``
^^^^^^^^^^^^^^^^^^^^^^
By default, two ``null`` values are not considered equal for unique constraints
and indexes. Therefore, seemingly duplicate rows may be stored if one of the
values in the constraint is ``null``. This default behavior is implementation
defined, so other SQL dialects may behave differently than PostgreSQL.
The ``NULLS NOT DISTINCT`` clause can be used to change this behavior, treating
null values as equal and preventing unintended duplicate rows. The opposite
``NULLS DISTINCT`` clause can also be used to make PostgreSQL's default behavior
explict.
The ``postgresql_nulls_not_distinct`` parameter can be set to ``True`` to
add the ``NULLS NOT DISTINCT`` clause, or ``False`` to add ``NULLS DISTINCT``.
Not setting it, or passing ``None``, will not add a clause and keep the default
behavior.
This feature requires PostgreSQL 15 or later.
.. versionadded:: 2.0.16
.. _postgresql_table_valued_overview:
Table values, Table and Column valued functions, Row and Tuple objects