diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst index e6fa9ddcd2..14a3889c54 100644 --- 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 1702bc70c9..77b6a9d261 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -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