Add support for exclusion constraints in create_table operation (#624)

This PR adds a new type of constraint to `create_table` operation called
`exclude` to support [exclusion
constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-EXCLUSION).

New options:
* `exclude.index_method`: name of the index method (e.g. btree, gist,
etc.)
* `exclude.elements`: exlusion elements
* `exclude.predicate`: WHERE clause for partial indices

Example constraint forbidding overlap in room reservations:
```json
{
  "name": "52_create_table_with_table_exclusion_constraint",
  "operations": [
    {
      "create_table": {
        "name": "room_reservations",
        "columns": [
          {
            "name": "id",
            "type": "serial"
          },
          {
            "name": "start",
            "type": "timestamp"
          },
          {
            "name": "end",
            "type": "timestamp"
          },
          {
            "name": "canceled",
            "type": "boolean",
            "default": "false"
          }
        ],
        "constraints": [
          {
            "name": "forbid_double_booking",
            "type": "exclude",
            "exclude": {
              "index_method": "gist",
              "elements": "id WITH =, tsrange(\"start\", \"end\") WITH &&",
              "predicate": "NOT canceled"
            }
          }
        ]
      }
    }
  ]
}
```

The tests I added require the extension `btree_gist`. So I added it for
`make examples` and running `go test`.

Author: kvch

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

@@ -216,6 +216,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:
@@ -241,16 +242,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
@@ -312,6 +321,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 {
@@ -398,6 +409,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 {