Improve create_index operation with extra index element settings (#697)

kvch · web-flow · commit 7b383dc405a0 · 2025-02-28T10:32:23.000+01:00
This PR adds a breaking change to `create_index` operation. From now on
`columns` does not accept a list of column names. Instead it expects a
map, so we can support for additional index elements settings.

New settings:
* `collation`: name of the collation to use on the column
* `opclass`: `opclass.name` sets the name of the operator class and
`opclass.params` expects a KV pairs for operator class settings
* `sort`: change the ordering (`ASC` or `DESC`)
* `nulls`: change the position of null values in the index (`FIRST` or
`LAST`)
diff --git a/docs/operations/create_index.mdx b/docs/operations/create_index.mdx
@@ -10,7 +10,20 @@ description: A create index operation creates a new index on a set of columns.
   "create_index": {
     "table": "name of table on which to define the index",
     "name": "index name",
-    "columns": [ "names of columns on which to define the index" ]
+    "columns": [
+      "column_name": {
+        "collate": "collation name",
+        "sort": "ASC | DESC",
+        "nulls": "FIRST | LAST",
+        "opclass": {
+          "name": "operator_class_name",
+          "params": [
+             "param1=val",
+             "param2=val"
+          ]
+        }
+      }
+    ]
     "predicate": "conditional expression for defining a partial index",
     "storage_parameters": "comma-separated list of storage parameters",
     "unique": true | false,
@@ -51,3 +64,9 @@ Set storage parameters and index method:
 Create a unique index:
 
 <ExampleSnippet example="42_create_unique_index.json" language="json" />
+
+### Create an index with custom operator class
+
+Create an index with a custom operator class:
+
+<ExampleSnippet example="54_create_index_with_opclass.json" language="json" />
diff --git a/examples/.ledger b/examples/.ledger
@@ -51,3 +51,4 @@
 51_create_table_with_table_foreign_key_constraint.json
 52_create_table_with_exclusion_constraint.json
 53_add_column_with_volatile_default.json
+54_create_index_with_opclass.json
diff --git a/examples/10_create_index.json b/examples/10_create_index.json
@@ -5,9 +5,9 @@
       "create_index": {
         "name": "idx_fruits_name",
         "table": "fruits",
-        "columns": [
-          "name"
-        ]
+        "columns": {
+          "name": {}
+        }
       }
     }
   ]
diff --git a/examples/37_create_partial_index.json b/examples/37_create_partial_index.json
@@ -5,9 +5,9 @@
       "create_index": {
         "name": "idx_fruits_id_gt_10",
         "table": "fruits",
-        "columns": [
-          "id"
-        ],
+        "columns": {
+          "id": {}
+        },
         "predicate": "id > 10"
       }
     }
diff --git a/examples/38_create_hash_index_with_fillfactor.json b/examples/38_create_hash_index_with_fillfactor.json
@@ -5,9 +5,9 @@
       "create_index": {
         "name": "idx_fruits_name",
         "table": "fruits",
-        "columns": [
-          "name"
-        ],
+        "columns": {
+          "name": {}
+        },
         "method": "hash",
         "storage_parameters": "fillfactor = 70"
       }
diff --git a/examples/42_create_unique_index.json b/examples/42_create_unique_index.json
@@ -5,9 +5,9 @@
       "create_index": {
         "name": "idx_fruits_unique_name",
         "table": "fruits",
-        "columns": [
-          "name"
-        ],
+        "columns": {
+          "name": {}
+        },
         "unique": true
       }
     }
diff --git a/examples/54_create_index_with_opclass.json b/examples/54_create_index_with_opclass.json
@@ -0,0 +1,18 @@
+{
+  "name": "54_create_index_with_opclass",
+  "operations": [
+    {
+      "create_index": {
+        "name": "idx_fruits_custom_opclass",
+        "table": "fruits",
+        "columns": {
+          "id": {
+            "opclass": {
+              "name": "int8_ops"
+            }
+          }
+        }
+      }
+    }
+  ]
+}
diff --git a/go.mod b/go.mod
@@ -15,7 +15,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-20250124115938-4fa82ad6d036
+	github.com/xataio/pg_query_go/v6 v6.0.0-20250226155420-277802e03678
 	golang.org/x/tools v0.30.0
 )
 
