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: cdc858cd88fbf86661662147210f9587117aa593

Change-Id: I3f2c8fe346d3235fa8ba12c4d9ab712ddb840230
(cherry picked from commit 57dcfdacaa75ddac3a9246512f3deac4aef10cf0)

diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst
index 3345d1185de1bf97a61e152c16152f52bd3b3b8e..d15fabb556773670041f47cd10b11a9289d72b04 100644 (file)
--- a/doc/build/changelog/changelog_20.rst
+++ b/doc/build/changelog/changelog_20.rst
@@ -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

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 8637f35d4fba142ee97cbfc71b5bf7b0480e3137..3122ea9e7ca28a84b6dfc2968e7f479cf80ed782 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -1390,6 +1390,29 @@ that are subject to the action::
 .. versionadded:: 2.0.40
 
 
+``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