Add support for exclusion constraints in create_table operation

docs/operations/create_table.mdx

@@ -76,10 +76,15 @@ Each `constraint` is defined as:
     "storage_parameters": "parameter=value",
     "include_columns": ["list", "of", "columns", "included in index"]
   },
+  "exclude": {
+    "index_method": "name of the index method, e.g. btree",
+    "elements": "exclude elements",
+    "predicate": "WHERE clause of the exclude constraint"
+  }
 },
 ```
 
-Supported constraint types: `unique`, `check`, `primary_key`, `foreign_key`.
+Supported constraint types: `unique`, `check`, `primary_key`, `foreign_key`, `exclude`.
 
 Please note that you can only configure primary keys in `columns` list or `constraints` list, but
 not in both places.
@@ -154,3 +159,9 @@ Create a table with table level constraints:
 Create a table with table level foreign key constraints:
 
 <ExampleSnippet example="51_create_table_with_table_foreign_key_constraint.json" language="json" />
+
+### Create a table with exclusion constraint
+
+Create a table with an exclusion:
+
+<ExampleSnippet example="52_create_table_with_table_exclusion_constraint.json" language="json" />

examples/.ledger

@@ -49,3 +49,4 @@
 49_unset_not_null_on_indexed_column.json
 50_create_table_with_table_constraint.json
 51_create_table_with_table_foreign_key_constraint.json
+52_create_table_with_exclusion_constraint.json

examples/52_create_table_with_exclusion_constraint.json

@@ -0,0 +1,46 @@
+{
+  "name": "52_create_table_with_table_exclusion_constraint",
+  "operations": [
+    {
+      "create_table": {
+        "name": "library",
+        "columns": [
+          {
+            "name": "id",
+            "type": "serial"
+          },
+          {
+            "name": "returned",
+            "type": "timestamp"
+          },
+          {
+            "name": "title",
+            "type": "text"
+          },
+          {
+            "name": "summary",
+            "type": "text"
+          }
+        ],
+        "constraints": [
+          {
+            "name": "rooms_pk",
+            "type": "primary_key",
+            "columns": [
+              "id"
+            ]
+          },
+          {
+            "name": "forbid_duplicated_titles",
+            "type": "exclude",
+            "exclude": {
+              "index_method": "btree",
+              "elements": "title WITH =",
+              "predicate": "title IS NOT NULL"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/stretchr/testify v1.10.0
 	github.com/testcontainers/testcontainers-go v0.35.0
 	github.com/testcontainers/testcontainers-go/modules/postgres v0.35.0
-	github.com/xataio/pg_query_go/v6 v6.0.0-20250122133641-54118c062181
+	github.com/xataio/pg_query_go/v6 v6.0.0-20250124115938-4fa82ad6d036
 	golang.org/x/tools v0.29.0
 )
 

go.sum

@@ -223,6 +223,10 @@ github.com/tklauser/numcpus v0.8.0 h1:Mx4Wwe/FjZLeQsK/6kt2EOepwwSl7SmJrK5bV/dXYg
 github.com/tklauser/numcpus v0.8.0/go.mod h1:ZJZlAY+dmR4eut8epnzf0u/VwodKmryxR8txiloSqBE=
 github.com/xataio/pg_query_go/v6 v6.0.0-20250122133641-54118c062181 h1:iLOHgul20WFUhO4eFpJ/lZRkHzZICF2ghzncxtOcD0E=
 github.com/xataio/pg_query_go/v6 v6.0.0-20250122133641-54118c062181/go.mod h1:GK6bpfAhPtZb7wG/IccqvnH+cz3cmvvRTkC+MosESGo=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250123182324-526a22cbe0c0 h1:/fXLU7NusFv8TSEAM7n+vtsN5Rr2La9tXWEunrJOWrI=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250123182324-526a22cbe0c0/go.mod h1:GK6bpfAhPtZb7wG/IccqvnH+cz3cmvvRTkC+MosESGo=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250124115938-4fa82ad6d036 h1:QMjBW1XIFUDzyUs/zlYmUo8lNO+hQ4VVt0msFv2AYpw=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250124115938-4fa82ad6d036/go.mod h1:GK6bpfAhPtZb7wG/IccqvnH+cz3cmvvRTkC+MosESGo=
 github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778/go.mod h1:2MuV+tbUrU1zIOPMxZ5EncGwgmMJsa+9ucAQZXxsObs=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=

internal/jsonschema/testdata/create-table-16-invalid-exclusion-missing-exclusion.txtar

@@ -0,0 +1,34 @@
+This is an invalid 'create_table' migration.
+Exclusion constraints must have exclude configured
+
+-- create_table.json --
+{
+  "name": "migration_name",
+  "operations": [
+    {
+      "create_table": {
+        "name": "posts",
+        "columns": [
+          {
+            "name": "title",
+            "type": "varchar(255)"
+          },
+          {
+            "name": "user_id",
+            "type": "integer",
+            "nullable": true
+          }
+        ],
+        "constraints": [
+          {
+            "name": "my_invalid_fk",
+            "type": "exclude"
+          }
+        ]
+      }
+    }
+  ]
+}
+
+-- valid --
+false

internal/jsonschema/testdata/create-table-17-invalid-exclusion-columns-set.txtar

@@ -0,0 +1,39 @@
+This is an invalid 'create_table' migration.
+Exclusion constraints mustn't have columns configured
+
+-- create_table.json --
+{
+  "name": "migration_name",
+  "operations": [
+    {
+      "create_table": {
+        "name": "posts",
+        "columns": [
+          {
+            "name": "title",
+            "type": "varchar(255)"
+          },
+          {
+            "name": "user_id",
+            "type": "integer",
+            "nullable": true
+          }
+        ],
+        "constraints": [
+          {
+            "name": "my_invalid_exclusion",
+            "type": "exclude",
+            "columns": ["invalid"],
+            "exclude": {
+              "index_method": "btree",
+              "elements": "title WITH ="
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+
+-- valid --
+false

internal/testutils/error_codes.go

@@ -3,10 +3,11 @@
 package testutils
 
 const (
-	CheckViolationErrorCode   string = "check_violation"
-	FKViolationErrorCode      string = "foreign_key_violation"
-	NotNullViolationErrorCode string = "not_null_violation"
-	UniqueViolationErrorCode  string = "unique_violation"
-	UndefinedColumnErrorCode  string = "undefined_column"
-	UndefinedTableErrorCode   string = "undefined_table"
+	CheckViolationErrorCode     string = "check_violation"
+	ExclusionViolationErrorCode string = "exclusion_violation"
+	FKViolationErrorCode        string = "foreign_key_violation"
+	NotNullViolationErrorCode   string = "not_null_violation"
+	UndefinedColumnErrorCode    string = "undefined_column"
+	UndefinedTableErrorCode     string = "undefined_table"
+	UniqueViolationErrorCode    string = "unique_violation"
 )

pkg/migrations/op_common_test.go

@@ -272,6 +272,13 @@ func PrimaryKeyConstraintMustExist(t *testing.T, db *sql.DB, schema, table, cons
 	}
 }
 
+func ExcludeConstraintMustExist(t *testing.T, db *sql.DB, schema, table, constraint string) {
+	t.Helper()
+	if !excludeConstraintExists(t, db, schema, table, constraint) {
+		t.Fatalf("Expected constraint %q to exist", constraint)
+	}
+}
+
 func IndexMustExist(t *testing.T, db *sql.DB, schema, table, index string) {
 	t.Helper()
 	if !indexExists(t, db, schema, table, index) {
@@ -477,6 +484,26 @@ func primaryKeyConstraintExists(t *testing.T, db *sql.DB, schema, table, constra
 	return exists
 }
 
+func excludeConstraintExists(t *testing.T, db *sql.DB, schema, table, constraint string) bool {
+	t.Helper()
+
+	var exists bool
+	err := db.QueryRow(`
+    SELECT EXISTS (
+      SELECT 1
+      FROM pg_catalog.pg_constraint
+      WHERE conrelid = $1::regclass
+      AND conname = $2
+      AND contype = 'x'
+    )`,
+		fmt.Sprintf("%s.%s", schema, table), constraint).Scan(&exists)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return exists
+}
+
 func triggerExists(t *testing.T, db *sql.DB, schema, table, trigger string) bool {
 	t.Helper()
 

pkg/migrations/op_create_table.go

@@ -215,6 +215,7 @@ func (o *OpCreateTable) updateSchema(s *schema.Schema) *schema.Schema {
 	uniqueConstraints := make(map[string]*schema.UniqueConstraint, 0)
 	checkConstraints := make(map[string]*schema.CheckConstraint, 0)
 	foreignKeys := make(map[string]*schema.ForeignKey, 0)
+	excludeConstraints := make(map[string]*schema.ExcludeConstraint, 0)
 	for _, c := range o.Constraints {
 		switch c.Type {
 		case ConstraintTypeUnique:
@@ -240,16 +241,24 @@ func (o *OpCreateTable) updateSchema(s *schema.Schema) *schema.Schema {
 				OnUpdate:          string(c.References.OnUpdate),
 				MatchType:         string(c.References.MatchType),
 			}
+		case ConstraintTypeExclude:
+			excludeConstraints[c.Name] = &schema.ExcludeConstraint{
+				Name:        c.Name,
+				IndexMethod: c.Exclude.IndexMethod,
+				Elements:    c.Exclude.Elements,
+				Predicate:   c.Exclude.Predicate,
+			}
 		}
 	}
 
 	s.AddTable(o.Name, &schema.Table{
-		Name:              o.Name,
-		Columns:           columns,
-		UniqueConstraints: uniqueConstraints,
-		CheckConstraints:  checkConstraints,
-		PrimaryKey:        primaryKeys,
-		ForeignKeys:       foreignKeys,
+		Name:               o.Name,
+		Columns:            columns,
+		UniqueConstraints:  uniqueConstraints,
+		CheckConstraints:   checkConstraints,
+		PrimaryKey:         primaryKeys,
+		ForeignKeys:        foreignKeys,
+		ExcludeConstraints: excludeConstraints,
 	})
 
 	return s
@@ -311,6 +320,8 @@ func constraintsToSQL(constraints []Constraint) (string, error) {
 			constraintsSQL[i] = writer.WritePrimaryKey()
 		case ConstraintTypeForeignKey:
 			constraintsSQL[i] = writer.WriteForeignKey(c.References.Table, c.References.Columns, c.References.OnDelete, c.References.OnUpdate, c.References.OnDeleteSetColumns)
+		case ConstraintTypeExclude:
+			constraintsSQL[i] = writer.WriteExclude(c.Exclude.IndexMethod, c.Exclude.Elements, c.Exclude.Predicate)
 		}
 	}
 	if len(constraintsSQL) == 0 {
@@ -397,6 +408,20 @@ func (w *ConstraintSQLWriter) WriteForeignKey(referencedTable string, referenced
 	return constraint
 }
 
+func (w *ConstraintSQLWriter) WriteExclude(indexMethod, elements, predicate string) string {
+	constraint := ""
+	if w.Name != "" {
+		constraint = fmt.Sprintf("CONSTRAINT %s ", pq.QuoteIdentifier(w.Name))
+	}
+	constraint += fmt.Sprintf("EXCLUDE USING %s (%s)", indexMethod, elements)
+	constraint += w.addIndexParameters()
+	if predicate != "" {
+		constraint += fmt.Sprintf(" WHERE (%s)", predicate)
+	}
+	constraint += w.addDeferrable()
+	return constraint
+}
+
 func (w *ConstraintSQLWriter) addIndexParameters() string {
 	constraint := ""
 	if len(w.IncludeColumns) != 0 {

pkg/migrations/op_create_table_test.go

@@ -1020,6 +1020,76 @@ func TestCreateTable(t *testing.T) {
 				}, rows)
 			},
 		},
+		{
+			name: "create table with a simple exclude constraint mimicking unique constraint",
+			migrations: []migrations.Migration{
+				{
+					Name: "01_create_table",
+					Operations: migrations.Operations{
+						&migrations.OpCreateTable{
+							Name: "users",
+							Columns: []migrations.Column{
+								{
+									Name: "id",
+									Type: "int",
+								},
+								{
+									Name: "name",
+									Type: "text",
+								},
+							},
+							Constraints: []migrations.Constraint{
+								{
+									Name: "exclude_id",
+									Type: migrations.ConstraintTypeExclude,
+									Exclude: &migrations.ConstraintExclude{
+										IndexMethod: "btree",
+										Elements:    "id WITH =",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+			afterStart: func(t *testing.T, db *sql.DB, schema string) {
+				// The exclusion constraint exists on the new table.
+				ExcludeConstraintMustExist(t, db, schema, "users", "exclude_id")
+
+				// Inserting a row into the table succeeds when the exclude constraint is satisfied.
+				// This is the first row, so the constraint is satisfied.
+				MustInsert(t, db, schema, "01_create_table", "users", map[string]string{
+					"id":   "1",
+					"name": "alice",
+				})
+
+				// Inserting a row into the table fails because there is already a row with id 1.
+				MustNotInsert(t, db, schema, "01_create_table", "users", map[string]string{
+					"id":   "1",
+					"name": "b",
+				}, testutils.ExclusionViolationErrorCode)
+			},
+			afterRollback: func(t *testing.T, db *sql.DB, schema string) {
+				// The table has been dropped, so the constraint is gone.
+			},
+			afterComplete: func(t *testing.T, db *sql.DB, schema string) {
+				// The exclusion constraint exists on the new table.
+				ExcludeConstraintMustExist(t, db, schema, "users", "exclude_id")
+
+				// Inserting a row into the table succeeds when the exclude constraint is satisfied.
+				// This is the first row, so the constraint is satisfied.
+				MustInsert(t, db, schema, "01_create_table", "users", map[string]string{
+					"id":   "1",
+					"name": "alice",
+				})
+
+				// Inserting a row into the table fails because there is already a row with id 1.
+				MustNotInsert(t, db, schema, "01_create_table", "users", map[string]string{
+					"id":   "1",
+					"name": "b",
+				}, testutils.ExclusionViolationErrorCode)
+			},
+		},
 	})
 }