diff --git a/go.sum b/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-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/xataio/pg_query_go/v6 v6.0.0-20250226124908-814e464c6798 h1:rfb51gWpD24si3My5eiSJBGFKl+uzxN+He53bZCMsOw=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250226124908-814e464c6798/go.mod h1:GK6bpfAhPtZb7wG/IccqvnH+cz3cmvvRTkC+MosESGo=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250226155420-277802e03678 h1:jNslWEyKOXeYi7wZfkcSfsR/slEemAU5rVKBvkNnSsg=
+github.com/xataio/pg_query_go/v6 v6.0.0-20250226155420-277802e03678/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=
diff --git a/pkg/migrations/op_common_test.go b/pkg/migrations/op_common_test.go
@@ -309,6 +309,13 @@ func IndexMustExist(t *testing.T, db *sql.DB, schema, table, index string) {
 	}
 }
 
+func IndexDescendingMustExist(t *testing.T, db *sql.DB, schema, table, index string, columnIdx int) {
+	t.Helper()
+	if !indexDescendingExists(t, db, schema, table, index, columnIdx) {
+		t.Fatalf("Expected index %q to exist", index)
+	}
+}
+
 func IndexMustNotExist(t *testing.T, db *sql.DB, schema, table, index string) {
 	t.Helper()
 	if indexExists(t, db, schema, table, index) {
@@ -357,6 +364,25 @@ func indexExists(t *testing.T, db *sql.DB, schema, table, index string) bool {
 	return exists
 }
 
+func indexDescendingExists(t *testing.T, db *sql.DB, schema, table, index string, columnIdx int) bool {
+	t.Helper()
+
+	var flags []uint8
+	err := db.QueryRow(`
+    SELECT indoption
+    FROM pg_index
+    WHERE indrelid = $1::regclass
+    AND indexrelid = $2::regclass`,
+		fmt.Sprintf("%s.%s", schema, table), fmt.Sprintf("%s.%s", schema, index)).Scan(&flags)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// check if index is descending using the 1st bit of the flags
+	indoptionDesc := uint8(1)
+	return flags[columnIdx]&indoptionDesc == 1
+}
+
 func CheckIndexDefinition(t *testing.T, db *sql.DB, schema, table, index, expectedDefinition string) {
 	t.Helper()
 
diff --git a/pkg/migrations/op_create_index.go b/pkg/migrations/op_create_index.go
@@ -34,9 +34,32 @@ func (o *OpCreateIndex) Start(ctx context.Context, conn db.DB, latestSchema stri
 		stmt += fmt.Sprintf(" USING %s", string(o.Method))
 	}
 
-	stmt += fmt.Sprintf(" (%s)", strings.Join(
-		quoteColumnNames(table.PhysicalColumnNamesFor(o.Columns...)), ", "),
-	)
+	colSQLs := make([]string, 0, len(o.Columns))
+	for columnName, settings := range map[string]IndexField(o.Columns) {
+		physicalName := table.PhysicalColumnNamesFor(columnName)
+		colSQL := pq.QuoteIdentifier(physicalName[0])
+		// deparse collations
+		if settings.Collate != "" {
+			colSQL += " COLLATE " + settings.Collate
+		}
+		// deparse operator classes and their parameters
+		if settings.Opclass != nil {
+			colSQL += " " + settings.Opclass.Name
+			if len(settings.Opclass.Params) > 0 {
+				colSQL += " " + strings.Join(settings.Opclass.Params, ", ")
+			}
+		}
+		// deparse sort order of the index column
+		if settings.Sort != "" {
+			colSQL += " " + string(settings.Sort)
+		}
+		// deparse nulls order of the index column
+		if settings.Nulls != nil {
+			colSQL += " " + string(*settings.Nulls)
+		}
+		colSQLs = append(colSQLs, colSQL)
+	}
+	stmt += fmt.Sprintf(" (%s)", strings.Join(colSQLs, ", "))
 
 	if o.StorageParameters != "" {
 		stmt += fmt.Sprintf(" WITH (%s)", o.StorageParameters)
@@ -77,7 +100,7 @@ func (o *OpCreateIndex) Validate(ctx context.Context, s *schema.Schema) error {
 		return TableDoesNotExistError{Name: o.Table}
 	}
 
-	for _, column := range o.Columns {
+	for column := range map[string]IndexField(o.Columns) {
 		if table.GetColumn(column) == nil {
 			return ColumnDoesNotExistError{Table: o.Table, Name: column}
 		}
diff --git a/pkg/migrations/op_create_index_test.go b/pkg/migrations/op_create_index_test.go
@@ -45,7 +45,7 @@ func TestCreateIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_users_name",
 							Table:   "users",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 						},
 					},
 				},
@@ -91,7 +91,7 @@ func TestCreateIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_USERS_name",
 							Table:   "users",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 						},
 					},
 				},
