Add support for nulls_distinct=False in unique constraints

Author: timb07

CHANGELOG.md

@@ -8,7 +8,12 @@ Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 
 ## [Unreleased]
 
-_No notable unreleased changes_
+- Fixed a bug where a unique constraint with `nulls_distinct=False` was created
+  without "NULLS NOT DISTINCT" by `SaferAddUniqueConstraint`.
+- Fixed a bug where a unique constraint with `nulls_distinct=False` resulted in
+  invalid SQL when `SaferAddUniqueConstraint` was used with PostgreSQL 14.x or
+  earlier (which does not support "NULLS NOT DISTINCT"). The operation will now
+  raise a `ConstraintNotSupported` exception instead.
 
 ## [0.1.25] - 2026-02-24
 

src/django_pg_migration_tools/operations.py

@@ -267,6 +267,7 @@ def safer_create_index(
         index: models.Index | IndexSQLBuilder,
         unique: bool,
         model: type[models.Model],
+        nulls_distinct: bool = True,
     ) -> None:
         self._ensure_not_in_transaction(schema_editor)
 
@@ -283,6 +284,7 @@ def safer_create_index(
             model=model,
             schema_editor=schema_editor,
             index=index,
+            nulls_distinct=nulls_distinct,
         )
         schema_editor.execute(index_sql)
 
@@ -374,6 +376,7 @@ def _get_create_index_sql(
         model: type[models.Model],
         schema_editor: base_schema.BaseDatabaseSchemaEditor,
         index: models.Index | IndexSQLBuilder,
+        nulls_distinct: bool,
     ) -> str:
         if isinstance(index, IndexSQLBuilder):
             assert model._meta.db_table == index.table_name
