Skip to content

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

feat: support comments for sdl (#17803)

rebelice6faf76db4c97
diff --git a/backend/plugin/schema/pg/get_database_definition.go b/backend/plugin/schema/pg/get_database_definition.go
index 38219c2a26..2b51d83370 100644
--- a/backend/plugin/schema/pg/get_database_definition.go
+++ b/backend/plugin/schema/pg/get_database_definition.go
@@ -2149,6 +2149,13 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
if err := writeSchema(&buf, schema); err != nil {
return "", err
}
+
+ // Write schema comment if present
+ if len(schema.Comment) > 0 {
+ if err := writeSchemaCommentSDL(&buf, schema); err != nil {
+ return "", err
+ }
+ }
}
// Build a map of serial and identity sequences that should be skipped
@@ -2215,6 +2222,14 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
if _, err := buf.WriteString(";\n\n"); err != nil {
return "", err
}
+
+ // Write sequence comment if present
+ if len(sequence.Comment) > 0 {
+ if err := writeSequenceCommentSDL(&buf, schema.Name, sequence); err != nil {
+ return "", err
+ }
+ }
+
// Track sequences with owners for later ownership establishment
if sequence.OwnerTable != "" && sequence.OwnerColumn != "" {
tableID := getObjectID(schema.Name, sequence.OwnerTable)
@@ -2264,10 +2279,38 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
return "", err
}
+ // Write table comment if present
+ if len(table.Comment) > 0 {
+ if err := writeTableCommentSDL(&buf, schema.Name, table); err != nil {
+ return "", err
+ }
+ }
+
+ // Write column comments if present
+ for _, column := range table.Columns {
+ if len(column.Comment) > 0 {
+ if err := writeColumnCommentSDL(&buf, schema.Name, table.Name, column); err != nil {
+ return "", err
+ }
+ }
+ }
+
// Write CREATE INDEX statements for non-constraint indexes
if err := writeIndexesSDL(&buf, schema.Name, table); err != nil {
return "", err
}
+
+ // Write index comments if present
+ for _, index := range table.Indexes {
+ // Only write comment for standalone indexes (not primary key or unique constraint indexes)
+ if !index.Primary && !index.Unique {
+ if len(index.Comment) > 0 {
+ if err := writeIndexCommentSDL(&buf, schema.Name, index); err != nil {
+ return "", err
+ }
+ }
+ }
+ }
}
// Write ALTER SEQUENCE OWNED BY statements for sequences that have owners
@@ -2302,6 +2345,13 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
if _, err := buf.WriteString(";\n\n"); err != nil {
return "", err
}
+
+ // Write view comment if present
+ if len(view.Comment) > 0 {
+ if err := writeViewCommentSDL(&buf, schema.Name, view); err != nil {
+ return "", err
+ }
+ }
}
// Write functions and procedures after views
@@ -2317,6 +2367,13 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
if _, err := buf.WriteString(";\n\n"); err != nil {
return "", err
}
+
+ // Write function comment if present
+ if len(function.Comment) > 0 {
+ if err := writeFunctionCommentSDL(&buf, schema.Name, function); err != nil {
+ return "", err
+ }
+ }
}
}
@@ -3079,6 +3136,14 @@ func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *s
}
buf.WriteString(";\n")
+ // Add sequence comment if present
+ if len(sequence.Comment) > 0 {
+ buf.WriteString("\n")
+ if err := writeSequenceCommentSDL(&buf, schemaName, sequence); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate sequence comment for %s.%s", schemaName, sequence.Name)
+ }
+ }
+
// Add ALTER SEQUENCE OWNED BY for sequences with owners
if sequence.OwnerTable != "" && sequence.OwnerColumn != "" {
buf.WriteString("\n")
@@ -3110,11 +3175,39 @@ func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *s
}
buf.WriteString(";\n\n")
+ // Write table comment if present
+ if len(table.Comment) > 0 {
+ if err := writeTableCommentSDL(&buf, schemaName, table); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate table comment for %s.%s", schemaName, table.Name)
+ }
+ }
+
+ // Write column comments if present
+ for _, column := range table.Columns {
+ if len(column.Comment) > 0 {
+ if err := writeColumnCommentSDL(&buf, schemaName, table.Name, column); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate column comment for %s.%s.%s", schemaName, table.Name, column.Name)
+ }
+ }
+ }
+
// Write CREATE INDEX statements for non-constraint indexes
if err := writeIndexesSDL(&buf, schemaName, table); err != nil {
return nil, errors.Wrapf(err, "failed to generate indexes SDL for %s.%s", schemaName, table.Name)
}
+ // Write index comments if present
+ for _, index := range table.Indexes {
+ // Only write comment for standalone indexes (not primary key or unique constraint indexes)
+ if !index.Primary && !index.Unique {
+ if len(index.Comment) > 0 {
+ if err := writeIndexCommentSDL(&buf, schemaName, index); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate index comment for %s.%s", schemaName, index.Name)
+ }
+ }
+ }
+ }
+
files = append(files, schema.File{
Name: fmt.Sprintf("schemas/%s/tables/%s.sql", schemaName, table.Name),
Content: buf.String(),
@@ -3131,9 +3224,19 @@ func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *s
if err := writeViewSDL(&buf, schemaName, view); err != nil {
return nil, errors.Wrapf(err, "failed to generate view SDL for %s.%s", schemaName, view.Name)
}
+ buf.WriteString(";\n")
+
+ // Write view comment if present
+ if len(view.Comment) > 0 {
+ buf.WriteString("\n")
+ if err := writeViewCommentSDL(&buf, schemaName, view); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate view comment for %s.%s", schemaName, view.Name)
+ }
+ }
+
files = append(files, schema.File{
Name: fmt.Sprintf("schemas/%s/views/%s.sql", schemaName, view.Name),
- Content: buf.String() + ";\n",
+ Content: buf.String(),
})
}
@@ -3147,9 +3250,19 @@ func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *s
if err := writeFunctionSDL(&buf, schemaName, function); err != nil {
return nil, errors.Wrapf(err, "failed to generate function SDL for %s.%s", schemaName, function.Name)
}
+ buf.WriteString(";\n")
+
+ // Write function comment if present
+ if len(function.Comment) > 0 {
+ buf.WriteString("\n")
+ if err := writeFunctionCommentSDL(&buf, schemaName, function); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate function comment for %s.%s", schemaName, function.Name)
+ }
+ }
+
files = append(files, schema.File{
Name: fmt.Sprintf("schemas/%s/functions/%s.sql", schemaName, function.Name),
- Content: buf.String() + ";\n",
+ Content: buf.String(),
})
}
}
@@ -3215,3 +3328,187 @@ func buildTableSequencesMap(metadata *storepb.DatabaseSchemaMetadata) map[string
}
return tableSequencesMap
}
+
+// SDL Comment Functions
+
+func writeSchemaCommentSDL(out io.Writer, schema *storepb.SchemaMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON SCHEMA "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schema.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(schema.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeTableCommentSDL(out io.Writer, schemaName string, table *storepb.TableMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON TABLE "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, table.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(table.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeColumnCommentSDL(out io.Writer, schemaName, tableName string, column *storepb.ColumnMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON COLUMN "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, tableName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, column.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(column.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeViewCommentSDL(out io.Writer, schemaName string, view *storepb.ViewMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON VIEW "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, view.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(view.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeFunctionCommentSDL(out io.Writer, schemaName string, function *storepb.FunctionMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON FUNCTION "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, function.Signature); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(function.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeSequenceCommentSDL(out io.Writer, schemaName string, sequence *storepb.SequenceMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON SEQUENCE "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, sequence.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(sequence.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
+
+func writeIndexCommentSDL(out io.Writer, schemaName string, index *storepb.IndexMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON INDEX "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, schemaName); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"."`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, index.Name); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, escapeSingleQuote(index.Comment)); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `';`); err != nil {
+ return err
+ }
+ _, err := io.WriteString(out, "\n\n")
+ return err
+}
diff --git a/backend/plugin/schema/pg/get_database_definition_sdl_test.go b/backend/plugin/schema/pg/get_database_definition_sdl_test.go
index 7835bc6eee..4bb8c68d5d 100644
--- a/backend/plugin/schema/pg/get_database_definition_sdl_test.go
+++ b/backend/plugin/schema/pg/get_database_definition_sdl_test.go
@@ -1373,3 +1373,266 @@ func TestCheckConstraintNotValidFormatNormalMode(t *testing.T) {
_, err = pgparser.ParsePostgreSQL(result)
require.NoError(t, err, "Generated SQL should be parseable by PostgreSQL parser")
}
+
+func TestGetDatabaseDefinitionSDLFormat_WithComments(t *testing.T) {
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "test_schema",
+ Comment: "Test schema for comments",
+ Tables: []*storepb.TableMetadata{
+ {
+ Name: "users",
+ Comment: "Users table with comments",
+ Columns: []*storepb.ColumnMetadata{
+ {
+ Name: "id",
+ Type: "SERIAL",
+ Nullable: false,
+ Comment: "User ID",
+ },
+ {
+ Name: "name",
+ Type: "VARCHAR(255)",
+ Nullable: false,
+ Comment: "User name",
+ },
+ {
+ Name: "email",
+ Type: "VARCHAR(320)",
+ Nullable: true,
+ Comment: "User email address",
+ },
+ },
+ Indexes: []*storepb.IndexMetadata{
+ {
+ Name: "idx_users_email",
+ Expressions: []string{"email"},
+ Unique: false,
+ Primary: false,
+ Comment: "Index on email column",
+ },
+ },
+ },
+ },
+ Views: []*storepb.ViewMetadata{
+ {
+ Name: "active_users",
+ Definition: "SELECT id, name, email FROM test_schema.users WHERE active = true",
+ Comment: "View of active users",
+ },
+ },
+ Functions: []*storepb.FunctionMetadata{
+ {
+ Name: "get_user_count",
+ Signature: "get_user_count()",
+ Definition: "CREATE FUNCTION test_schema.get_user_count() RETURNS INTEGER AS $$ BEGIN RETURN (SELECT COUNT(*) FROM test_schema.users); END; $$ LANGUAGE plpgsql",
+ Comment: "Function to get user count",
+ },
+ },
+ Sequences: []*storepb.SequenceMetadata{
+ {
+ Name: "custom_seq",
+ DataType: "bigint",
+ Start: "1",
+ Increment: "1",
+ MinValue: "1",
+ MaxValue: "9223372036854775807",
+ Cycle: false,
+ CacheSize: "1",
+ Comment: "Custom sequence for testing",
+ },
+ },
+ },
+ },
+ }
+
+ ctx := schema.GetDefinitionContext{
+ SDLFormat: true,
+ }
+
+ result, err := GetDatabaseDefinition(ctx, metadata)
+ require.NoError(t, err)
+
+ // Verify schema comment
+ assert.Contains(t, result, `CREATE SCHEMA IF NOT EXISTS "test_schema";`)
+ assert.Contains(t, result, `COMMENT ON SCHEMA "test_schema" IS 'Test schema for comments';`)
+
+ // Verify table comment
+ assert.Contains(t, result, `COMMENT ON TABLE "test_schema"."users" IS 'Users table with comments';`)
+
+ // Verify column comments
+ assert.Contains(t, result, `COMMENT ON COLUMN "test_schema"."users"."id" IS 'User ID';`)
+ assert.Contains(t, result, `COMMENT ON COLUMN "test_schema"."users"."name" IS 'User name';`)
+ assert.Contains(t, result, `COMMENT ON COLUMN "test_schema"."users"."email" IS 'User email address';`)
+
+ // Verify view comment
+ assert.Contains(t, result, `COMMENT ON VIEW "test_schema"."active_users" IS 'View of active users';`)
+
+ // Verify function comment
+ assert.Contains(t, result, `COMMENT ON FUNCTION "test_schema"."get_user_count()" IS 'Function to get user count';`)
+
+ // Verify sequence comment
+ assert.Contains(t, result, `COMMENT ON SEQUENCE "test_schema"."custom_seq" IS 'Custom sequence for testing';`)
+
+ // Verify index comment
+ assert.Contains(t, result, `COMMENT ON INDEX "test_schema"."idx_users_email" IS 'Index on email column';`)
+
+ // Validate that the generated SQL can be parsed without errors using ANTLR parser
+ _, err = pgparser.ParsePostgreSQL(result)
+ require.NoError(t, err, "Generated SQL should be parseable by PostgreSQL parser")
+}
+
+func TestGetDatabaseDefinitionSDLFormat_WithCommentsEscaping(t *testing.T) {
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ Tables: []*storepb.TableMetadata{
+ {
+ Name: "test_table",
+ Comment: "Table with 'single quotes' and \"double quotes\"",
+ Columns: []*storepb.ColumnMetadata{
+ {
+ Name: "id",
+ Type: "INTEGER",
+ Nullable: false,
+ Comment: "Column with 'quoted' text",
+ },
+ },
+ },
+ },
+ },
+ },
+ }
+
+ ctx := schema.GetDefinitionContext{
+ SDLFormat: true,
+ }
+
+ result, err := GetDatabaseDefinition(ctx, metadata)
+ require.NoError(t, err)
+
+ // Verify that single quotes are properly escaped
+ assert.Contains(t, result, `COMMENT ON TABLE "public"."test_table" IS 'Table with ''single quotes'' and "double quotes"';`)
+ assert.Contains(t, result, `COMMENT ON COLUMN "public"."test_table"."id" IS 'Column with ''quoted'' text';`)
+
+ // Validate that the generated SQL can be parsed without errors using ANTLR parser
+ _, err = pgparser.ParsePostgreSQL(result)
+ require.NoError(t, err, "Generated SQL should be parseable by PostgreSQL parser")
+}
+
+func TestGetMultiFileDatabaseDefinition_WithComments(t *testing.T) {
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "app_schema",
+ Comment: "Application schema",
+ Tables: []*storepb.TableMetadata{
+ {
+ Name: "products",
+ Comment: "Product catalog",
+ Columns: []*storepb.ColumnMetadata{
+ {
+ Name: "id",
+ Type: "INTEGER",
+ Nullable: false,
+ Comment: "Product ID",
+ },
+ {
+ Name: "name",
+ Type: "TEXT",
+ Nullable: false,
+ Comment: "Product name",
+ },
+ },
+ Indexes: []*storepb.IndexMetadata{
+ {
+ Name: "idx_products_name",
+ Expressions: []string{"name"},
+ Unique: false,
+ Primary: false,
+ Comment: "Index for product search",
+ },
+ },
+ },
+ },
+ Views: []*storepb.ViewMetadata{
+ {
+ Name: "active_products",
+ Definition: "SELECT id, name FROM app_schema.products WHERE active = true",
+ Comment: "View of active products",
+ },
+ },
+ Functions: []*storepb.FunctionMetadata{
+ {
+ Name: "count_products",
+ Signature: "count_products()",
+ Definition: "CREATE FUNCTION app_schema.count_products() RETURNS INTEGER AS $$ BEGIN RETURN (SELECT COUNT(*) FROM app_schema.products); END; $$ LANGUAGE plpgsql",
+ Comment: "Returns product count",
+ },
+ },
+ Sequences: []*storepb.SequenceMetadata{
+ {
+ Name: "order_seq",
+ DataType: "bigint",
+ Start: "1",
+ Increment: "1",
+ MinValue: "1",
+ MaxValue: "9223372036854775807",
+ Cycle: false,
+ CacheSize: "1",
+ Comment: "Sequence for orders",
+ },
+ },
+ },
+ },
+ }
+
+ ctx := schema.GetDefinitionContext{
+ SDLFormat: true,
+ }
+
+ result, err := GetMultiFileDatabaseDefinition(ctx, metadata)
+ require.NoError(t, err)
+ require.NotNil(t, result)
+
+ // Build a map for easier testing
+ fileMap := make(map[string]string)
+ for _, file := range result.Files {
+ fileMap[file.Name] = file.Content
+ }
+
+ // Verify sequence file with comment
+ sequenceFile, ok := fileMap["schemas/app_schema/sequences/order_seq.sql"]
+ require.True(t, ok, "sequence file should exist")
+ assert.Contains(t, sequenceFile, `CREATE SEQUENCE "app_schema"."order_seq"`)
+ assert.Contains(t, sequenceFile, `COMMENT ON SEQUENCE "app_schema"."order_seq" IS 'Sequence for orders';`)
+
+ // Verify table file with comments
+ tableFile, ok := fileMap["schemas/app_schema/tables/products.sql"]
+ require.True(t, ok, "table file should exist")
+ assert.Contains(t, tableFile, `CREATE TABLE "app_schema"."products"`)
+ assert.Contains(t, tableFile, `COMMENT ON TABLE "app_schema"."products" IS 'Product catalog';`)
+ assert.Contains(t, tableFile, `COMMENT ON COLUMN "app_schema"."products"."id" IS 'Product ID';`)
+ assert.Contains(t, tableFile, `COMMENT ON COLUMN "app_schema"."products"."name" IS 'Product name';`)
+ assert.Contains(t, tableFile, `COMMENT ON INDEX "app_schema"."idx_products_name" IS 'Index for product search';`)
+
+ // Verify view file with comment
+ viewFile, ok := fileMap["schemas/app_schema/views/active_products.sql"]
+ require.True(t, ok, "view file should exist")
+ assert.Contains(t, viewFile, `CREATE VIEW "app_schema"."active_products"`)
+ assert.Contains(t, viewFile, `COMMENT ON VIEW "app_schema"."active_products" IS 'View of active products';`)
+
+ // Verify function file with comment
+ functionFile, ok := fileMap["schemas/app_schema/functions/count_products.sql"]
+ require.True(t, ok, "function file should exist")
+ assert.Contains(t, functionFile, `CREATE FUNCTION app_schema.count_products()`)
+ assert.Contains(t, functionFile, `COMMENT ON FUNCTION "app_schema"."count_products()" IS 'Returns product count';`)
+
+ // Validate that each file's SQL can be parsed
+ for fileName, content := range fileMap {
+ _, err := pgparser.ParsePostgreSQL(content)
+ require.NoError(t, err, "SQL in file %s should be parseable by PostgreSQL parser", fileName)
+ }
+}