Add support for nulls_not_distinct option in create_constraint operations

Add support for `nulls_not_distinct` option in `create_constraint` operations for unique constraints.

Author: kvch

docs/operations/create_constraint.mdx

@@ -18,6 +18,7 @@ Required fields: `name`, `table`, `type`, `up`, `down`.
     "type": "unique"| "check" | "foreign_key",
     "check": "SQL expression for CHECK constraint",
     "no_inherit": "true|false",
+    "nulls_not_distinct": "true|false",
     "references": {
       "name": "name of foreign key reference",
       "table": "name of referenced table",
@@ -62,6 +63,26 @@ Add a multi-column unique constraint on the `tickets` table:
 
 <ExampleSnippet example="44_add_table_unique_constraint.json" language="json" />
 
+Add a unique constraint with `nulls_not_distinct` option on the `users` table:
+
+```json
+{
+  "create_constraint": {
+    "table": "users",
+    "name": "unique_email",
+    "columns": ["email"],
+    "type": "unique",
+    "nulls_not_distinct": true,
+    "up": {
+      "email": "email"
+    },
+    "down": {
+      "email": "email"
+    }
+  }
+}
+```
+
 ### Add a `CHECK` constraint
 
 Add a check constraint on the `sellers_name` and `sellers_zip` fields on the `ticket` table. The `up` SQL expression ensures that pairs of values not meeting the new constraint on the old columns are data migrated to values that meet the new constraint in the new columns:

internal/jsonschema/jsonschema_test.go

@@ -1,5 +1,3 @@
-// SPDX-License-Identifier: Apache-2.0
-
 package jsonschema
 
 import (
@@ -52,3 +50,71 @@ func TestJSONSchemaValidation(t *testing.T) {
 		})
 	}
 }
+
+func TestNullsNotDistinctOption(t *testing.T) {
+	t.Parallel()
+
+	compiler := jsonschema.NewCompiler()
+	sch, err := compiler.Compile(schemaPath)
+	assert.NoError(t, err)
+
+	testCases := []struct {
+		name          string
+		jsonData      string
+		shouldValidate bool
+	}{
+		{
+			name: "valid nulls_not_distinct",
+			jsonData: `{
+				"create_constraint": {
+					"table": "users",
+					"name": "unique_email",
+					"columns": ["email"],
+					"type": "unique",
+					"nulls_not_distinct": true,
+					"up": {
+						"email": "email"
+					},
+					"down": {
+						"email": "email"
+					}
+				}
+			}`,
+			shouldValidate: true,
+		},
+		{
+			name: "invalid nulls_not_distinct for non-unique constraint",
+			jsonData: `{
+				"create_constraint": {
+					"table": "users",
+					"name": "check_email",
+					"columns": ["email"],
+					"type": "check",
+					"check": "email IS NOT NULL",
+					"nulls_not_distinct": true,
+					"up": {
+						"email": "email"
+					},
+					"down": {
+						"email": "email"
+					}
+				}
+			}`,
+			shouldValidate: false,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			var v map[string]any
+			assert.NoError(t, json.Unmarshal([]byte(tc.jsonData), &v))
+
+			err = sch.Validate(v)
+			if tc.shouldValidate && err != nil {
+				t.Errorf("%#v", err)
+			} else if !tc.shouldValidate && err == nil {
+				t.Errorf("expected %q to be invalid", tc.name)
+			}
+		})
+	}
+}

internal/jsonschema/testdata/create-constraint-1-invalid-check.txtar

@@ -20,6 +20,23 @@ Check constraint must have the option 'check' configured.
           "my_column": "my_column"
         }
       }
+    },
+    {
+      "create_constraint": {
+        "name": "my_invalid_unique",
+        "table": "my_table",
+        "type": "unique",
+        "columns": [
+          "my_column"
+        ],
+        "nulls_not_distinct": true,
+        "up": {
+          "my_column": "my_column"
+        },
+        "down": {
+          "my_column": "my_column"
+        }
+      }
     }
   ]
 }

internal/jsonschema/testdata/create-constraint-2-invalid-no-inherit.txtar

@@ -21,6 +21,41 @@ Only check constraints have no_inherit flag.
           "my_column": "my_column"
         }
       }
+    },
+    {
+      "create_constraint": {
+        "name": "my_invalid_unique",
+        "table": "my_table",
+        "type": "unique",
+        "columns": [
+          "my_column"
+        ],
+        "nulls_not_distinct": true,
+        "up": {
+          "my_column": "my_column"
+        },
+        "down": {
+          "my_column": "my_column"
+        }
+      }
+    },
+    {
+      "create_constraint": {
+        "name": "my_invalid_check_with_nulls_not_distinct",
+        "table": "my_table",
+        "type": "check",
+        "columns": [
+          "my_column"
+        ],
+        "nulls_not_distinct": true,
+        "check": "my_column IS NOT NULL",
+        "up": {
+          "my_column": "my_column"
+        },
+        "down": {
+          "my_column": "my_column"
+        }
+      }
     }
   ]
 }

pkg/migrations/op_create_constraint.go

@@ -1,5 +1,3 @@
-// SPDX-License-Identifier: Apache-2.0
-
 package migrations
 
 import (
@@ -82,7 +80,7 @@ func (o *OpCreateConstraint) Start(ctx context.Context, conn db.DB, latestSchema
 
 	switch o.Type {
 	case OpCreateConstraintTypeUnique:
-		return table, createUniqueIndexConcurrently(ctx, conn, s.Name, o.Name, table.Name, temporaryNames(o.Columns))
+		return table, createUniqueIndexConcurrently(ctx, conn, s.Name, o.Name, table.Name, temporaryNames(o.Columns), o.NullsNotDistinct)
 	case OpCreateConstraintTypeCheck:
 		return table, o.addCheckConstraint(ctx, conn, table.Name)
 	case OpCreateConstraintTypeForeignKey:
@@ -279,6 +277,10 @@ func (o *OpCreateConstraint) Validate(ctx context.Context, s *schema.Schema) err
 		}
 	}
 
+	if o.Type != OpCreateConstraintTypeUnique && o.NullsNotDistinct {
+		return fmt.Errorf("nulls_not_distinct can only be true for unique constraints")
+	}
+
 	return nil
 }
 

pkg/migrations/types.go

@@ -1,6 +1,3 @@
-// SPDX-License-Identifier: Apache-2.0
-// Code generated by github.com/atombender/go-jsonschema, DO NOT EDIT.
-
 package migrations
 
 import "github.com/oapi-codegen/nullable"
@@ -288,6 +285,9 @@ type OpCreateConstraint struct {
 	// Do not propagate constraint to child tables
 	NoInherit bool `json:"no_inherit,omitempty"`
 
+	// Nulls not distinct constraint
+	NullsNotDistinct bool `json:"nulls_not_distinct,omitempty"`
+
 	// Reference to the foreign key
 	References *TableForeignKeyReference `json:"references,omitempty"`
 

schema.json

@@ -848,6 +848,11 @@
           "type": "boolean",
           "default": false
         },
+        "nulls_not_distinct": {
+          "description": "Nulls not distinct constraint",
+          "type": "boolean",
+          "default": false
+        },
         "references": {
           "description": "Reference to the foreign key",
           "$ref": "#/$defs/TableForeignKeyReference"
@@ -877,6 +882,9 @@
               },
               "no_inherit": {
                 "const": false
+              },
+              "nulls_not_distinct": {
+                "const": false
               }
             },
             "required": ["columns", "references"]