@@ -388,6 +391,9 @@ def _get_create_index_sql(
         if unique:
             index_sql = index_sql.replace("CREATE INDEX", "CREATE UNIQUE INDEX")
 
+        if not nulls_distinct:
+            index_sql += " NULLS NOT DISTINCT"
+
         return index_sql
 
 
@@ -399,6 +405,10 @@ class ConstraintAlreadyExists(ConstraintOperationError):
     pass
 
 
+class ConstraintNotSupported(ConstraintOperationError):
+    pass
+
+
 class SafeConstraintOperationManager(base_operations.Operation):
     def create_unique_constraint(
         self,
@@ -419,6 +429,20 @@ def create_unique_constraint(
 
         index = self._get_index_for_constraint(constraint)
 
+        if constraint.nulls_distinct is None or constraint.nulls_distinct is True:
+            nulls_distinct = True
+        else:
+            nulls_distinct = False
+
+        if (
+            not nulls_distinct
+            and not schema_editor.connection.features.supports_nulls_distinct_unique_constraints
+        ):
+            # Postgres versions <= 14 do not support NULLS NOT DISTINCT
+            raise ConstraintNotSupported(
+                "Constraints with NULLS NOT DISTINCT are not supported with this PostgreSQL version"
+            )
+
         if (constraint.condition is not None) or constraint.expressions:
             """
             Unique constraints with conditions/expressions do not exist in postgres.
@@ -434,6 +458,7 @@ def create_unique_constraint(
                 index=index,
                 model=model,
                 unique=True,
+                nulls_distinct=nulls_distinct,
             )
             return
 
@@ -448,6 +473,7 @@ def create_unique_constraint(
             index=index,
             model=model,
             unique=True,
+            nulls_distinct=nulls_distinct,
         )
 
         # Django doesn't have a handy flag "using=..." so we need to alter the

tests/django_pg_migration_tools/test_operations.py

@@ -1,5 +1,6 @@
 from textwrap import dedent
 from typing import Any
+from unittest.mock import patch
 
 import pytest
 from django.db import (
@@ -1436,6 +1437,144 @@ def test_when_expression_on_constraint_only_creates_index(self):
             )
             assert not cursor.fetchone()
 
+    # Disable the overall test transaction because a unique concurrent index
+    # cannot be triggered/tested inside of a transaction.
+    @pytest.mark.django_db(transaction=True)
+    def test_when_nulls_not_distinct(self):
+        # Prove that:
+        #   - An invalid index doesn't exist.
+        #   - The constraint doesn't exist yet.
+        with connection.cursor() as cursor:
+            cursor.execute(
+                psycopg_sql.SQL(operations.IndexQueries.CHECK_INVALID_INDEX)
+                .format(index_name=psycopg_sql.Literal("unique_null_int_field"))
+                .as_string(cursor.connection)
+            )
+            assert not cursor.fetchone()
+            cursor.execute(
+                psycopg_sql.SQL(operations.ConstraintQueries.CHECK_EXISTING_CONSTRAINT)
+                .format(constraint_name=psycopg_sql.Literal("unique_null_int_field"))
+                .as_string(cursor.connection)
+            )
+            assert not cursor.fetchone()
+            # Also, set the lock_timeout to check it has been returned to
+            # its original value once the unique index creation is completed.
+            cursor.execute(_SET_LOCK_TIMEOUT)
+
+        project_state = ProjectState()
+        project_state.add_model(ModelState.from_model(NullIntFieldModel))
+        new_state = project_state.clone()
+
+        operation = operations.SaferAddUniqueConstraint(
+            model_name="nullintfieldmodel",
+            constraint=UniqueConstraint(
+                fields=("int_field",),
+                name="unique_null_int_field",
+                nulls_distinct=False,
+            ),
+        )
+        operation.state_forwards(self.app_label, new_state)
+        # Proceed to add the unique index followed by the constraint:
+        with connection.schema_editor(atomic=False, collect_sql=False) as editor:
+            if not connection.features.supports_nulls_distinct_unique_constraints:
+                # Postgres versions <= 14 do not support NULLS NOT DISTINCT
+                with pytest.raises(operations.ConstraintNotSupported):
+                    operation.database_forwards(
+                        self.app_label,
+                        editor,
+                        from_state=project_state,
+                        to_state=new_state,
+                    )
+                return
+
+            with utils.CaptureQueriesContext(connection) as queries:
+                operation.database_forwards(
+                    self.app_label, editor, from_state=project_state, to_state=new_state
+                )
+
+        with connection.cursor() as cursor:
+            cursor.execute(
+                _CHECK_INDEX_EXISTS_QUERY,
+                {
+                    "table_name": "example_app_nullintfieldmodel",
+                    "index_name": "unique_null_int_field",
+                },
+            )
+            assert cursor.fetchone()
+            cursor.execute(
+                _CHECK_CONSTRAINT_EXISTS_QUERY,
+                {
+                    "table_name": "example_app_nullintfieldmodel",
+                    "constraint_name": "unique_null_int_field",
+                },
+            )
+            assert cursor.fetchone()
+
+        # Assert on the sequence of expected SQL queries:
+        #
+        # 1. Check if the constraint already exists.
+        assert queries[0]["sql"] == dedent("""
+            SELECT con.conname
+            FROM pg_catalog.pg_constraint con
+            INNER JOIN pg_catalog.pg_namespace nsp ON nsp.oid = con.connamespace
+            WHERE con.conname = 'unique_null_int_field'
+                AND nsp.nspname = current_schema();
+            """)
+        # 2. Check the original lock_timeout value to be able to restore it
+        # later.
+        assert queries[1]["sql"] == "SHOW lock_timeout;"
+        # 3. Remove the timeout.
+        assert queries[2]["sql"] == "SET lock_timeout = '0';"
+        # 4. Verify if the index is invalid.
+        assert queries[3]["sql"] == dedent("""
+            SELECT relname
+            FROM pg_class, pg_index
+            WHERE (
+                pg_index.indisvalid = false
+                AND pg_index.indexrelid = pg_class.oid
+                AND relname = 'unique_null_int_field'
+            );
+            """)
+        # 5. Finally create the index concurrently.
+        assert (
+            queries[4]["sql"]
+            == 'CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "unique_null_int_field" ON "example_app_nullintfieldmodel" ("int_field") NULLS NOT DISTINCT'
+        )
+        # 6. Set the timeout back to what it was originally.
+        assert queries[5]["sql"] == "SET lock_timeout = '1s';"
+
+        # 7. Add the table constraint.
+        assert (
+            queries[6]["sql"]
+            == 'ALTER TABLE "example_app_nullintfieldmodel" ADD CONSTRAINT "unique_null_int_field" UNIQUE USING INDEX "unique_null_int_field"'
+        )
+
+    def test_when_nulls_not_distinct_and_not_supported(self):
+        project_state = ProjectState()
+        project_state.add_model(ModelState.from_model(NullIntFieldModel))
+        new_state = project_state.clone()
+
+        operation = operations.SaferAddUniqueConstraint(
+            model_name="nullintfieldmodel",
+            constraint=UniqueConstraint(
+                fields=("int_field",),
+                name="unique_null_int_field",
+                nulls_distinct=False,
+            ),
+        )
+        with connection.schema_editor(atomic=False, collect_sql=False) as editor:
+            with patch.object(
+                connection, "features", supports_nulls_distinct_unique_constraints=False
+            ):
+                # Postgres versions <= 14 do not support NULLS NOT DISTINCT
+                with pytest.raises(operations.ConstraintNotSupported):
+                    operation.database_forwards(
+                        self.app_label,
+                        editor,
+                        from_state=project_state,
+                        to_state=new_state,
+                    )
+
 
 class TestBuildPostgresIdentifier:
     def test_happy_path(self):