@@ -142,7 +142,7 @@ func TestCreateIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:      "idx_users_name_after_2019",
 							Table:     "users",
-							Columns:   []string{"registered_at_year"},
+							Columns:   map[string]migrations.IndexField{"registered_at_year": {}},
 							Predicate: "registered_at_year > 2019",
 						},
 					},
@@ -161,6 +161,56 @@ func TestCreateIndex(t *testing.T) {
 				// Complete is a no-op.
 			},
 		},
+		{
+			name: "create index with descending order",
+			migrations: []migrations.Migration{
+				{
+					Name: "01_add_table",
+					Operations: migrations.Operations{
+						&migrations.OpCreateTable{
+							Name: "users",
+							Columns: []migrations.Column{
+								{
+									Name: "id",
+									Type: "serial",
+									Pk:   true,
+								},
+								{
+									Name:     "name",
+									Type:     "varchar(255)",
+									Nullable: false,
+								},
+							},
+						},
+					},
+				},
+				{
+					Name: "02_create_index",
+					Operations: migrations.Operations{
+						&migrations.OpCreateIndex{
+							Name:  "idx_users_name",
+							Table: "users",
+							Columns: map[string]migrations.IndexField{
+								"name": {
+									Sort: migrations.IndexFieldSortDESC,
+								},
+							},
+						},
+					},
+				},
+			},
+			afterStart: func(t *testing.T, db *sql.DB, schema string) {
+				// The index has been created on the underlying table.
+				IndexDescendingMustExist(t, db, schema, "users", "idx_users_name", 0)
+			},
+			afterRollback: func(t *testing.T, db *sql.DB, schema string) {
+				// The index has been dropped from the the underlying table.
+				IndexMustNotExist(t, db, schema, "users", "idx_users_name")
+			},
+			afterComplete: func(t *testing.T, db *sql.DB, schema string) {
+				// Complete is a no-op.
+			},
+		},
 		{
 			name: "invalid name",
 			migrations: []migrations.Migration{
@@ -195,7 +245,7 @@ func TestCreateIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    invalidName,
 							Table:   "users",
-							Columns: []string{"registered_at_year"},
+							Columns: map[string]migrations.IndexField{"registered_at_year": {}},
 						},
 					},
 				},
@@ -234,7 +284,7 @@ func TestCreateIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:              "idx_users_name_hash",
 							Table:             "users",
-							Columns:           []string{"name"},
+							Columns:           map[string]migrations.IndexField{"name": {}},
 							Method:            migrations.OpCreateIndexMethodHash,
 							StorageParameters: "fillfactor = 70",
 						},
@@ -295,7 +345,7 @@ func TestCreateIndexOnMultipleColumns(t *testing.T) {
 					&migrations.OpCreateIndex{
 						Name:    "idx_users_name_email",
 						Table:   "users",
-						Columns: []string{"name", "email"},
+						Columns: map[string]migrations.IndexField{"name": {}, "email": {}},
 					},
 				},
 			},
@@ -350,7 +400,7 @@ func TestCreateIndexInMultiOperationMigrations(t *testing.T) {
 						},
 						&migrations.OpCreateIndex{
 							Table:   "products",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 							Name:    "idx_products_name",
 						},
 					},
