Skip to content

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

feat: support comment in generate migration (#17806)

rebelice4136660cf572
diff --git a/backend/plugin/schema/pg/comment_migration_test.go b/backend/plugin/schema/pg/comment_migration_test.go
new file mode 100644
index 0000000000..f7a10516fb
--- /dev/null
+++ b/backend/plugin/schema/pg/comment_migration_test.go
@@ -0,0 +1,422 @@
+package pg
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestCommentMigration_TableComment(t *testing.T) {
+ tests := []struct {
+ name string
+ currentSDL string
+ previousSDL string
+ wantSQL string
+ }{
+ {
+ name: "add table comment",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'User information table';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+`,
+ wantSQL: `COMMENT ON TABLE "public"."users" IS 'User information table';
+`,
+ },
+ {
+ name: "modify table comment",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'Updated user table';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'User information table';
+`,
+ wantSQL: `COMMENT ON TABLE "public"."users" IS 'Updated user table';
+`,
+ },
+ {
+ name: "remove table comment",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'User information table';
+`,
+ wantSQL: `COMMENT ON TABLE "public"."users" IS NULL;
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ diff, err := GetSDLDiff(tt.currentSDL, tt.previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ require.Equal(t, tt.wantSQL, migrationSQL)
+ })
+ }
+}
+
+func TestCommentMigration_ColumnComment(t *testing.T) {
+ tests := []struct {
+ name string
+ currentSDL string
+ previousSDL string
+ wantSQL string
+ }{
+ {
+ name: "add column comment",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON COLUMN "public"."users"."id" IS 'Primary key';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+`,
+ wantSQL: `COMMENT ON COLUMN "public"."users"."id" IS 'Primary key';
+`,
+ },
+ {
+ name: "modify column comment",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON COLUMN "public"."users"."id" IS 'User unique identifier';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON COLUMN "public"."users"."id" IS 'Primary key';
+`,
+ wantSQL: `COMMENT ON COLUMN "public"."users"."id" IS 'User unique identifier';
+`,
+ },
+ {
+ name: "multiple column comments",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON COLUMN "public"."users"."id" IS 'Primary key';
+COMMENT ON COLUMN "public"."users"."name" IS 'User full name';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+`,
+ // Note: order may vary depending on map iteration
+ wantSQL: `COMMENT ON COLUMN "public"."users"."id" IS 'Primary key';
+COMMENT ON COLUMN "public"."users"."name" IS 'User full name';
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ diff, err := GetSDLDiff(tt.currentSDL, tt.previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ require.Equal(t, tt.wantSQL, migrationSQL)
+ })
+ }
+}
+
+func TestCommentMigration_ViewComment(t *testing.T) {
+ currentSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+CREATE VIEW "public"."active_users" AS SELECT * FROM users;
+
+COMMENT ON VIEW "public"."active_users" IS 'View of active users';
+`
+
+ previousSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+CREATE VIEW "public"."active_users" AS SELECT * FROM users;
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ expectedSQL := `COMMENT ON VIEW "public"."active_users" IS 'View of active users';
+`
+ require.Equal(t, expectedSQL, migrationSQL)
+}
+
+func TestCommentMigration_SequenceComment(t *testing.T) {
+ currentSDL := `
+CREATE SEQUENCE "public"."user_id_seq" AS integer START WITH 1 INCREMENT BY 1;
+
+COMMENT ON SEQUENCE "public"."user_id_seq" IS 'Sequence for user IDs';
+`
+
+ previousSDL := `
+CREATE SEQUENCE "public"."user_id_seq" AS integer START WITH 1 INCREMENT BY 1;
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ expectedSQL := `COMMENT ON SEQUENCE "public"."user_id_seq" IS 'Sequence for user IDs';
+`
+ require.Equal(t, expectedSQL, migrationSQL)
+}
+
+func TestCommentMigration_FunctionComment(t *testing.T) {
+ currentSDL := `
+CREATE FUNCTION "public"."add_numbers"(a integer, b integer) RETURNS integer
+ LANGUAGE plpgsql
+ AS $$
+BEGIN
+ RETURN a + b;
+END;
+$$;
+
+COMMENT ON FUNCTION "public"."add_numbers"(integer, integer) IS 'Adds two numbers';
+`
+
+ previousSDL := `
+CREATE FUNCTION "public"."add_numbers"(a integer, b integer) RETURNS integer
+ LANGUAGE plpgsql
+ AS $$
+BEGIN
+ RETURN a + b;
+END;
+$$;
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ // Function signature includes parameter names
+ expectedSQL := `COMMENT ON FUNCTION "public".add_numbers(a integer, b integer) IS 'Adds two numbers';
+`
+ require.Equal(t, expectedSQL, migrationSQL)
+}
+
+func TestCommentMigration_SchemaComment(t *testing.T) {
+ currentSDL := `
+CREATE SCHEMA "app";
+
+COMMENT ON SCHEMA "app" IS 'Application schema';
+`
+
+ previousSDL := `
+CREATE SCHEMA "app";
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ expectedSQL := `COMMENT ON SCHEMA "app" IS 'Application schema';
+`
+ require.Equal(t, expectedSQL, migrationSQL)
+}
+
+func TestCommentMigration_SpecialCharacters(t *testing.T) {
+ tests := []struct {
+ name string
+ currentSDL string
+ previousSDL string
+ wantSQL string
+ }{
+ {
+ name: "comment with single quote",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL
+);
+
+COMMENT ON TABLE "public"."users" IS 'User''s table';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL
+);
+`,
+ // Single quotes are already escaped in SDL, and writeCommentOnTable escapes again
+ wantSQL: `COMMENT ON TABLE "public"."users" IS 'User''''s table';
+`,
+ },
+ {
+ name: "comment with newlines",
+ currentSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL
+);
+
+COMMENT ON TABLE "public"."users" IS 'This is a
+multi-line
+comment';
+`,
+ previousSDL: `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL
+);
+`,
+ wantSQL: `COMMENT ON TABLE "public"."users" IS 'This is a
+multi-line
+comment';
+`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ diff, err := GetSDLDiff(tt.currentSDL, tt.previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ require.Equal(t, tt.wantSQL, migrationSQL)
+ })
+ }
+}
+
+func TestCommentMigration_NoObjectChangeWithCommentChange(t *testing.T) {
+ // Test that when only comment changes, no table ALTER is generated
+ currentSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'Updated comment';
+`
+
+ previousSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'Old comment';
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ // Should have no table changes
+ require.Len(t, diff.TableChanges, 0)
+
+ // Should have comment change
+ require.Len(t, diff.CommentChanges, 1)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ expectedSQL := `COMMENT ON TABLE "public"."users" IS 'Updated comment';
+`
+ require.Equal(t, expectedSQL, migrationSQL)
+}
+
+func TestCommentMigration_CombinedChanges(t *testing.T) {
+ // Test that when both table and comment change, we get both statements
+ currentSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text,
+ "email" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'User table with email';
+`
+
+ previousSDL := `
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);
+
+COMMENT ON TABLE "public"."users" IS 'Basic user table';
+`
+
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+
+ // Should have table change
+ require.Len(t, diff.TableChanges, 1)
+ require.Equal(t, "ALTER", string(diff.TableChanges[0].Action))
+
+ // Should have comment change
+ require.Len(t, diff.CommentChanges, 1)
+
+ migrationSQL, err := generateMigration(diff)
+ require.NoError(t, err)
+
+ // Should contain both ALTER TABLE and COMMENT ON
+ require.Contains(t, migrationSQL, "ALTER TABLE")
+ require.Contains(t, migrationSQL, "COMMENT ON TABLE")
+ require.Contains(t, migrationSQL, "email")
+ require.Contains(t, migrationSQL, "User table with email")
+}
diff --git a/backend/plugin/schema/pg/generate_migration.go b/backend/plugin/schema/pg/generate_migration.go
index 9a54bb5cb4..c02e2f2aab 100644
--- a/backend/plugin/schema/pg/generate_migration.go
+++ b/backend/plugin/schema/pg/generate_migration.go
@@ -1051,7 +1051,12 @@ func createObjectsInOrder(diff *schema.MetadataDiff, buf *strings.Builder) error
}
// Handle enum type comment changes
- return generateEnumTypeCommentChanges(buf, diff)
+ if err := generateEnumTypeCommentChanges(buf, diff); err != nil {
+ return err
+ }
+
+ // Handle SDL-based comment changes (from SDL diff mode)
+ return generateCommentChangesFromSDL(buf, diff)
}
func generateCreateTable(schemaName, tableName string, table *storepb.TableMetadata, includeForeignKeys bool) (string, error) {
@@ -2898,6 +2903,61 @@ func writeCommentOnType(out *strings.Builder, schema, typeName, comment string)
_, _ = out.WriteString("\n")
}
+// generateCommentChangesFromSDL generates COMMENT ON statements from SDL-based comment diffs
+// This handles comment changes detected from SDL diff mode (AST-based)
+func generateCommentChangesFromSDL(buf *strings.Builder, diff *schema.MetadataDiff) error {
+ if len(diff.CommentChanges) == 0 {
+ return nil
+ }
+
+ for _, commentDiff := range diff.CommentChanges {
+ // Extract the new comment text from the AST node
+ newComment := extractCommentFromDiff(commentDiff)
+
+ switch commentDiff.ObjectType {
+ case schema.CommentObjectTypeSchema:
+ writeCommentOnSchema(buf, commentDiff.SchemaName, newComment)
+
+ case schema.CommentObjectTypeTable:
+ writeCommentOnTable(buf, commentDiff.SchemaName, commentDiff.ObjectName, newComment)
+
+ case schema.CommentObjectTypeColumn:
+ writeCommentOnColumn(buf, commentDiff.SchemaName, commentDiff.ObjectName, commentDiff.ColumnName, newComment)
+
+ case schema.CommentObjectTypeView:
+ writeCommentOnView(buf, commentDiff.SchemaName, commentDiff.ObjectName, newComment)
+
+ case schema.CommentObjectTypeFunction:
+ // For functions, ObjectName contains the function signature
+ writeCommentOnFunction(buf, commentDiff.SchemaName, commentDiff.ObjectName, newComment)
+
+ case schema.CommentObjectTypeSequence:
+ writeCommentOnSequence(buf, commentDiff.SchemaName, commentDiff.ObjectName, newComment)
+
+ case schema.CommentObjectTypeIndex:
+ // Index name is stored in IndexName field
+ indexName := commentDiff.IndexName
+ if indexName == "" {
+ // Fallback to ObjectName if IndexName is not set
+ indexName = commentDiff.ObjectName
+ }
+ writeCommentOnIndex(buf, commentDiff.SchemaName, indexName, newComment)
+
+ default:
+ // Unknown object type, skip
+ continue
+ }
+ }
+
+ return nil
+}
+
+// extractCommentFromDiff extracts the comment text from a CommentDiff
+// It uses the NewComment field which contains the extracted comment text
+func extractCommentFromDiff(commentDiff *schema.CommentDiff) string {
+ return commentDiff.NewComment
+}
+
// convertToCreateOrReplace uses ANTLR parser to safely convert CREATE FUNCTION to CREATE OR REPLACE FUNCTION
func convertToCreateOrReplace(definition string) string {
// Parse the SQL statement using ANTLR
diff --git a/backend/plugin/schema/pg/get_sdl_diff.go b/backend/plugin/schema/pg/get_sdl_diff.go
index c0a13207a6..3ce4aff317 100644
--- a/backend/plugin/schema/pg/get_sdl_diff.go
+++ b/backend/plugin/schema/pg/get_sdl_diff.go
@@ -329,6 +329,32 @@ func (l *sdlChunkExtractor) EnterViewstmt(ctx *parser.ViewstmtContext) {
l.chunks.Views[schemaQualifiedName] = chunk
}
+func (l *sdlChunkExtractor) EnterCreateschemastmt(ctx *parser.CreateschemastmtContext) {
+ // Extract schema name
+ var schemaName string
+
+ // Schema name can be either from optschemaname or colid
+ if ctx.Colid() != nil {
+ schemaName = pgparser.NormalizePostgreSQLColid(ctx.Colid())
+ } else if ctx.Optschemaname() != nil && ctx.Optschemaname().Colid() != nil {
+ schemaName = pgparser.NormalizePostgreSQLColid(ctx.Optschemaname().Colid())
+ } else {
+ // Skip if we can't determine schema name
+ return
+ }
+
+ // Skip pg_catalog and information_schema
+ if schemaName == "pg_catalog" || schemaName == "information_schema" {
+ return
+ }
+
+ // Create chunk for this schema
+ l.chunks.Schemas[schemaName] = &schema.SDLChunk{
+ Identifier: schemaName,
+ ASTNode: ctx,
+ }
+}
+
func (l *sdlChunkExtractor) EnterCommentstmt(ctx *parser.CommentstmtContext) {
// Extract the comment text (can be sconst or NULL)
// We store the entire AST node, not just the comment text
@@ -4328,7 +4354,17 @@ func processObjectComments(currentMap, previousMap map[string]*schema.SDLChunk,
// If comments are different, generate a CommentDiff
if currentCommentText != previousCommentText {
- schemaName, objectName := parseIdentifier(identifier)
+ var schemaName, objectName string
+
+ // For SCHEMA objects, identifier is just the schema name
+ // For other objects, identifier is "schema.object"
+ if objectType == schema.CommentObjectTypeSchema {
+ schemaName = identifier
+ objectName = identifier // For schemas, objectName is also the schema name
+ } else {
+ schemaName, objectName = parseIdentifier(identifier)
+ }
+
action := schema.MetadataDiffActionAlter
if previousCommentText == "" {
action = schema.MetadataDiffActionCreate