Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(schema/pg): canonical pg_get_indexdef shape for index expressions [BYT-9261] (#20009)

Danny Xu1521d4e860e1
diff --git a/backend/generated-go/store/database.pb.go b/backend/generated-go/store/database.pb.go
index f7812ff24e..62968f2677 100644
--- a/backend/generated-go/store/database.pb.go
+++ b/backend/generated-go/store/database.pb.go
@@ -3121,7 +3121,14 @@ type IndexMetadata struct {
// The name of the index.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// The expressions are the ordered columns or expressions of an index.
- // This could refer to a column or an expression.
+ //
+ // For PostgreSQL, the canonical shape for each entry matches
+ // pg_get_indexdef(oid, col, true) — the tightest `index_elem` grammar form:
+ // - column key: bare identifier e.g. "id", `"Name"`
+ // - function-call key: bare func_expr_windowless e.g. "lower(name)"
+ // - expression key: parenthesized a_expr e.g. "(payload ->> 'k'::text)"
+ //
+ // The DDL emitter writes entries verbatim into the CREATE INDEX key list.
Expressions []string `protobuf:"bytes,2,rep,name=expressions,proto3" json:"expressions,omitempty"`
// The ordered list of key lengths for the index.
// If the key length is not specified, it is -1.
diff --git a/backend/plugin/schema/pg/get_database_definition.go b/backend/plugin/schema/pg/get_database_definition.go
index 2058e80bf7..fbc8cc8a39 100644
--- a/backend/plugin/schema/pg/get_database_definition.go
+++ b/backend/plugin/schema/pg/get_database_definition.go
@@ -7,6 +7,7 @@ import (
"strings"
"github.com/pkg/errors"
+ "google.golang.org/protobuf/proto"
omnipg "github.com/bytebase/omni/pg"
"github.com/bytebase/omni/pg/ast"
@@ -51,6 +52,17 @@ func init() {
func GetDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *storepb.DatabaseSchemaMetadata) (string, error) {
metadata = filterBackupSchemaIfNecessary(ctx, metadata)
+ // Clone before mutating: the caller's *DatabaseSchemaMetadata is often a
+ // shared pointer returned from store.dbSchemaCache (see
+ // backend/store/model/database.go:GetProto), so concurrent callers could
+ // race on in-place normalization writes below.
+ metadata = proto.CloneOf(metadata)
+
+ // Repair historical non-canonical metadata shapes (e.g. index key
+ // expressions stored without outer parens) so emission produces valid SQL.
+ // See legacy_normalize.go for removal criteria.
+ normalizeLegacyMetadata(metadata)
+
if len(metadata.Schemas) == 0 {
return "", nil
}
@@ -1946,6 +1958,10 @@ func writeIndexKeyList(out io.Writer, index *storepb.IndexMetadata) error {
}
}
+ // expression is expected to be in canonical pg_get_indexdef form —
+ // see IndexMetadata.expressions in proto/store/store/database.proto.
+ // normalizeLegacyMetadata (called at the top of GetDatabaseDefinition)
+ // repairs historical rows that pre-date the contract.
if _, err := io.WriteString(out, expression); err != nil {
return err
}
@@ -3601,6 +3617,17 @@ func writeForeignKeyConstraintSDL(out io.Writer, fk *storepb.ForeignKeyMetadata)
func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *storepb.DatabaseSchemaMetadata) (*schema.MultiFileSchemaResult, error) {
metadata = filterBackupSchemaIfNecessary(ctx, metadata)
+ // Clone before mutating: the caller's *DatabaseSchemaMetadata is often a
+ // shared pointer returned from store.dbSchemaCache (see
+ // backend/store/model/database.go:GetProto), so concurrent callers could
+ // race on in-place normalization writes below.
+ metadata = proto.CloneOf(metadata)
+
+ // Repair historical non-canonical metadata shapes (e.g. index key
+ // expressions stored without outer parens) so emission produces valid SQL.
+ // See legacy_normalize.go for removal criteria.
+ normalizeLegacyMetadata(metadata)
+
if len(metadata.Schemas) == 0 {
return &schema.MultiFileSchemaResult{Files: []schema.File{}}, nil
}
diff --git a/backend/plugin/schema/pg/legacy_normalize.go b/backend/plugin/schema/pg/legacy_normalize.go
new file mode 100644
index 0000000000..50a8fb441e
--- /dev/null
+++ b/backend/plugin/schema/pg/legacy_normalize.go
@@ -0,0 +1,292 @@
+// This file repairs historical PostgreSQL metadata that violates the canonical
+// shape documented by IndexMetadata.expressions in
+// proto/store/store/database.proto.
+//
+// Canonical shape (matches pg_get_indexdef(oid, col, true) per-column output):
+// - column key: bare identifier, e.g. "id", `"Name"`
+// - function-call key: bare func_expr_windowless, e.g. "lower(name)"
+// - expression key: parenthesized a_expr, e.g. "(payload ->> 'k'::text)"
+//
+// That form is exactly PostgreSQL's `index_elem` grammar alternative, so the
+// emitter can write entries verbatim into a CREATE INDEX key list.
+//
+// The BYT-9261 reproducer (demo metadata for the bytebase-meta DB) stores
+// expression keys without the required outer parens — an older sync code path
+// stripped them before persisting. The emitter writing those verbatim produces
+// invalid SQL ("CREATE INDEX ... (payload ->> 'k')") which both PostgreSQL and
+// the omni parser reject ("syntax error at or near \"->>\"").
+//
+// normalizeLegacyMetadata re-canonicalizes such rows on read so the emitter
+// can rely on the contract.
+//
+// Removal criteria — this file can be deleted when:
+// 1. A one-time migrator has rewritten db_schema.metadata rows to canonical
+// shape (straightforward: run the canonicalizer over each row's
+// IndexMetadata.Expressions and UPSERT); AND
+// 2. at least one release containing the migrator has been out for 30+ days.
+// Tracked by BYT-9261 follow-up.
+
+package pg
+
+import (
+ "regexp"
+ "strings"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+)
+
+// normalizeLegacyMetadata mutates meta in place to match the canonical
+// IndexMetadata.expressions contract. Idempotent and cheap on canonical input.
+func normalizeLegacyMetadata(meta *storepb.DatabaseSchemaMetadata) {
+ if meta == nil {
+ return
+ }
+ for _, s := range meta.GetSchemas() {
+ for _, t := range s.GetTables() {
+ canonicalizeIndexExpressions(t.GetIndexes())
+ for _, p := range t.GetPartitions() {
+ canonicalizePartitionIndexes(p)
+ }
+ }
+ for _, mv := range s.GetMaterializedViews() {
+ canonicalizeIndexExpressions(mv.GetIndexes())
+ }
+ }
+}
+
+func canonicalizePartitionIndexes(p *storepb.TablePartitionMetadata) {
+ if p == nil {
+ return
+ }
+ canonicalizeIndexExpressions(p.GetIndexes())
+ for _, sub := range p.GetSubpartitions() {
+ canonicalizePartitionIndexes(sub)
+ }
+}
+
+func canonicalizeIndexExpressions(indexes []*storepb.IndexMetadata) {
+ for _, idx := range indexes {
+ for i, expr := range idx.Expressions {
+ idx.Expressions[i] = canonicalizeIndexKeyExpression(expr)
+ }
+ }
+}
+
+// canonicalizeIndexKeyExpression repairs a single index key expression into
+// the canonical pg_get_indexdef shape:
+//
+// - bare column identifier → returned unchanged
+// - bare function call → returned unchanged
+// - anything else → wrapped in a single pair of '(' ')'
+//
+// Any redundant outer parens in the input are collapsed first, so
+// "((payload ->> 'k'))" and "payload ->> 'k'" both produce "(payload ->> 'k')".
+//
+// Idempotent: canonical input round-trips unchanged.
+func canonicalizeIndexKeyExpression(s string) string {
+ s = strings.TrimSpace(s)
+ // Collapse any fully-matched outer parens — covers both legacy stripped
+ // expressions ("expr", no parens to strip) and over-wrapped ones
+ // ("((expr))", strip twice).
+ for {
+ stripped, ok := stripMatchedOuterParens(s)
+ if !ok {
+ break
+ }
+ s = strings.TrimSpace(stripped)
+ }
+ if s == "" {
+ return s
+ }
+ // Canonical bare forms are emitted as-is.
+ if isBareColumnIdent(s) || isBareFunctionCall(s) {
+ return s
+ }
+ // Everything else is an a_expr and must be parenthesized per PG's
+ // index_elem grammar.
+ return "(" + s + ")"
+}
+
+// stripMatchedOuterParens returns s without its outermost '(' ')' pair iff
+// those parens enclose the entire expression. Single- and double-quoted
+// strings are respected so parens inside literals don't confuse matching.
+func stripMatchedOuterParens(s string) (string, bool) {
+ if len(s) < 2 || s[0] != '(' || s[len(s)-1] != ')' {
+ return s, false
+ }
+ depth := 0
+ inSingle := false
+ inDouble := false
+ for i := 0; i < len(s); i++ {
+ c := s[i]
+ switch {
+ case inSingle:
+ if c == '\'' {
+ if i+1 < len(s) && s[i+1] == '\'' {
+ i++
+ } else {
+ inSingle = false
+ }
+ }
+ case inDouble:
+ if c == '"' {
+ if i+1 < len(s) && s[i+1] == '"' {
+ i++
+ } else {
+ inDouble = false
+ }
+ }
+ case c == '\'':
+ inSingle = true
+ case c == '"':
+ inDouble = true
+ case c == '(':
+ depth++
+ case c == ')':
+ depth--
+ if depth == 0 && i != len(s)-1 {
+ // Opening '(' at index 0 closed before end of string —
+ // outer parens don't enclose the whole expression.
+ return s, false
+ }
+ default:
+ // Any other character is ignored.
+ }
+ }
+ if depth != 0 {
+ return s, false
+ }
+ return s[1 : len(s)-1], true
+}
+
+// reBareColumnIdent matches an unquoted simple identifier. PostgreSQL allows
+// Unicode letters and `$` (after the first character) in unquoted identifiers
+// — e.g. `col$1`, `naïve`. We mirror that because otherwise such columns would
+// be wrapped as expression keys and break PRIMARY KEY / UNIQUE constraint
+// emission, which require bare column identifiers, not expression keys.
+var reBareColumnIdent = regexp.MustCompile(`^[\p{L}_][\p{L}\p{N}_$]*$`)
+
+// isBareColumnIdent reports whether s is a simple identifier — either unquoted
+// (`name`) or double-quoted (`"Name"`, `"has ""quote"" inside"`).
+func isBareColumnIdent(s string) bool {
+ s = strings.TrimSpace(s)
+ if reBareColumnIdent.MatchString(s) {
+ return true
+ }
+ if len(s) < 2 || s[0] != '"' || s[len(s)-1] != '"' {
+ return false
+ }
+ inner := s[1 : len(s)-1]
+ if inner == "" {
+ return false
+ }
+ for i := 0; i < len(inner); i++ {
+ if inner[i] != '"' {
+ continue
+ }
+ if i+1 < len(inner) && inner[i+1] == '"' {
+ i++
+ continue
+ }
+ return false
+ }
+ return true
+}
+
+// isBareFunctionCall reports whether s is a bare function call — an identifier
+// (optionally schema-qualified) directly followed by a parenthesized argument
+// list that extends to and balances at the end of s. This is the shape
+// pg_get_indexdef returns for function-call index keys like `lower(name)` or
+// `tst.foo(a, b)`.
+//
+// Critically, the opening '(' after the identifier must match the LAST ')' in
+// s. Otherwise a compound expression like `lower(name) + abs(score)` — which
+// also starts with `ident(` and ends with `)` — would be misclassified as a
+// bare call, and a legacy stripped-parens entry would be emitted unwrapped,
+// producing invalid CREATE INDEX SQL.
+func isBareFunctionCall(s string) bool {
+ s = strings.TrimSpace(s)
+ if s == "" || !isIdentStart(s[0]) {
+ return false
+ }
+ i := scanIdent(s, 0)
+ // Optional schema qualifier: ".ident"
+ if i < len(s) && s[i] == '.' {
+ if j := scanIdent(s, i+1); j > i+1 {
+ i = j
+ } else {
+ return false
+ }
+ }
+ // Optional whitespace between name and '('
+ for i < len(s) && (s[i] == ' ' || s[i] == '\t') {
+ i++
+ }
+ if i >= len(s) || s[i] != '(' {
+ return false
+ }
+ if !strings.HasSuffix(s, ")") {
+ return false
+ }
+ // Verify the '(' at position i pairs with the ')' at len(s)-1, accounting
+ // for nested parens and string literals.
+ depth := 0
+ inSingle := false
+ inDouble := false
+ for j := i; j < len(s); j++ {
+ c := s[j]
+ switch {
+ case inSingle:
+ if c == '\'' {
+ if j+1 < len(s) && s[j+1] == '\'' {
+ j++
+ } else {
+ inSingle = false
+ }
+ }
+ case inDouble:
+ if c == '"' {
+ if j+1 < len(s) && s[j+1] == '"' {
+ j++
+ } else {
+ inDouble = false
+ }
+ }
+ case c == '\'':
+ inSingle = true
+ case c == '"':
+ inDouble = true
+ case c == '(':
+ depth++
+ case c == ')':
+ depth--
+ if depth == 0 {
+ return j == len(s)-1
+ }
+ default:
+ // Any other character is ignored.
+ }
+ }
+ return false
+}
+
+func isIdentStart(b byte) bool {
+ return (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || b == '_'
+}
+
+func isIdentCont(b byte) bool {
+ return isIdentStart(b) || (b >= '0' && b <= '9')
+}
+
+// scanIdent returns the index after the identifier starting at pos, or pos if
+// there is no identifier at pos.
+func scanIdent(s string, pos int) int {
+ if pos >= len(s) || !isIdentStart(s[pos]) {
+ return pos
+ }
+ i := pos + 1
+ for i < len(s) && isIdentCont(s[i]) {
+ i++
+ }
+ return i
+}
diff --git a/backend/plugin/schema/pg/legacy_normalize_test.go b/backend/plugin/schema/pg/legacy_normalize_test.go
new file mode 100644
index 0000000000..b0ad3c5928
--- /dev/null
+++ b/backend/plugin/schema/pg/legacy_normalize_test.go
@@ -0,0 +1,401 @@
+package pg
+
+import (
+ "strings"
+ "testing"
+
+ omnipg "github.com/bytebase/omni/pg"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/schema"
+)
+
+func TestStripMatchedOuterParens(t *testing.T) {
+ cases := []struct {
+ in string
+ want string
+ stripped bool
+ }{
+ {"(a)", "a", true},
+ {"(payload ->> 'k'::text)", "payload ->> 'k'::text", true},
+ {"((a))", "(a)", true},
+ {"(a + b)", "a + b", true},
+ {"a + b", "a + b", false},
+ {"(a)+(b)", "(a)+(b)", false},
+ {"('(' || name || ')')", "'(' || name || ')'", true},
+ {`("name" || ' x')`, `"name" || ' x'`, true},
+ {"(", "(", false},
+ {")", ")", false},
+ {"", "", false},
+ {"(a", "(a", false},
+ {"a)", "a)", false},
+ }
+ for _, c := range cases {
+ got, ok := stripMatchedOuterParens(c.in)
+ if got != c.want || ok != c.stripped {
+ t.Errorf("stripMatchedOuterParens(%q) = (%q, %v); want (%q, %v)",
+ c.in, got, ok, c.want, c.stripped)
+ }
+ }
+}
+
+func TestIsBareColumnIdent(t *testing.T) {
+ cases := []struct {
+ s string
+ want bool
+ }{
+ {"name", true},
+ {" name ", true},
+ {"_col", true},
+ {"col1", true},
+ // PostgreSQL allows `$` in unquoted identifiers after the first
+ // character. Columns like `col$1` must be classified as bare
+ // identifiers — otherwise PK/UNIQUE constraint emission on such
+ // columns would wrap them as expression keys, which PG rejects.
+ // Codex review (PR #20009).
+ {"col$1", true},
+ {"a$b$c", true},
+ {"$col", false}, // leading '$' is not allowed
+ // PostgreSQL also allows Unicode letters in unquoted identifiers.
+ // Misclassifying these as expressions would break PK/UNIQUE emission
+ // on columns like `naïve`. Codex review (PR #20009).
+ {"naïve", true},
+ {"café", true},
+ {"名前", true},
+ {"1col", false}, // digit start still rejected
+ {`"Name"`, true},
+ {`"has ""quote"" inside"`, true},
+ {"name + 1", false},
+ {"payload ->> 'k'", false},
+ {"(name)", false},
+ {"lower(name)", false},
+ {"name.other", false},
+ {"1name", false},
+ {"", false},
+ {`""`, false},
+ {`"a`, false},
+ {`a"`, false},
+ }
+ for _, c := range cases {
+ if got := isBareColumnIdent(c.s); got != c.want {
+ t.Errorf("isBareColumnIdent(%q) = %v; want %v", c.s, got, c.want)
+ }
+ }
+}
+
+func TestIsBareFunctionCall(t *testing.T) {
+ cases := []struct {
+ s string
+ want bool
+ }{
+ {"lower(name)", true},
+ {"coalesce(a, b)", true},
+ {"substring(name, 1, 3)", true},
+ {"public.foo(a)", true},
+ {"lower (name)", true}, // whitespace before '(' is allowed
+ {" lower(name) ", true}, // surrounding whitespace trimmed
+ {"name", false}, // bare ident, not a call
+ {"name + 1", false}, // operator expression
+ {"(lower(name))", false}, // outer parens — not bare
+ {"lower(name) + 1", false}, // not terminated with ')'
+ {"(name)", false}, // starts with '('
+ {"", false},
+ {"1lower(name)", false}, // digit start
+ // Compound expressions that happen to end with ')' — the '(' after
+ // the leading ident does NOT match the trailing ')'. Misclassifying
+ // these as bare calls would leave legacy stripped-parens entries
+ // unwrapped, producing invalid CREATE INDEX SQL. Codex review
+ // (PR #20009 r3082599144).
+ {"lower(name) + abs(score)", false},
+ {"abs(x) - abs(y)", false},
+ {"f() OR g()", false},
+ {"coalesce(a, b) || coalesce(c, d)", false},
+ // True nested-call cases stay correctly classified.
+ {"coalesce(lower(name), upper(name))", true},
+ {"f(g(h(x)))", true},
+ }
+ for _, c := range cases {
+ if got := isBareFunctionCall(c.s); got != c.want {
+ t.Errorf("isBareFunctionCall(%q) = %v; want %v", c.s, got, c.want)
+ }
+ }
+}
+
+func TestCanonicalizeIndexKeyExpression(t *testing.T) {
+ cases := []struct {
+ in, want string
+ }{
+ // Canonical forms — round-trip unchanged.
+ {"id", "id"},
+ {`"Name"`, `"Name"`},
+ {"lower(name)", "lower(name)"},
+ {"coalesce(a, b)", "coalesce(a, b)"},
+ {"(payload ->> 'k'::text)", "(payload ->> 'k'::text)"},
+ {"(id + 1)", "(id + 1)"},
+ {"(name::text)", "(name::text)"},
+
+ // Legacy stripped-parens expressions — wrap.
+ {"payload ->> 'k'::text", "(payload ->> 'k'::text)"},
+ {"id + 1", "(id + 1)"},
+ {"name::text", "(name::text)"},
+ {"a || b || c", "(a || b || c)"},
+ {"a @> b", "(a @> b)"},
+
+ // Over-wrapped — collapse to single pair.
+ {"((payload ->> 'k'))", "(payload ->> 'k')"},
+ {"((id + 1))", "(id + 1)"},
+ {"(lower(name))", "lower(name)"}, // stripped → bare func call
+
+ // Whitespace tolerance.
+ {" id ", "id"},
+ {" (a + b) ", "(a + b)"},
+
+ // Compound expressions involving function calls — must wrap, even
+ // though the input starts with `ident(` and ends with `)`.
+ // PR #20009 r3082599144.
+ {"lower(name) + abs(score)", "(lower(name) + abs(score))"},
+ {"abs(x) - abs(y)", "(abs(x) - abs(y))"},
+ {"f() OR g()", "(f() OR g())"},
+
+ // Empty / edge.
+ {"", ""},
+ }
+ for _, c := range cases {
+ if got := canonicalizeIndexKeyExpression(c.in); got != c.want {
+ t.Errorf("canonicalizeIndexKeyExpression(%q) = %q; want %q", c.in, got, c.want)
+ }
+ }
+}
+
+// TestIndexEmissionParses is the regression lock for BYT-9261: for every
+// expression family that can appear in a functional index, the DDL produced by
+// GetDatabaseDefinition must parse cleanly through omni — whether the stored
+// form is canonical (pg_get_indexdef-native) or legacy (stripped parens).
+func TestIndexEmissionParses(t *testing.T) {
+ exprs := []string{
+ // Identifier keys — stored bare, emitted bare.
+ "name",
+ `"Name"`,
+ // Function-call keys — stored bare, emitted bare.
+ "lower(name)",
+ "coalesce(a, b)",
+ // Operator/expression keys — canonical form is parenthesized. Legacy
+ // data strips the parens.
+ "payload ->> 'k'::text",
+ "payload -> 'k'",
+ "payload #> '{a,b}'",
+ "payload #>> '{a,b}'",
+ "name::text",
+ "first_name || ' ' || last_name",
+ "a + 1",
+ "a - b",
+ "a = 1",
+ "name ~ '^foo'",
+ "name ~* 'foo'",
+ `payload @> '{"k":1}'::jsonb`,
+ "tags <@ ARRAY['a','b']",
+ }
+
+ for _, expr := range exprs {
+ shapes := []struct {
+ name, stored string
+ }{
+ {"bare (legacy or identifier/func)", expr},
+ {"parenthesized (canonical for expressions)", "(" + expr + ")"},
+ }
+ for _, shape := range shapes {
+ meta := &storepb.DatabaseSchemaMetadata{
+ Name: "db",
+ Schemas: []*storepb.SchemaMetadata{{
+ Name: "public",
+ Tables: []*storepb.TableMetadata{{
+ Name: "t",
+ Columns: []*storepb.ColumnMetadata{
+ {Name: "a", Position: 1, Type: "integer"},
+ {Name: "b", Position: 2, Type: "integer"},
+ {Name: "name", Position: 3, Type: "text"},
+ {Name: "first_name", Position: 4, Type: "text"},
+ {Name: "last_name", Position: 5, Type: "text"},
+ {Name: "tags", Position: 6, Type: "text[]"},
+ {Name: "payload", Position: 7, Type: "jsonb"},
+ },
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "idx",
+ Type: "btree",
+ Expressions: []string{shape.stored},
+ }},
+ }},
+ }},
+ }
+ ddl, err := GetDatabaseDefinition(schema.GetDefinitionContext{}, meta)
+ if err != nil {
+ t.Fatalf("GetDatabaseDefinition(expr=%q, shape=%s): %v", expr, shape.name, err)
+ }
+ if _, err := omnipg.Parse(ddl); err != nil {
+ t.Errorf("omni parse failed for expr=%q shape=%s:\n DDL: %s\n err: %v",
+ expr, shape.name, indexLine(ddl), err)
+ }
+ }
+ }
+}
+
+// TestNormalizeLegacyMetadata_PartitionAndMV locks the traversal of
+// TablePartitionMetadata.Indexes (including nested Subpartitions) and
+// MaterializedViewMetadata.Indexes — which are structurally easy to miss.
+func TestNormalizeLegacyMetadata_PartitionAndMV(t *testing.T) {
+ meta := &storepb.DatabaseSchemaMetadata{
+ Name: "db",
+ Schemas: []*storepb.SchemaMetadata{{
+ Name: "public",
+ Tables: []*storepb.TableMetadata{{
+ Name: "t",
+ Partitions: []*storepb.TablePartitionMetadata{{
+ Name: "t_p1",
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "partition_idx",
+ Expressions: []string{"payload ->> 'k'::text"}, // legacy: no parens
+ }},
+ Subpartitions: []*storepb.TablePartitionMetadata{{
+ Name: "t_p1_sub",
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "subpartition_idx",
+ Expressions: []string{"a + b"}, // legacy: no parens
+ }},
+ }},
+ }},
+ }},
+ MaterializedViews: []*storepb.MaterializedViewMetadata{{
+ Name: "mv",
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "mv_idx",
+ Expressions: []string{"lower(name)"}, // canonical: bare func call
+ }},
+ }},
+ }},
+ }
+
+ normalizeLegacyMetadata(meta)
+
+ got := []string{
+ meta.Schemas[0].Tables[0].Partitions[0].Indexes[0].Expressions[0],
+ meta.Schemas[0].Tables[0].Partitions[0].Subpartitions[0].Indexes[0].Expressions[0],
+ meta.Schemas[0].MaterializedViews[0].Indexes[0].Expressions[0],
+ }
+ want := []string{
+ "(payload ->> 'k'::text)", // wrapped
+ "(a + b)", // wrapped
+ "lower(name)", // unchanged
+ }
+ for i := range got {
+ if got[i] != want[i] {
+ t.Errorf("slot %d: got %q, want %q", i, got[i], want[i])
+ }
+ }
+}
+
+// TestGetMultiFileDatabaseDefinition_LegacyIndexExpressionsParse locks the
+// multi-file / SDL export path: legacy stripped-parens expressions stored on
+// tables, partitions, and materialized views must all emit as parseable SQL
+// through GetMultiFileDatabaseDefinition, which has its own entry point and
+// was previously missing the normalization pass (Codex review, PR #20009).
+func TestGetMultiFileDatabaseDefinition_LegacyIndexExpressionsParse(t *testing.T) {
+ meta := &storepb.DatabaseSchemaMetadata{
+ Name: "db",
+ Schemas: []*storepb.SchemaMetadata{{
+ Name: "public",
+ Tables: []*storepb.TableMetadata{{
+ Name: "t",
+ Columns: []*storepb.ColumnMetadata{
+ {Name: "a", Position: 1, Type: "integer"},
+ {Name: "b", Position: 2, Type: "integer"},
+ {Name: "payload", Position: 3, Type: "jsonb"},
+ },
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "t_legacy_idx",
+ Type: "btree",
+ Expressions: []string{"payload ->> 'k'::text"}, // legacy
+ }},
+ Partitions: []*storepb.TablePartitionMetadata{{
+ Name: "t_p1",
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "t_p1_legacy_idx",
+ Type: "btree",
+ Expressions: []string{"a + b"}, // legacy
+ }},
+ }},
+ }},
+ MaterializedViews: []*storepb.MaterializedViewMetadata{{
+ Name: "mv",
+ Definition: "SELECT 1 AS x",
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "mv_legacy_idx",
+ Type: "btree",
+ Expressions: []string{"payload ->> 'k'::text"}, // legacy
+ }},
+ }},
+ }},
+ }
+
+ result, err := GetMultiFileDatabaseDefinition(schema.GetDefinitionContext{}, meta)
+ if err != nil {
+ t.Fatalf("GetMultiFileDatabaseDefinition: %v", err)
+ }
+
+ var sawIndex bool
+ for _, f := range result.Files {
+ if !strings.Contains(f.Content, "CREATE INDEX") && !strings.Contains(f.Content, "CREATE UNIQUE INDEX") {
+ continue
+ }
+ sawIndex = true
+ if _, err := omnipg.Parse(f.Content); err != nil {
+ t.Errorf("omni parse failed for %s:\n%s\nerr: %v", f.Name, f.Content, err)
+ }
+ }
+ if !sawIndex {
+ t.Fatal("no CREATE INDEX emitted in multi-file output; test setup is wrong")
+ }
+}
+
+// TestGetDatabaseDefinition_DoesNotMutateInput guards the proto.Clone at the
+// top of GetDatabaseDefinition. The caller's metadata (often a shared pointer
+// from store.dbSchemaCache) must not be altered by the normalization pass.
+func TestGetDatabaseDefinition_DoesNotMutateInput(t *testing.T) {
+ meta := &storepb.DatabaseSchemaMetadata{
+ Name: "db",
+ Schemas: []*storepb.SchemaMetadata{{
+ Name: "public",
+ Tables: []*storepb.TableMetadata{{
+ Name: "t",
+ Columns: []*storepb.ColumnMetadata{
+ {Name: "payload", Position: 1, Type: "jsonb"},
+ },
+ Indexes: []*storepb.IndexMetadata{{
+ Name: "idx",
+ Type: "btree",
+ // Deliberately non-canonical: the normalizer would rewrite this.
+ Expressions: []string{"payload ->> 'k'"},
+ }},
+ }},
+ }},
+ }
+ before := meta.Schemas[0].Tables[0].Indexes[0].Expressions[0]
+
+ if _, err := GetDatabaseDefinition(schema.GetDefinitionContext{}, meta); err != nil {
+ t.Fatal(err)
+ }
+
+ after := meta.Schemas[0].Tables[0].Indexes[0].Expressions[0]
+ if before != after {
+ t.Errorf("caller's metadata was mutated: before=%q, after=%q", before, after)
+ }
+}
+
+func indexLine(ddl string) string {
+ for ln := range strings.SplitSeq(ddl, "\n") {
+ trimmed := strings.TrimSpace(ln)
+ if strings.HasPrefix(trimmed, "CREATE INDEX") || strings.HasPrefix(trimmed, "CREATE UNIQUE INDEX") {
+ return trimmed
+ }
+ }
+ return ""
+}
diff --git a/proto/gen/grpc-doc/store/README.md b/proto/gen/grpc-doc/store/README.md
index 22b9d15545..f4a1f07597 100644
--- a/proto/gen/grpc-doc/store/README.md
+++ b/proto/gen/grpc-doc/store/README.md
@@ -1351,7 +1351,9 @@ IndexMetadata is the metadata for indexes.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | [string](#string) | | The name of the index. |
-| expressions | [string](#string) | repeated | The expressions are the ordered columns or expressions of an index. This could refer to a column or an expression. |
+| expressions | [string](#string) | repeated | The expressions are the ordered columns or expressions of an index.
+
+For PostgreSQL, the canonical shape for each entry matches pg_get_indexdef(oid, col, true) — the tightest `index_elem` grammar form: - column key: bare identifier e.g. &#34;id&#34;, `&#34;Name&#34;` - function-call key: bare func_expr_windowless e.g. &#34;lower(name)&#34; - expression key: parenthesized a_expr e.g. &#34;(payload -&gt;&gt; &#39;k&#39;::text)&#34; The DDL emitter writes entries verbatim into the CREATE INDEX key list. |
| key_length | [int64](#int64) | repeated | The ordered list of key lengths for the index. If the key length is not specified, it is -1. |
| descending | [bool](#bool) | repeated | The ordered list of descending flags for the index columns. |
| type | [string](#string) | | The type is the type of an index. |
diff --git a/proto/gen/grpc-doc/store/index.html b/proto/gen/grpc-doc/store/index.html
index 97d17eb18f..e1639d02b4 100644
--- a/proto/gen/grpc-doc/store/index.html
+++ b/proto/gen/grpc-doc/store/index.html
@@ -4207,7 +4207,13 @@ For PostgreSQL, it&#39;s the list of tables that the function depends on the ret
<td><a href="#string">string</a></td>
<td>repeated</td>
<td><p>The expressions are the ordered columns or expressions of an index.
-This could refer to a column or an expression. </p></td>
+
+For PostgreSQL, the canonical shape for each entry matches
+pg_get_indexdef(oid, col, true) — the tightest `index_elem` grammar form:
+ - column key: bare identifier e.g. &#34;id&#34;, `&#34;Name&#34;`
+ - function-call key: bare func_expr_windowless e.g. &#34;lower(name)&#34;
+ - expression key: parenthesized a_expr e.g. &#34;(payload -&gt;&gt; &#39;k&#39;::text)&#34;
+The DDL emitter writes entries verbatim into the CREATE INDEX key list. </p></td>
</tr>
<tr>
diff --git a/proto/store/store/database.proto b/proto/store/store/database.proto
index d3d755b49d..a343fe31d8 100644
--- a/proto/store/store/database.proto
+++ b/proto/store/store/database.proto
@@ -712,7 +712,13 @@ message IndexMetadata {
string name = 1;
// The expressions are the ordered columns or expressions of an index.
- // This could refer to a column or an expression.
+ //
+ // For PostgreSQL, the canonical shape for each entry matches
+ // pg_get_indexdef(oid, col, true) — the tightest `index_elem` grammar form:
+ // - column key: bare identifier e.g. "id", `"Name"`
+ // - function-call key: bare func_expr_windowless e.g. "lower(name)"
+ // - expression key: parenthesized a_expr e.g. "(payload ->> 'k'::text)"
+ // The DDL emitter writes entries verbatim into the CREATE INDEX key list.
repeated string expressions = 2;
// The ordered list of key lengths for the index.