@@ -406,7 +456,7 @@ func TestCreateIndexInMultiOperationMigrations(t *testing.T) {
 						},
 						&migrations.OpCreateIndex{
 							Table:   "products",
-							Columns: []string{"item_name"},
+							Columns: map[string]migrations.IndexField{"item_name": {}},
 							Name:    "idx_products_item_name",
 						},
 					},
@@ -449,7 +499,7 @@ func TestCreateIndexInMultiOperationMigrations(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_users_name",
 							Table:   "users",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 						},
 					},
 				},
@@ -505,7 +555,7 @@ func TestCreateIndexInMultiOperationMigrations(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_users_age",
 							Table:   "users",
-							Columns: []string{"age"},
+							Columns: map[string]migrations.IndexField{"age": {}},
 						},
 					},
 				},
diff --git a/pkg/migrations/op_drop_index_test.go b/pkg/migrations/op_drop_index_test.go
@@ -42,7 +42,7 @@ func TestDropIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_users_name",
 							Table:   "users",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 						},
 					},
 				},
@@ -96,7 +96,7 @@ func TestDropIndex(t *testing.T) {
 						&migrations.OpCreateIndex{
 							Name:    "idx_USERS_name",
 							Table:   "users",
-							Columns: []string{"name"},
+							Columns: map[string]migrations.IndexField{"name": {}},
 						},
 					},
 				},
diff --git a/pkg/migrations/types.go b/pkg/migrations/types.go
diff --git a/pkg/sql2pgroll/convert_test.go b/pkg/sql2pgroll/convert_test.go
diff --git a/pkg/sql2pgroll/create_index.go b/pkg/sql2pgroll/create_index.go
diff --git a/pkg/sql2pgroll/create_index_test.go b/pkg/sql2pgroll/create_index_test.go
diff --git a/pkg/sql2pgroll/expect/create_index.go b/pkg/sql2pgroll/expect/create_index.go
diff --git a/schema.json b/schema.json

Original file line number	Diff line number	Diff line change
`@@ -5,9 +5,9 @@`
`5`	`5`	`"create_index": {`
`6`	`6`	`"name": "idx_fruits_name",`
`7`	`7`	`"table": "fruits",`
`8`		`- "columns": [`
`9`		`- "name"`
`10`		`- ]`
	`8`	`+ "columns": {`
	`9`	`+ "name": {}`
	`10`	`+ }`
`11`	`11`	`}`
`12`	`12`	`}`
`13`	`13`	`]`
Original file line number	Diff line number	Diff line change
`@@ -5,9 +5,9 @@`
`5`	`5`	`"create_index": {`
`6`	`6`	`"name": "idx_fruits_id_gt_10",`
`7`	`7`	`"table": "fruits",`
`8`		`- "columns": [`
`9`		`- "id"`
`10`		`- ],`
	`8`	`+ "columns": {`
	`9`	`+ "id": {}`
	`10`	`+ },`
`11`	`11`	`"predicate": "id > 10"`
`12`	`12`	`}`
`13`	`13`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,9 +5,9 @@`
`5`	`5`	`"create_index": {`
`6`	`6`	`"name": "idx_fruits_unique_name",`
`7`	`7`	`"table": "fruits",`
`8`		`- "columns": [`
`9`		`- "name"`
`10`		`- ],`
	`8`	`+ "columns": {`
	`9`	`+ "name": {}`
	`10`	`+ },`
`11`	`11`	`"unique": true`
`12`	`12`	`}`
`13`	`13`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ require (`
`15`	`15`	`github.com/stretchr/testify v1.10.0`
`16`	`16`	`github.com/testcontainers/testcontainers-go v0.35.0`
`17`	`17`	`github.com/testcontainers/testcontainers-go/modules/postgres v0.35.0`
`18`		`- github.com/xataio/pg_query_go/v6 v6.0.0-20250124115938-4fa82ad6d036`
	`18`	`+ github.com/xataio/pg_query_go/v6 v6.0.0-20250226155420-277802e03678`
`19`	`19`	`golang.org/x/tools v0.30.0`
`20`	`20`	`)`
`21`	`21`