Skip to content

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

feat: support extension for pg sdl (#18118)

rebelicecc1c99d6516f
diff --git a/backend/plugin/schema/differ.go b/backend/plugin/schema/differ.go
index e3d42413b0..7c11d1e48f 100644
--- a/backend/plugin/schema/differ.go
+++ b/backend/plugin/schema/differ.go
@@ -50,6 +50,9 @@ type MetadataDiff struct {
// Enum type changes
EnumTypeChanges []*EnumTypeDiff
+ // Extension changes
+ ExtensionChanges []*ExtensionDiff
+
// Event changes
EventChanges []*EventDiff
@@ -247,6 +250,16 @@ type EnumTypeDiff struct {
NewASTNode any // For SDL/AST-only mode
}
+// ExtensionDiff represents changes to an extension.
+type ExtensionDiff struct {
+ Action MetadataDiffAction
+ ExtensionName string
+ OldExtension *storepb.ExtensionMetadata
+ NewExtension *storepb.ExtensionMetadata
+ OldASTNode any // For SDL/AST-only mode
+ NewASTNode any // For SDL/AST-only mode
+}
+
// EventDiff represents changes to an event.
type EventDiff struct {
Action MetadataDiffAction
@@ -268,6 +281,7 @@ const (
CommentObjectTypeSequence CommentObjectType = "SEQUENCE"
CommentObjectTypeIndex CommentObjectType = "INDEX"
CommentObjectTypeType CommentObjectType = "TYPE"
+ CommentObjectTypeExtension CommentObjectType = "EXTENSION"
)
// CommentDiff represents changes to database object comments.
@@ -342,6 +356,9 @@ func GetDatabaseSchemaDiff(engine storepb.Engine, oldSchema, newSchema *model.Da
}
}
+ // Compare database-level objects (extensions)
+ compareExtensions(diff, oldMetadata, newMetadata)
+
// Sort all diff lists to ensure stable output order
sortDiffLists(diff)
@@ -1932,6 +1949,64 @@ func compareEnumTypes(diff *MetadataDiff, schemaName string, oldSchema, newSchem
}
}
+// compareExtensions compares extensions between old and new database metadata.
+func compareExtensions(diff *MetadataDiff, oldMetadata, newMetadata *storepb.DatabaseSchemaMetadata) {
+ // Build maps of extensions
+ oldExtensionMap := make(map[string]*storepb.ExtensionMetadata)
+ for _, extension := range oldMetadata.Extensions {
+ oldExtensionMap[extension.Name] = extension
+ }
+
+ newExtensionMap := make(map[string]*storepb.ExtensionMetadata)
+ for _, extension := range newMetadata.Extensions {
+ newExtensionMap[extension.Name] = extension
+ }
+
+ // Check for dropped extensions
+ for extensionName, oldExtension := range oldExtensionMap {
+ if _, exists := newExtensionMap[extensionName]; !exists {
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &ExtensionDiff{
+ Action: MetadataDiffActionDrop,
+ ExtensionName: extensionName,
+ OldExtension: oldExtension,
+ })
+ }
+ }
+
+ // Check for new extensions
+ for extensionName, newExtension := range newExtensionMap {
+ if _, exists := oldExtensionMap[extensionName]; !exists {
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &ExtensionDiff{
+ Action: MetadataDiffActionCreate,
+ ExtensionName: extensionName,
+ NewExtension: newExtension,
+ })
+ }
+ }
+
+ // Check for modified extensions
+ for extensionName, newExtension := range newExtensionMap {
+ if oldExtension, exists := oldExtensionMap[extensionName]; exists {
+ // Check if extension has changed (schema, version, or description)
+ if oldExtension.Schema != newExtension.Schema ||
+ oldExtension.Version != newExtension.Version ||
+ oldExtension.Description != newExtension.Description {
+ // Use DROP + CREATE pattern for modifications
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &ExtensionDiff{
+ Action: MetadataDiffActionDrop,
+ ExtensionName: extensionName,
+ OldExtension: oldExtension,
+ })
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &ExtensionDiff{
+ Action: MetadataDiffActionCreate,
+ ExtensionName: extensionName,
+ NewExtension: newExtension,
+ })
+ }
+ }
+ }
+}
+
// compareEvents compares events between old and new schemas.
func compareEvents(diff *MetadataDiff, _ string, oldSchema, newSchema *model.SchemaMetadata) {
oldSchemaProto := oldSchema.GetProto()
@@ -2056,7 +2131,8 @@ func FilterPostgresArchiveSchema(diff *MetadataDiff) *MetadataDiff {
}
}
- // Events are database-level objects, not schema-specific, so copy them all
+ // Extensions and Events are database-level objects, not schema-specific, so copy them all
+ filtered.ExtensionChanges = diff.ExtensionChanges
filtered.EventChanges = diff.EventChanges
return filtered
@@ -2273,6 +2349,14 @@ func sortDiffLists(diff *MetadataDiff) {
return strings.Compare(string(a.Action), string(b.Action))
})
+ // Sort extension changes by extension name, then action
+ slices.SortFunc(diff.ExtensionChanges, func(a, b *ExtensionDiff) int {
+ if a.ExtensionName != b.ExtensionName {
+ return strings.Compare(a.ExtensionName, b.ExtensionName)
+ }
+ return strings.Compare(string(a.Action), string(b.Action))
+ })
+
// Sort event changes by event name, then action
slices.SortFunc(diff.EventChanges, func(a, b *EventDiff) int {
if a.EventName != b.EventName {
diff --git a/backend/plugin/schema/pg/extension_test.go b/backend/plugin/schema/pg/extension_test.go
new file mode 100644
index 0000000000..cca64afa19
--- /dev/null
+++ b/backend/plugin/schema/pg/extension_test.go
@@ -0,0 +1,707 @@
+package pg
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/schema"
+ "github.com/bytebase/bytebase/backend/store/model"
+)
+
+// TestExtensionInSDLOutput tests that extensions are included in SDL output
+func TestExtensionInSDLOutput(t *testing.T) {
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "uuid-ossp",
+ Schema: "public",
+ Version: "1.1",
+ Description: "UUID generation extension",
+ },
+ {
+ Name: "pg_trgm",
+ Version: "1.6",
+ },
+ },
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ },
+ },
+ }
+
+ // Test single-file SDL format
+ sdl, err := getSDLFormat(metadata)
+ require.NoError(t, err)
+
+ // Verify extensions are present
+ require.Contains(t, sdl, "CREATE EXTENSION")
+ require.Contains(t, sdl, "uuid-ossp")
+ require.Contains(t, sdl, "pg_trgm")
+ require.Contains(t, sdl, `WITH SCHEMA "public"`)
+ require.Contains(t, sdl, `VERSION '1.1'`)
+ require.Contains(t, sdl, `VERSION '1.6'`)
+
+ // Verify comment
+ require.Contains(t, sdl, "COMMENT ON EXTENSION")
+ require.Contains(t, sdl, "UUID generation extension")
+}
+
+// TestExtensionInMultiFileSDL tests that extensions are included in multi-file SDL
+func TestExtensionInMultiFileSDL(t *testing.T) {
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "postgis",
+ Schema: "public",
+ Version: "3.3.2",
+ Description: "PostGIS geometry and geography types",
+ },
+ },
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ },
+ },
+ }
+
+ // Test multi-file SDL format
+ result, err := GetMultiFileDatabaseDefinition(schema.GetDefinitionContext{}, metadata)
+ require.NoError(t, err)
+ require.NotNil(t, result)
+
+ // Find the extension file
+ var extensionFile *schema.File
+ for i := range result.Files {
+ if result.Files[i].Name == "extensions.sql" {
+ extensionFile = &result.Files[i]
+ break
+ }
+ }
+ require.NotNil(t, extensionFile, "Extension file not found")
+
+ // Verify content includes extension
+ require.Contains(t, extensionFile.Content, "CREATE EXTENSION")
+ require.Contains(t, extensionFile.Content, "postgis")
+ require.Contains(t, extensionFile.Content, `WITH SCHEMA "public"`)
+ require.Contains(t, extensionFile.Content, `VERSION '3.3.2'`)
+ require.Contains(t, extensionFile.Content, "COMMENT ON EXTENSION")
+ require.Contains(t, extensionFile.Content, "PostGIS geometry and geography types")
+}
+
+// TestExtensionDependencyOrdering tests that extensions have correct dependency ordering in migrations
+func TestExtensionDependencyOrdering(t *testing.T) {
+ t.Run("CREATE: Extension before Enum Types and Tables", func(t *testing.T) {
+ // Test that when creating an extension,
+ // CREATE EXTENSION comes before CREATE TYPE and CREATE TABLE
+
+ oldMetadata := &storepb.DatabaseSchemaMetadata{
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ },
+ },
+ }
+
+ newMetadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "uuid-ossp",
+ },
+ },
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ EnumTypes: []*storepb.EnumTypeMetadata{
+ {
+ Name: "status_type",
+ Values: []string{"active", "inactive"},
+ },
+ },
+ Tables: []*storepb.TableMetadata{
+ {
+ Name: "users",
+ Columns: []*storepb.ColumnMetadata{
+ {
+ Name: "id",
+ Type: "uuid",
+ },
+ {
+ Name: "status",
+ Type: "status_type",
+ },
+ },
+ },
+ },
+ },
+ },
+ }
+
+ // Convert to model.DatabaseSchema
+ oldSchema := model.NewDatabaseSchema(oldMetadata, nil, nil, storepb.Engine_POSTGRES, false)
+ newSchema := model.NewDatabaseSchema(newMetadata, nil, nil, storepb.Engine_POSTGRES, false)
+
+ // Get diff
+ diff, err := schema.GetDatabaseSchemaDiff(storepb.Engine_POSTGRES, oldSchema, newSchema)
+ require.NoError(t, err)
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+ require.NotEmpty(t, migration)
+
+ // Find positions of CREATE EXTENSION, CREATE TYPE, and CREATE TABLE
+ extensionPos := -1
+ typePos := -1
+ tablePos := -1
+ for i := 0; i < len(migration); i++ {
+ if extensionPos == -1 && i+len("CREATE EXTENSION") <= len(migration) {
+ if migration[i:i+len("CREATE EXTENSION")] == "CREATE EXTENSION" {
+ extensionPos = i
+ }
+ }
+ if typePos == -1 && i+len("CREATE TYPE") <= len(migration) {
+ if migration[i:i+len("CREATE TYPE")] == "CREATE TYPE" {
+ typePos = i
+ }
+ }
+ if tablePos == -1 && i+len("CREATE TABLE") <= len(migration) {
+ if migration[i:i+len("CREATE TABLE")] == "CREATE TABLE" {
+ tablePos = i
+ }
+ }
+ }
+
+ require.NotEqual(t, -1, extensionPos, "CREATE EXTENSION not found in migration")
+ require.NotEqual(t, -1, typePos, "CREATE TYPE not found in migration")
+ require.NotEqual(t, -1, tablePos, "CREATE TABLE not found in migration")
+ require.Less(t, extensionPos, typePos, "CREATE EXTENSION should come before CREATE TYPE")
+ require.Less(t, extensionPos, tablePos, "CREATE EXTENSION should come before CREATE TABLE")
+ })
+
+ t.Run("DROP: Tables and Enum Types before Extension", func(t *testing.T) {
+ // Test that when dropping an extension,
+ // DROP TABLE and DROP TYPE come before DROP EXTENSION
+
+ oldMetadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "uuid-ossp",
+ },
+ },
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ EnumTypes: []*storepb.EnumTypeMetadata{
+ {
+ Name: "status_type",
+ Values: []string{"active", "inactive"},
+ },
+ },
+ Tables: []*storepb.TableMetadata{
+ {
+ Name: "users",
+ Columns: []*storepb.ColumnMetadata{
+ {
+ Name: "id",
+ Type: "uuid",
+ },
+ {
+ Name: "status",
+ Type: "status_type",
+ },
+ },
+ },
+ },
+ },
+ },
+ }
+
+ newMetadata := &storepb.DatabaseSchemaMetadata{
+ Schemas: []*storepb.SchemaMetadata{
+ {
+ Name: "public",
+ },
+ },
+ }
+
+ // Convert to model.DatabaseSchema
+ oldSchema := model.NewDatabaseSchema(oldMetadata, nil, nil, storepb.Engine_POSTGRES, false)
+ newSchema := model.NewDatabaseSchema(newMetadata, nil, nil, storepb.Engine_POSTGRES, false)
+
+ // Get diff
+ diff, err := schema.GetDatabaseSchemaDiff(storepb.Engine_POSTGRES, oldSchema, newSchema)
+ require.NoError(t, err)
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+ require.NotEmpty(t, migration)
+
+ // Find positions of DROP TABLE, DROP TYPE, and DROP EXTENSION
+ tablePos := -1
+ typePos := -1
+ extensionPos := -1
+ for i := 0; i < len(migration); i++ {
+ if tablePos == -1 && i+len("DROP TABLE") <= len(migration) {
+ if migration[i:i+len("DROP TABLE")] == "DROP TABLE" {
+ tablePos = i
+ }
+ }
+ if typePos == -1 && i+len("DROP TYPE") <= len(migration) {
+ if migration[i:i+len("DROP TYPE")] == "DROP TYPE" {
+ typePos = i
+ }
+ }
+ if extensionPos == -1 && i+len("DROP EXTENSION") <= len(migration) {
+ if migration[i:i+len("DROP EXTENSION")] == "DROP EXTENSION" {
+ extensionPos = i
+ }
+ }
+ }
+
+ require.NotEqual(t, -1, tablePos, "DROP TABLE not found in migration")
+ require.NotEqual(t, -1, typePos, "DROP TYPE not found in migration")
+ require.NotEqual(t, -1, extensionPos, "DROP EXTENSION not found in migration")
+ require.Less(t, tablePos, extensionPos, "DROP TABLE should come before DROP EXTENSION")
+ require.Less(t, typePos, extensionPos, "DROP TYPE should come before DROP EXTENSION")
+ })
+
+ t.Run("INITIALIZATION: First-time SDL with Extension", func(t *testing.T) {
+ // This tests the initialization scenario: empty database, user writes first SDL
+ // This is a very common bb rollout scenario
+
+ // Previous SDL (empty - new database)
+ previousSDL := ``
+
+ // Current SDL (first-time setup with extension and other objects)
+ currentSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "public";
+
+CREATE TYPE "public"."status_type" AS ENUM ('active', 'inactive');
+
+CREATE TABLE "public"."users" (
+ "id" uuid NOT NULL,
+ "status" status_type NOT NULL
+);`
+
+ // Get SDL diff (simulates bb rollout initialization)
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Verify we have extension, enum, and table changes
+ require.Equal(t, 1, len(diff.ExtensionChanges), "Should have 1 extension change")
+ require.Equal(t, 1, len(diff.EnumTypeChanges), "Should have 1 enum type change")
+ require.Equal(t, 1, len(diff.TableChanges), "Should have 1 table change")
+
+ extDiff := diff.ExtensionChanges[0]
+ require.Equal(t, schema.MetadataDiffActionCreate, extDiff.Action)
+ require.Equal(t, "uuid-ossp", extDiff.ExtensionName)
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // Verify correct ordering: extension → enum → table
+ extensionPos := strings.Index(migration, "CREATE EXTENSION")
+ enumPos := strings.Index(migration, "CREATE TYPE")
+ tablePos := strings.Index(migration, "CREATE TABLE")
+
+ require.NotEqual(t, -1, extensionPos, "CREATE EXTENSION should be present")
+ require.NotEqual(t, -1, enumPos, "CREATE TYPE should be present")
+ require.NotEqual(t, -1, tablePos, "CREATE TABLE should be present")
+ require.Less(t, extensionPos, enumPos, "CREATE EXTENSION should come before CREATE TYPE")
+ require.Less(t, extensionPos, tablePos, "CREATE EXTENSION should come before CREATE TABLE")
+ })
+
+ t.Run("ADD Extension via SDL chunks", func(t *testing.T) {
+ // This tests adding an extension to existing database via SDL diff
+
+ // Previous SDL (existing database with table, no extension)
+ previousSDL := `CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);`
+
+ // Current SDL (with new extension)
+ currentSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "public";
+
+CREATE TABLE "public"."users" (
+ "id" integer NOT NULL,
+ "name" text
+);`
+
+ // Get SDL diff (simulates bb rollout behavior)
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Debug: log all diffs
+ t.Logf("ExtensionChanges: %d", len(diff.ExtensionChanges))
+ for i, extDiff := range diff.ExtensionChanges {
+ t.Logf(" Extension[%d]: Action=%v, Name=%s, HasNewAST=%v",
+ i, extDiff.Action, extDiff.ExtensionName,
+ extDiff.NewASTNode != nil)
+ }
+
+ // Verify we have an ExtensionDiff with CREATE action
+ require.Equal(t, 1, len(diff.ExtensionChanges), "Should have 1 extension change")
+ extDiff := diff.ExtensionChanges[0]
+ require.Equal(t, schema.MetadataDiffActionCreate, extDiff.Action)
+ require.Equal(t, "uuid-ossp", extDiff.ExtensionName)
+ require.NotNil(t, extDiff.NewASTNode, "NewASTNode should be set for SDL mode")
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // Verify migration creates the extension
+ require.Contains(t, migration, "CREATE EXTENSION")
+ require.Contains(t, migration, "uuid-ossp")
+ })
+
+ t.Run("REMOVE Extension via SDL chunks", func(t *testing.T) {
+ // This tests removing an extension via SDL diff
+
+ // Previous SDL (with extension)
+ previousSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+CREATE TABLE "public"."users" (
+ "id" uuid NOT NULL,
+ "name" text
+);`
+
+ // Current SDL (extension removed)
+ currentSDL := `CREATE TABLE "public"."users" (
+ "id" uuid NOT NULL,
+ "name" text
+);`
+
+ // Get SDL diff
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Verify we have an ExtensionDiff with DROP action
+ require.Equal(t, 1, len(diff.ExtensionChanges), "Should have 1 extension change")
+ extDiff := diff.ExtensionChanges[0]
+ require.Equal(t, schema.MetadataDiffActionDrop, extDiff.Action)
+ require.Equal(t, "uuid-ossp", extDiff.ExtensionName)
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // Verify migration drops the extension
+ require.Contains(t, migration, "DROP EXTENSION")
+ require.Contains(t, migration, "uuid-ossp")
+ })
+
+ t.Run("MODIFY Extension via SDL chunks (DROP + CREATE)", func(t *testing.T) {
+ // This tests modifying an extension via SDL diff
+ // PostgreSQL doesn't support modifying extensions easily, so we use DROP + CREATE pattern
+
+ // Previous SDL (with original version)
+ previousSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp" VERSION '1.0';`
+
+ // Current SDL (with modified version)
+ currentSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp" VERSION '1.1';`
+
+ // Get SDL diff
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Verify we have two ExtensionDiff entries: DROP then CREATE
+ require.Equal(t, 2, len(diff.ExtensionChanges), "Should have 2 extension changes (DROP + CREATE)")
+ dropDiff := diff.ExtensionChanges[0]
+ createDiff := diff.ExtensionChanges[1]
+
+ require.Equal(t, schema.MetadataDiffActionDrop, dropDiff.Action)
+ require.Equal(t, "uuid-ossp", dropDiff.ExtensionName)
+
+ require.Equal(t, schema.MetadataDiffActionCreate, createDiff.Action)
+ require.Equal(t, "uuid-ossp", createDiff.ExtensionName)
+ require.NotNil(t, createDiff.NewASTNode, "NewASTNode should be set for SDL mode")
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // Verify migration has both DROP and CREATE
+ require.Contains(t, migration, "DROP EXTENSION")
+ require.Contains(t, migration, "CREATE EXTENSION")
+ require.Contains(t, migration, "uuid-ossp")
+ })
+}
+
+// TestExtensionCommentChanges tests that extension comment changes are properly detected and generated
+func TestExtensionCommentChanges(t *testing.T) {
+ // Previous SDL (extension without comment)
+ previousSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`
+
+ // Current SDL (extension with comment)
+ currentSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+COMMENT ON EXTENSION "uuid-ossp" IS 'UUID generation functions';`
+
+ // Get SDL diff
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Verify we have a comment change
+ hasCommentDiff := false
+ for _, commentDiff := range diff.CommentChanges {
+ if commentDiff.ObjectType == schema.CommentObjectTypeExtension &&
+ commentDiff.ObjectName == "uuid-ossp" {
+ hasCommentDiff = true
+ break
+ }
+ }
+ require.True(t, hasCommentDiff, "Should have comment diff for extension")
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // Verify migration includes comment
+ require.Contains(t, migration, "COMMENT ON EXTENSION")
+ require.Contains(t, migration, "uuid-ossp")
+ require.Contains(t, migration, "UUID generation functions")
+}
+
+// TestExtensionWithCitextType tests the real-world scenario where citext extension
+// is needed before creating tables with citext columns (bb rollout multi-file SDL)
+func TestExtensionWithCitextType(t *testing.T) {
+ // Simulates multi-file SDL scenario where:
+ // - extensions.sql contains: CREATE EXTENSION "citext"
+ // - tables.sql contains: CREATE TABLE with citext column
+ // Previous SDL (empty database)
+ previousSDL := ``
+
+ // Current SDL (multi-file combined: extension + table using citext type)
+ // This simulates the content after merging extensions.sql and tables.sql
+ currentSDL := `-- Extension: citext
+-- Provides case-insensitive text data type
+CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA public;
+
+COMMENT ON EXTENSION "citext" IS 'Case-insensitive character string type';
+
+-- Script to create all dependency example objects in correct order
+-- For testdb11 schema
+
+-- ============================================================================
+-- STEP 1: Create Base Tables (Layer 0)
+-- ============================================================================
+
+-- Layer 0 entities have no foreign key dependencies and can be created first
+
+CREATE TABLE "public"."email_addresses" (
+ "email_id" serial,
+ "email" citext NOT NULL,
+ "user_id" integer,
+ "created_at" timestamp DEFAULT CURRENT_TIMESTAMP
+);`
+
+ // Get SDL diff
+ diff, err := GetSDLDiff(currentSDL, previousSDL, nil, nil)
+ require.NoError(t, err)
+ require.NotNil(t, diff)
+
+ // Verify we have both extension and table changes
+ require.Equal(t, 1, len(diff.ExtensionChanges), "Should have 1 extension change")
+ require.GreaterOrEqual(t, len(diff.TableChanges), 1, "Should have at least 1 table change")
+
+ extDiff := diff.ExtensionChanges[0]
+ require.Equal(t, schema.MetadataDiffActionCreate, extDiff.Action)
+ require.Equal(t, "citext", extDiff.ExtensionName)
+
+ // Generate migration
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+ t.Logf("Generated migration:\n%s", migration)
+
+ // CRITICAL: Verify correct ordering - extension MUST come before table
+ extensionPos := strings.Index(migration, "CREATE EXTENSION")
+ tablePos := strings.Index(migration, "CREATE TABLE")
+
+ require.NotEqual(t, -1, extensionPos, "CREATE EXTENSION should be present")
+ require.NotEqual(t, -1, tablePos, "CREATE TABLE should be present")
+ require.Less(t, extensionPos, tablePos, "CREATE EXTENSION must come BEFORE CREATE TABLE (otherwise citext type won't exist)")
+
+ // Verify the extension is citext
+ require.Contains(t, migration, `"citext"`)
+
+ // Verify the table uses citext type
+ require.Contains(t, migration, "email_addresses")
+}
+
+// TestExtensionNotFilteredByArchiveSchemaFilter tests that extension changes are preserved
+// when FilterPostgresArchiveSchema is applied (bb rollout workflow uses this filter)
+func TestExtensionNotFilteredByArchiveSchemaFilter(t *testing.T) {
+ // Create a diff with extension changes
+ diff := &schema.MetadataDiff{
+ DatabaseName: "testdb",
+ ExtensionChanges: []*schema.ExtensionDiff{
+ {
+ Action: schema.MetadataDiffActionCreate,
+ ExtensionName: "citext",
+ NewExtension: &storepb.ExtensionMetadata{
+ Name: "citext",
+ Schema: "public",
+ },
+ },
+ },
+ TableChanges: []*schema.TableDiff{
+ {
+ Action: schema.MetadataDiffActionCreate,
+ SchemaName: "public",
+ TableName: "test_table",
+ },
+ {
+ Action: schema.MetadataDiffActionCreate,
+ SchemaName: "bbdataarchive", // This should be filtered
+ TableName: "archive_table",
+ },
+ },
+ }
+
+ // Apply the archive schema filter (this is what bb rollout does)
+ filtered := schema.FilterPostgresArchiveSchema(diff)
+
+ // Verify extension changes are preserved (database-level objects)
+ require.Equal(t, 1, len(filtered.ExtensionChanges), "Extension changes should be preserved")
+ require.Equal(t, "citext", filtered.ExtensionChanges[0].ExtensionName)
+
+ // Verify archive schema tables are filtered out
+ require.Equal(t, 1, len(filtered.TableChanges), "Only non-archive tables should remain")
+ require.Equal(t, "public", filtered.TableChanges[0].SchemaName)
+ require.Equal(t, "test_table", filtered.TableChanges[0].TableName)
+}
+
+// TestExtensionRoundtripNoDiff tests that dumping SDL from database doesn't create false diffs
+// This reproduces the issue where:
+// 1. User creates extension with format A (e.g., manual SQL)
+// 2. Bytebase dumps SDL from database
+// 3. No changes were made, but extension is detected as changed and DROP+CREATE is generated
+func TestExtensionRoundtripNoDiff(t *testing.T) {
+ t.Run("User creates extension then dump from database - should not generate diff", func(t *testing.T) {
+ // STEP 1: User's initial SDL (manual creation)
+ userSDL := `CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA public;`
+
+ // Parse user SDL to get metadata (simulate database state)
+ chunks, err := ChunkSDLText(userSDL)
+ require.NoError(t, err)
+ require.Equal(t, 1, len(chunks.Extensions))
+
+ // STEP 2: Simulate database dump - create metadata and dump back to SDL
+ // This simulates what happens when Bytebase dumps the current database state
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "citext",
+ Schema: "public",
+ // Version might or might not be specified by user
+ Version: "",
+ // Description might be empty
+ Description: "",
+ },
+ },
+ }
+
+ // Create current database schema from metadata (this is the actual database state)
+ currentSchema := model.NewDatabaseSchema(metadata, nil, nil, storepb.Engine_POSTGRES, false)
+
+ // Dump SDL from metadata (this is what getSDLFormat does)
+ dumpedSDL, err := getSDLFormat(metadata)
+ require.NoError(t, err)
+
+ // STEP 3: Compare user SDL (previous) vs dumped SDL (current)
+ // This is what happens in bb rollout when user doesn't change anything
+ // Pass currentSchema so usability check can work
+ diff, err := GetSDLDiff(dumpedSDL, userSDL, currentSchema, nil)
+ require.NoError(t, err)
+
+ // CRITICAL: There should be NO extension changes!
+ // The extension is the same, just different text representation
+ if len(diff.ExtensionChanges) > 0 {
+ t.Error("FAILED: Extension changes detected when there should be none!")
+ t.Error("This means Bytebase will try to DROP+CREATE the extension even though nothing changed")
+
+ // Generate migration to see what would happen
+ migration, err := schema.GenerateMigration(storepb.Engine_POSTGRES, diff)
+ require.NoError(t, err)
+
+ // Check if DROP is in the migration
+ if strings.Contains(migration, "DROP EXTENSION") {
+ t.Error("CRITICAL: Migration contains DROP EXTENSION - this will fail with '2BP01' error!")
+ }
+ }
+
+ require.Equal(t, 0, len(diff.ExtensionChanges), "No changes should be detected for unchanged extension")
+ })
+
+ t.Run("Extension with version - roundtrip test", func(t *testing.T) {
+ // User creates with explicit version
+ userSDL := `CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA public VERSION '1.1';`
+
+ // Database metadata after creation
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "uuid-ossp",
+ Schema: "public",
+ Version: "1.1",
+ },
+ },
+ }
+
+ currentSchema := model.NewDatabaseSchema(metadata, nil, nil, storepb.Engine_POSTGRES, false)
+
+ dumpedSDL, err := getSDLFormat(metadata)
+ require.NoError(t, err)
+
+ diff, err := GetSDLDiff(dumpedSDL, userSDL, currentSchema, nil)
+ require.NoError(t, err)
+
+ require.Equal(t, 0, len(diff.ExtensionChanges), "No changes for extension with version")
+ })
+
+ t.Run("Extension with comment - roundtrip test", func(t *testing.T) {
+ // User creates with comment
+ userSDL := `CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA public;
+
+COMMENT ON EXTENSION "citext" IS 'Case-insensitive text type';`
+
+ metadata := &storepb.DatabaseSchemaMetadata{
+ Extensions: []*storepb.ExtensionMetadata{
+ {
+ Name: "citext",
+ Schema: "public",
+ Description: "Case-insensitive text type",
+ },
+ },
+ }
+
+ currentSchema := model.NewDatabaseSchema(metadata, nil, nil, storepb.Engine_POSTGRES, false)
+
+ dumpedSDL, err := getSDLFormat(metadata)
+ require.NoError(t, err)
+
+ diff, err := GetSDLDiff(dumpedSDL, userSDL, currentSchema, nil)
+ require.NoError(t, err)
+
+ require.Equal(t, 0, len(diff.ExtensionChanges), "No changes for extension with comment")
+ })
+}
diff --git a/backend/plugin/schema/pg/generate_migration.go b/backend/plugin/schema/pg/generate_migration.go
index 454cdc9378..904fba3fa3 100644
--- a/backend/plugin/schema/pg/generate_migration.go
+++ b/backend/plugin/schema/pg/generate_migration.go
@@ -507,6 +507,13 @@ func dropObjectsInOrder(diff *schema.MetadataDiff, buf *strings.Builder) {
}
}
+ // Drop extensions (after enum types and tables)
+ for _, extDiff := range diff.ExtensionChanges {
+ if extDiff.Action == schema.MetadataDiffActionDrop {
+ writeDropExtension(buf, extDiff.ExtensionName)
+ }
+ }
+
// Drop sequences - prioritize sequences in schemas being dropped
var sequencesInDroppedSchemas []string
var otherSequences []string
@@ -631,6 +638,24 @@ func createObjectsInOrder(diff *schema.MetadataDiff, buf *strings.Builder) error
_, _ = buf.WriteString("\n")
}
+ // Create extensions (before enum types and tables as they might provide types used in definitions)
+ for _, extDiff := range diff.ExtensionChanges {
+ if extDiff.Action == schema.MetadataDiffActionCreate {
+ // Support both metadata and AST-only modes
+ if extDiff.NewExtension != nil {
+ // Metadata mode: use extension metadata
+ if err := writeCreateExtension(buf, extDiff.NewExtension); err != nil {
+ return err
+ }
+ } else if extDiff.NewASTNode != nil {
+ // AST-only mode: extract SQL from AST node
+ if err := writeMigrationExtensionFromAST(buf, extDiff.NewASTNode); err != nil {
+ return err
+ }
+ }
+ }
+ }
+
// Create enum types (before tables as they might be used in column definitions)
for _, enumDiff := range diff.EnumTypeChanges {
if enumDiff.Action == schema.MetadataDiffActionCreate {
@@ -1896,6 +1921,67 @@ func writeCreateEnumType(out *strings.Builder, schema string, enum *storepb.Enum
return nil
}
+func writeDropExtension(out *strings.Builder, extensionName string) {
+ _, _ = out.WriteString(`DROP EXTENSION IF EXISTS "`)
+ _, _ = out.WriteString(extensionName)
+ _, _ = out.WriteString(`";`)
+ _, _ = out.WriteString("\n")
+}
+
+func writeCreateExtension(out *strings.Builder, extension *storepb.ExtensionMetadata) error {
+ _, _ = out.WriteString(`CREATE EXTENSION IF NOT EXISTS "`)
+ _, _ = out.WriteString(extension.Name)
+ _, _ = out.WriteString(`"`)
+
+ // Add WITH SCHEMA clause if schema is specified
+ if extension.Schema != "" {
+ _, _ = out.WriteString(` WITH SCHEMA "`)
+ _, _ = out.WriteString(extension.Schema)
+ _, _ = out.WriteString(`"`)
+ }
+
+ // Add VERSION clause if version is specified
+ if extension.Version != "" {
+ _, _ = out.WriteString(` VERSION '`)
+ _, _ = out.WriteString(extension.Version)
+ _, _ = out.WriteString(`'`)
+ }
+
+ _, _ = out.WriteString(`;`)
+ _, _ = out.WriteString("\n")
+
+ // Write description (comment) if present
+ if extension.Description != "" {
+ writeCommentOnExtension(out, extension.Name, extension.Description)
+ }
+
+ return nil
+}
+
+func writeMigrationExtensionFromAST(out *strings.Builder, astNode any) error {
+ if astNode == nil {
+ return errors.New("AST node is nil")
+ }
+
+ // Try to cast to PostgreSQL CreateextensionstmtContext
+ if ctx, ok := astNode.(*pgparser.CreateextensionstmtContext); ok {
+ // Get text using token stream
+ if stream := ctx.GetParser().GetTokenStream(); stream != nil {
+ text := stream.GetTextFromInterval(antlr.Interval{
+ Start: ctx.GetStart().GetTokenIndex(),
+ Stop: ctx.GetStop().GetTokenIndex(),
+ })
+ _, _ = out.WriteString(text)
+ _, _ = out.WriteString(";")
+ _, _ = out.WriteString("\n")
+ return nil
+ }
+ return errors.New("token stream not available for extension AST node")
+ }
+
+ return errors.Errorf("unexpected AST node type for extension: %T", astNode)
+}
+
func writeCreateSchema(out *strings.Builder, schema string) error {
_, _ = out.WriteString(`CREATE SCHEMA IF NOT EXISTS "`)
_, _ = out.WriteString(schema)
@@ -3397,6 +3483,23 @@ func writeCommentOnType(out *strings.Builder, schema, typeName, comment string)
_, _ = out.WriteString("\n")
}
+func writeCommentOnExtension(out *strings.Builder, extensionName, comment string) {
+ _, _ = out.WriteString(`COMMENT ON EXTENSION "`)
+ _, _ = out.WriteString(extensionName)
+ _, _ = out.WriteString(`" IS `)
+ if comment == "" {
+ _, _ = out.WriteString(`NULL`)
+ } else {
+ _, _ = out.WriteString(`'`)
+ // Escape single quotes in the comment
+ escapedComment := strings.ReplaceAll(comment, "'", "''")
+ _, _ = out.WriteString(escapedComment)
+ _, _ = out.WriteString(`'`)
+ }
+ _, _ = out.WriteString(`;`)
+ _, _ = 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 {
@@ -3522,6 +3625,10 @@ func generateCommentChangesFromSDL(buf *strings.Builder, diff *schema.MetadataDi
// COMMENT ON TYPE (for enum types)
writeCommentOnType(buf, commentDiff.SchemaName, commentDiff.ObjectName, newComment)
+ case schema.CommentObjectTypeExtension:
+ // COMMENT ON EXTENSION
+ writeCommentOnExtension(buf, commentDiff.ObjectName, newComment)
+
default:
// Unknown object type, skip
continue
diff --git a/backend/plugin/schema/pg/get_database_definition.go b/backend/plugin/schema/pg/get_database_definition.go
index d9abaa7473..ac027266d7 100644
--- a/backend/plugin/schema/pg/get_database_definition.go
+++ b/backend/plugin/schema/pg/get_database_definition.go
@@ -2182,15 +2182,80 @@ func writeExtension(out io.Writer, extension *storepb.ExtensionMetadata) error {
return err
}
- if _, err := io.WriteString(out, `" WITH SCHEMA "`); err != nil {
+ if _, err := io.WriteString(out, `"`); err != nil {
+ return err
+ }
+
+ // Add WITH SCHEMA clause if schema is specified and not empty
+ if extension.Schema != "" {
+ if _, err := io.WriteString(out, ` WITH SCHEMA "`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, extension.Schema); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `"`); err != nil {
+ return err
+ }
+ }
+
+ // Add VERSION clause if version is specified
+ if extension.Version != "" {
+ if _, err := io.WriteString(out, ` VERSION '`); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, extension.Version); err != nil {
+ return err
+ }
+ if _, err := io.WriteString(out, `'`); err != nil {
+ return err
+ }
+ }
+
+ if _, err := io.WriteString(out, `;`); err != nil {
return err
}
- if _, err := io.WriteString(out, extension.Schema); err != nil {
+ if _, err := io.WriteString(out, "\n"); err != nil {
return err
}
- if _, err := io.WriteString(out, `";`); err != nil {
+ // Write extension description (comment) if present
+ if extension.Description != "" {
+ if _, err := io.WriteString(out, "\n"); err != nil {
+ return err
+ }
+ if err := writeExtensionComment(out, extension); err != nil {
+ return err
+ }
+ } else {
+ // Add blank line even if no description
+ if _, err := io.WriteString(out, "\n"); err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+func writeExtensionComment(out io.Writer, extension *storepb.ExtensionMetadata) error {
+ if _, err := io.WriteString(out, `COMMENT ON EXTENSION "`); err != nil {
+ return err
+ }
+
+ if _, err := io.WriteString(out, extension.Name); err != nil {
+ return err
+ }
+
+ if _, err := io.WriteString(out, `" IS '`); err != nil {
+ return err
+ }
+
+ if _, err := io.WriteString(out, escapeSingleQuote(extension.Description)); err != nil {
+ return err
+ }
+
+ if _, err := io.WriteString(out, `';`); err != nil {
return err
}
@@ -2218,6 +2283,13 @@ func getSDLFormat(metadata *storepb.DatabaseSchemaMetadata) (string, error) {
}
}
+ // Write extensions (before enum types and tables as they might provide types used in definitions)
+ for _, extension := range metadata.Extensions {
+ if err := writeExtension(&buf, extension); err != nil {
+ return "", err
+ }
+ }
+
// Build a map of serial and identity sequences that should be skipped
// Serial sequences are identified by checking if their owner columns match the serial pattern
// Identity sequences are identified by checking if their owner columns have IdentityGeneration set
@@ -3566,6 +3638,25 @@ func GetMultiFileDatabaseDefinition(ctx schema.GetDefinitionContext, metadata *s
}
}
+ // Generate extensions.sql file if there are any extensions
+ if len(metadata.Extensions) > 0 {
+ var buf strings.Builder
+ for i, extension := range metadata.Extensions {
+ if i > 0 {
+ buf.WriteString("\n")
+ }
+
+ if err := writeExtension(&buf, extension); err != nil {
+ return nil, errors.Wrapf(err, "failed to generate extension SDL for %s", extension.Name)
+ }
+ }
+
+ files = append(files, schema.File{
+ Name: "extensions.sql",
+ Content: buf.String(),
+ })
+ }
+
return &schema.MultiFileSchemaResult{Files: files}, nil
}
diff --git a/backend/plugin/schema/pg/get_sdl_diff.go b/backend/plugin/schema/pg/get_sdl_diff.go
index 4e3aef240f..509ee4ccf5 100644
--- a/backend/plugin/schema/pg/get_sdl_diff.go
+++ b/backend/plugin/schema/pg/get_sdl_diff.go
@@ -103,6 +103,9 @@ func GetSDLDiff(currentSDLText, previousUserSDLText string, currentSchema, previ
// Process enum type changes
processEnumTypeChanges(currentChunks, previousChunks, currentDBSDLChunks, diff)
+ // Process extension changes
+ processExtensionChanges(currentChunks, previousChunks, currentDBSDLChunks, diff)
+
// Process explicit schema changes (CREATE SCHEMA statements)
processSchemaChanges(currentChunks, previousChunks, currentSchema, diff)
@@ -127,6 +130,7 @@ func ChunkSDLText(sdlText string) (*schema.SDLChunks, error) {
Sequences: make(map[string]*schema.SDLChunk),
Schemas: make(map[string]*schema.SDLChunk),
EnumTypes: make(map[string]*schema.SDLChunk),
+ Extensions: make(map[string]*schema.SDLChunk),
ColumnComments: make(map[string]map[string]antlr.ParserRuleContext),
IndexComments: make(map[string]map[string]antlr.ParserRuleContext),
}, nil
@@ -148,6 +152,7 @@ func ChunkSDLText(sdlText string) (*schema.SDLChunks, error) {
Sequences: make(map[string]*schema.SDLChunk),
Schemas: make(map[string]*schema.SDLChunk),
EnumTypes: make(map[string]*schema.SDLChunk),
+ Extensions: make(map[string]*schema.SDLChunk),
ColumnComments: make(map[string]map[string]antlr.ParserRuleContext),
IndexComments: make(map[string]map[string]antlr.ParserRuleContext),
},
@@ -432,6 +437,23 @@ func (l *sdlChunkExtractor) EnterCreateschemastmt(ctx *parser.CreateschemastmtCo
}
}
+func (l *sdlChunkExtractor) EnterCreateextensionstmt(ctx *parser.CreateextensionstmtContext) {
+ // Extract extension name from AST
+ if ctx.Name() == nil {
+ return
+ }
+
+ extensionName := pgparser.NormalizePostgreSQLName(ctx.Name())
+
+ // Extension is database-level, no schema prefix needed
+ chunk := &schema.SDLChunk{
+ Identifier: extensionName, // Just the extension name
+ ASTNode: ctx,
+ }
+
+ l.chunks.Extensions[extensionName] = chunk
+}
+
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
@@ -648,12 +670,14 @@ func (l *sdlChunkExtractor) EnterCommentstmt(ctx *parser.CommentstmtContext) {
return
}
- // Check for object_type_name: SCHEMA, DATABASE, etc.
+ // Check for object_type_name: SCHEMA, EXTENSION, DATABASE, etc.
if ctx.Object_type_name() != nil && ctx.Name() != nil {
objectType := ctx.Object_type_name().GetText()
name := pgparser.NormalizePostgreSQLName(ctx.Name())
- if strings.ToUpper(objectType) == "SCHEMA" {
+ objectTypeUpper := strings.ToUpper(objectType)
+ switch objectTypeUpper {
+ case "SCHEMA":
if chunk, exists := l.chunks.Schemas[name]; exists {
chunk.CommentStatements = append(chunk.CommentStatements, ctx)
} else {
@@ -664,6 +688,20 @@ func (l *sdlChunkExtractor) EnterCommentstmt(ctx *parser.CommentstmtContext) {
}
l.chunks.Schemas[name] = chunk
}
+ case "EXTENSION":
+ // Extensions are database-level, no schema prefix
+ if chunk, exists := l.chunks.Extensions[name]; exists {
+ chunk.CommentStatements = append(chunk.CommentStatements, ctx)
+ } else {
+ chunk := &schema.SDLChunk{
+ Identifier: name,
+ ASTNode: nil,
+ CommentStatements: []antlr.ParserRuleContext{ctx},
+ }
+ l.chunks.Extensions[name] = chunk
+ }
+ default:
+ // Other object types are handled elsewhere
}
return
}
@@ -2736,6 +2774,13 @@ func applyMinimalChangesToChunks(previousChunks *schema.SDLChunks, currentSchema
return errors.Wrap(err, "failed to apply enum type changes")
}
+ // Process extension changes: apply minimal changes to extension chunks
+ // Extensions are database-level objects
+ err = applyExtensionChangesToChunks(previousChunks, currentSchema, previousSchema)
+ if err != nil {
+ return errors.Wrap(err, "failed to apply extension changes")
+ }
+
// Process column comment changes: sync column comments based on metadata
err = applyColumnCommentChanges(previousChunks, currentSchema, previousSchema)
if err != nil {
@@ -3405,6 +3450,14 @@ func buildCurrentDatabaseSDLChunks(currentSchema *model.DatabaseSchema) (*curren
sdlChunks.comments[identifier] = []string{commentText}
}
}
+ for extensionName, chunk := range currentSDLChunks.Extensions {
+ sdlChunks.chunks[extensionName] = strings.TrimSpace(chunk.GetTextWithoutComments())
+ // Store comment text for usability check
+ commentText := extractCommentTextFromChunk(chunk)
+ if commentText != "" {
+ sdlChunks.comments[extensionName] = []string{commentText}
+ }
+ }
return sdlChunks, nil
}
@@ -5275,6 +5328,7 @@ func processCommentChanges(currentChunks, previousChunks *schema.SDLChunks, curr
processObjectComments(currentChunks.MaterializedViews, previousChunks.MaterializedViews, schema.CommentObjectTypeMaterializedView, createdObjects, droppedObjects, currentDBSDLChunks, diff)
processObjectComments(currentChunks.Functions, previousChunks.Functions, schema.CommentObjectTypeFunction, createdObjects, droppedObjects, currentDBSDLChunks, diff)
processObjectComments(currentChunks.Sequences, previousChunks.Sequences, schema.CommentObjectTypeSequence, createdObjects, droppedObjects, currentDBSDLChunks, diff)
+ processObjectComments(currentChunks.Extensions, previousChunks.Extensions, schema.CommentObjectTypeExtension, createdObjects, droppedObjects, currentDBSDLChunks, diff)
processObjectComments(currentChunks.EnumTypes, previousChunks.EnumTypes, schema.CommentObjectTypeType, createdObjects, droppedObjects, currentDBSDLChunks, diff)
processObjectComments(currentChunks.Indexes, previousChunks.Indexes, schema.CommentObjectTypeIndex, createdObjects, droppedObjects, currentDBSDLChunks, diff)
processObjectComments(currentChunks.Schemas, previousChunks.Schemas, schema.CommentObjectTypeSchema, createdObjects, droppedObjects, currentDBSDLChunks, diff)
@@ -5329,6 +5383,13 @@ func buildCreatedObjectsSet(diff *schema.MetadataDiff) map[string]bool {
}
}
+ for _, extDiff := range diff.ExtensionChanges {
+ if extDiff.Action == schema.MetadataDiffActionCreate {
+ // Extensions are database-level, no schema prefix
+ created[extDiff.ExtensionName] = true
+ }
+ }
+
return created
}
@@ -5378,6 +5439,13 @@ func buildDroppedObjectsSet(diff *schema.MetadataDiff) map[string]bool {
}
}
+ for _, extDiff := range diff.ExtensionChanges {
+ if extDiff.Action == schema.MetadataDiffActionDrop {
+ // Extensions are database-level, no schema prefix
+ dropped[extDiff.ExtensionName] = true
+ }
+ }
+
return dropped
}
@@ -5410,12 +5478,16 @@ func processObjectComments(currentMap, previousMap map[string]*schema.SDLChunk,
}
var schemaName, objectName string
- // For SCHEMA objects, identifier is just the schema name
+ // For SCHEMA and EXTENSION objects, identifier is just the object name (database-level)
// For other objects, identifier is "schema.object"
- if objectType == schema.CommentObjectTypeSchema {
+ switch objectType {
+ case schema.CommentObjectTypeSchema:
schemaName = identifier
objectName = identifier // For schemas, objectName is also the schema name
- } else {
+ case schema.CommentObjectTypeExtension:
+ schemaName = "" // Extensions are database-level, no schema
+ objectName = identifier
+ default:
schemaName, objectName = parseIdentifier(identifier)
}
@@ -6545,6 +6617,98 @@ func processEnumTypeChanges(currentChunks, previousChunks *schema.SDLChunks, cur
}
}
+// processExtensionChanges processes extension changes between current and previous chunks
+func processExtensionChanges(currentChunks, previousChunks *schema.SDLChunks, currentDBSDLChunks *currentDatabaseSDLChunks, diff *schema.MetadataDiff) {
+ // Process current extensions to find created and modified ones
+ for extensionName, currentChunk := range currentChunks.Extensions {
+ if previousChunk, exists := previousChunks.Extensions[extensionName]; exists {
+ // Extension exists in both - check if modified by comparing text (excluding comments)
+ currentText := currentChunk.GetTextWithoutComments()
+ previousText := previousChunk.GetTextWithoutComments()
+ if currentText != previousText {
+ // Apply usability check
+ if currentDBSDLChunks.shouldSkipChunkDiffForUsability(currentText, extensionName) {
+ continue
+ }
+ // Extension was modified - use DROP + CREATE pattern
+ // (PostgreSQL doesn't support ALTER EXTENSION for most changes)
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &schema.ExtensionDiff{
+ Action: schema.MetadataDiffActionDrop,
+ ExtensionName: extensionName,
+ OldExtension: nil,
+ NewExtension: nil,
+ OldASTNode: previousChunk.ASTNode,
+ NewASTNode: nil,
+ })
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &schema.ExtensionDiff{
+ Action: schema.MetadataDiffActionCreate,
+ ExtensionName: extensionName,
+ OldExtension: nil,
+ NewExtension: nil,
+ OldASTNode: nil,
+ NewASTNode: currentChunk.ASTNode,
+ })
+ // Add COMMENT ON EXTENSION diffs if they exist in the new version
+ if len(currentChunk.CommentStatements) > 0 {
+ for _, commentNode := range currentChunk.CommentStatements {
+ commentText := extractCommentTextFromNode(commentNode)
+ diff.CommentChanges = append(diff.CommentChanges, &schema.CommentDiff{
+ Action: schema.MetadataDiffActionCreate,
+ ObjectType: schema.CommentObjectTypeExtension,
+ ObjectName: extensionName,
+ OldComment: "",
+ NewComment: commentText,
+ OldASTNode: nil,
+ NewASTNode: commentNode,
+ })
+ }
+ }
+ }
+ // If text is identical, skip - no changes detected
+ } else {
+ // New extension
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &schema.ExtensionDiff{
+ Action: schema.MetadataDiffActionCreate,
+ ExtensionName: extensionName,
+ OldExtension: nil,
+ NewExtension: nil,
+ OldASTNode: nil,
+ NewASTNode: currentChunk.ASTNode,
+ })
+ // Add COMMENT ON EXTENSION diffs if they exist
+ if len(currentChunk.CommentStatements) > 0 {
+ for _, commentNode := range currentChunk.CommentStatements {
+ commentText := extractCommentTextFromNode(commentNode)
+ diff.CommentChanges = append(diff.CommentChanges, &schema.CommentDiff{
+ Action: schema.MetadataDiffActionCreate,
+ ObjectType: schema.CommentObjectTypeExtension,
+ ObjectName: extensionName,
+ OldComment: "",
+ NewComment: commentText,
+ OldASTNode: nil,
+ NewASTNode: commentNode,
+ })
+ }
+ }
+ }
+ }
+
+ // Process previous extensions to find dropped ones
+ for extensionName, previousChunk := range previousChunks.Extensions {
+ if _, exists := currentChunks.Extensions[extensionName]; !exists {
+ // Extension was dropped
+ diff.ExtensionChanges = append(diff.ExtensionChanges, &schema.ExtensionDiff{
+ Action: schema.MetadataDiffActionDrop,
+ ExtensionName: extensionName,
+ OldExtension: nil,
+ NewExtension: nil,
+ OldASTNode: previousChunk.ASTNode,
+ NewASTNode: nil,
+ })
+ }
+ }
+}
+
// processSchemaChanges processes explicit CREATE SCHEMA statements in the SDL
func processSchemaChanges(currentChunks, previousChunks *schema.SDLChunks, currentSchema *model.DatabaseSchema, diff *schema.MetadataDiff) {
// Build set of existing schemas in current database
@@ -6686,3 +6850,263 @@ func addImplicitSchemaCreation(diff *schema.MetadataDiff, currentSchema *model.D
}
}
}
+
+// applyExtensionChangesToChunks applies minimal changes to extension chunks based on schema differences
+// Extensions are database-level objects (not schema-scoped)
+func applyExtensionChangesToChunks(previousChunks *schema.SDLChunks, currentSchema, previousSchema *model.DatabaseSchema) error {
+ if currentSchema == nil || previousSchema == nil || previousChunks == nil {
+ return nil
+ }
+
+ // Get extension differences by comparing schema metadata
+ currentMetadata := currentSchema.GetMetadata()
+ previousMetadata := previousSchema.GetMetadata()
+ if currentMetadata == nil || previousMetadata == nil {
+ return nil
+ }
+
+ // Build extension maps for current and previous schemas
+ // Extensions are database-level, stored directly in DatabaseSchemaMetadata
+ currentExtensions := make(map[string]*storepb.ExtensionMetadata)
+ previousExtensions := make(map[string]*storepb.ExtensionMetadata)
+
+ // Collect all extensions from current schema
+ for _, extension := range currentMetadata.Extensions {
+ // Extension key is just the name (database-level, no schema prefix)
+ currentExtensions[extension.Name] = extension
+ }
+
+ // Collect all extensions from previous schema
+ for _, extension := range previousMetadata.Extensions {
+ previousExtensions[extension.Name] = extension
+ }
+
+ // Process extension additions: create new extension chunks
+ for extensionName, currentExtension := range currentExtensions {
+ if _, exists := previousExtensions[extensionName]; !exists {
+ // New extension - create a chunk for it
+ err := createExtensionChunk(previousChunks, currentExtension)
+ if err != nil {
+ return errors.Wrapf(err, "failed to create extension chunk for %s", extensionName)
+ }
+ }
+ }
+
+ // Process extension modifications: update existing chunks
+ for extensionName, currentExtension := range currentExtensions {
+ if previousExtension, exists := previousExtensions[extensionName]; exists {
+ // Extension exists in both metadata
+ // Only update if chunk exists in SDL (user explicitly defined it)
+ if _, chunkExists := previousChunks.Extensions[extensionName]; chunkExists {
+ // Chunk exists - update if needed
+ err := updateExtensionChunkIfNeeded(previousChunks, currentExtension, previousExtension)
+ if err != nil {
+ return errors.Wrapf(err, "failed to update extension chunk for %s", extensionName)
+ }
+ }
+ // If chunk doesn't exist, skip - user didn't define this extension in SDL
+ }
+ }
+
+ // Process extension deletions: remove dropped extension chunks
+ for extensionName := range previousExtensions {
+ if _, exists := currentExtensions[extensionName]; !exists {
+ // Extension was dropped - remove it from chunks
+ deleteExtensionChunk(previousChunks, extensionName)
+ }
+ }
+
+ return nil
+}
+
+// createExtensionChunk creates a new CREATE EXTENSION chunk and adds it to the chunks
+func createExtensionChunk(chunks *schema.SDLChunks, extension *storepb.ExtensionMetadata) error {
+ if extension == nil || chunks == nil {
+ return nil
+ }
+
+ // Generate SDL text for the extension
+ extensionSDL := generateCreateExtensionSQL(extension)
+ if extensionSDL == "" {
+ return errors.New("failed to generate SDL for extension")
+ }
+
+ // Parse the SDL to get AST node
+ parseResult, err := pgparser.ParsePostgreSQL(extensionSDL)
+ if err != nil {
+ return errors.Wrapf(err, "failed to parse generated extension SDL: %s", extensionSDL)
+ }
+
+ // Extract the CREATE EXTENSION AST node
+ var extensionASTNode *parser.CreateextensionstmtContext
+ antlr.ParseTreeWalkerDefault.Walk(&extensionExtractor{
+ result: &extensionASTNode,
+ }, parseResult.Tree)
+
+ if extensionASTNode == nil {
+ return errors.New("failed to extract CREATE EXTENSION AST node")
+ }
+
+ // Create and add the chunk
+ chunk := &schema.SDLChunk{
+ Identifier: extension.Name, // Extensions are database-level, no schema prefix
+ ASTNode: extensionASTNode,
+ }
+
+ // Handle comment if present (description field is the comment)
+ if len(extension.Description) > 0 {
+ commentSQL := generateCommentOnExtensionSQL(extension.Name, extension.Description)
+ commentParseResult, err := pgparser.ParsePostgreSQL(commentSQL)
+ if err == nil {
+ var commentNode *parser.CommentstmtContext
+ antlr.ParseTreeWalkerDefault.Walk(&commentExtractor{
+ result: &commentNode,
+ }, commentParseResult.Tree)
+ if commentNode != nil {
+ chunk.CommentStatements = []antlr.ParserRuleContext{commentNode}
+ }
+ }
+ }
+
+ chunks.Extensions[extension.Name] = chunk
+ return nil
+}
+
+// updateExtensionChunkIfNeeded updates an extension chunk if the definition or comment changed
+func updateExtensionChunkIfNeeded(chunks *schema.SDLChunks, currentExtension, previousExtension *storepb.ExtensionMetadata) error {
+ if currentExtension == nil || previousExtension == nil {
+ return nil
+ }
+
+ chunk, exists := chunks.Extensions[currentExtension.Name]
+ if !exists {
+ return errors.Errorf("extension chunk not found for %s", currentExtension.Name)
+ }
+
+ // Check if the extension definition has changed (schema, version, or description)
+ definitionChanged := !extensionsEqual(currentExtension, previousExtension)
+
+ if definitionChanged {
+ // Extension definition has changed - regenerate the CREATE EXTENSION chunk
+ extensionSDL := generateCreateExtensionSQL(currentExtension)
+ if extensionSDL == "" {
+ return errors.New("failed to generate SDL for extension")
+ }
+
+ // Parse the SDL to get AST node
+ parseResult, err := pgparser.ParsePostgreSQL(extensionSDL)
+ if err != nil {
+ return errors.Wrapf(err, "failed to parse generated extension SDL: %s", extensionSDL)
+ }
+
+ // Extract the CREATE EXTENSION AST node
+ var extensionASTNode *parser.CreateextensionstmtContext
+ antlr.ParseTreeWalkerDefault.Walk(&extensionExtractor{
+ result: &extensionASTNode,
+ }, parseResult.Tree)
+
+ if extensionASTNode == nil {
+ return errors.New("failed to extract CREATE EXTENSION AST node")
+ }
+
+ // Update the AST node in the chunk
+ chunk.ASTNode = extensionASTNode
+ }
+
+ // Handle comment changes (description field)
+ commentChanged := currentExtension.Description != previousExtension.Description
+
+ if commentChanged {
+ // Remove old comment statements
+ chunk.CommentStatements = nil
+
+ // Add new comment if present
+ if len(currentExtension.Description) > 0 {
+ commentSQL := generateCommentOnExtensionSQL(currentExtension.Name, currentExtension.Description)
+ commentParseResult, err := pgparser.ParsePostgreSQL(commentSQL)
+ if err == nil {
+ var commentNode *parser.CommentstmtContext
+ antlr.ParseTreeWalkerDefault.Walk(&commentExtractor{
+ result: &commentNode,
+ }, commentParseResult.Tree)
+ if commentNode != nil {
+ chunk.CommentStatements = []antlr.ParserRuleContext{commentNode}
+ }
+ }
+ }
+ }
+
+ return nil
+}
+
+// deleteExtensionChunk removes an extension chunk from the chunks map
+func deleteExtensionChunk(chunks *schema.SDLChunks, extensionName string) {
+ if chunks == nil {
+ return
+ }
+ delete(chunks.Extensions, extensionName)
+}
+
+// generateCreateExtensionSQL generates a CREATE EXTENSION IF NOT EXISTS statement
+func generateCreateExtensionSQL(extension *storepb.ExtensionMetadata) string {
+ if extension == nil {
+ return ""
+ }
+
+ var buf strings.Builder
+ buf.WriteString(`CREATE EXTENSION IF NOT EXISTS "`)
+ buf.WriteString(extension.Name)
+ buf.WriteString(`"`)
+
+ // Add WITH SCHEMA clause if schema is specified
+ if extension.Schema != "" {
+ buf.WriteString(` WITH SCHEMA "`)
+ buf.WriteString(extension.Schema)
+ buf.WriteString(`"`)
+ }
+
+ // Add VERSION clause if version is specified
+ if extension.Version != "" {
+ buf.WriteString(` VERSION '`)
+ buf.WriteString(extension.Version)
+ buf.WriteString(`'`)
+ }
+
+ buf.WriteString(`;`)
+
+ return buf.String()
+}
+
+// generateCommentOnExtensionSQL generates a COMMENT ON EXTENSION statement
+func generateCommentOnExtensionSQL(extensionName, comment string) string {
+ // Escape single quotes in comment
+ escapedComment := strings.ReplaceAll(comment, "'", "''")
+ return fmt.Sprintf("COMMENT ON EXTENSION \"%s\" IS '%s';", extensionName, escapedComment)
+}
+
+// extensionExtractor is a walker to extract CREATE EXTENSION AST nodes
+type extensionExtractor struct {
+ parser.BasePostgreSQLParserListener
+ result **parser.CreateextensionstmtContext
+}
+
+func (e *extensionExtractor) EnterCreateextensionstmt(ctx *parser.CreateextensionstmtContext) {
+ if e.result != nil {
+ *e.result = ctx
+ }
+}
+
+// extensionsEqual compares two extension metadata for equality (excluding comments)
+func extensionsEqual(a, b *storepb.ExtensionMetadata) bool {
+ if a == nil && b == nil {
+ return true
+ }
+ if a == nil || b == nil {
+ return false
+ }
+
+ return a.Name == b.Name &&
+ a.Schema == b.Schema &&
+ a.Version == b.Version &&
+ a.Description == b.Description
+}
diff --git a/backend/plugin/schema/sdl_differ.go b/backend/plugin/schema/sdl_differ.go
index f05aeff25b..8b0c5c8d23 100644
--- a/backend/plugin/schema/sdl_differ.go
+++ b/backend/plugin/schema/sdl_differ.go
@@ -125,6 +125,7 @@ type SDLChunks struct {
Sequences map[string]*SDLChunk // key: sequence name/identifier
Schemas map[string]*SDLChunk // key: schema name/identifier
EnumTypes map[string]*SDLChunk // key: enum type name/identifier
+ Extensions map[string]*SDLChunk // key: extension name/identifier
// Column comments: map[schemaName.tableName][columnName] -> COMMENT ON COLUMN AST node
ColumnComments map[string]map[string]antlr.ParserRuleContext
diff --git a/docs/adding-new-object-to-sdl-mode.md b/docs/adding-new-object-to-sdl-mode.md
index 665b1f98ab..f0845521f2 100644
--- a/docs/adding-new-object-to-sdl-mode.md
+++ b/docs/adding-new-object-to-sdl-mode.md
@@ -1840,6 +1840,116 @@ func TestMaterializedViewDependencyOrder(t *testing.T) {
---
+## Phase 6: Integration Points (CRITICAL - Often Forgotten!)
+
+This phase covers integration points that are **not** in the main implementation flow but are **critical** for production usage.
+
+### 6.1 Archive Schema Filter (CRITICAL!)
+
+**File**: `backend/plugin/schema/differ.go` - `FilterPostgresArchiveSchema` function
+
+The `FilterPostgresArchiveSchema` function filters out objects from the `bbdataarchive` schema. This is called in **every** `bb rollout` execution.
+
+**⚠️ CRITICAL**: If you forget to add your object type here, it will be correctly detected in diff but **filtered out during execution**!
+
+#### For Database-level Objects (Extensions, Events)
+
+Database-level objects are stored directly in `DatabaseSchemaMetadata` (not in `SchemaMetadata`). They don't have a schema name, so they should be **copied directly** without filtering:
+
+```go
+// Extensions and Events are database-level objects, not schema-specific, so copy them all
+filtered.ExtensionChanges = diff.ExtensionChanges
+filtered.EventChanges = diff.EventChanges
+```
+
+#### For Schema-scoped Objects (Tables, Views, Functions, etc.)
+
+Schema-scoped objects must be **filtered by schema name**:
+
+```go
+// Filter table changes
+for _, tableChange := range diff.TableChanges {
+ if tableChange.SchemaName != archiveSchemaName {
+ filtered.TableChanges = append(filtered.TableChanges, tableChange)
+ }
+}
+```
+
+#### Example Implementation
+
+**Before** (missing ExtensionChanges):
+```go
+func FilterPostgresArchiveSchema(diff *MetadataDiff) *MetadataDiff {
+ // ... filter schema-scoped objects ...
+
+ // Events are database-level objects, not schema-specific, so copy them all
+ filtered.EventChanges = diff.EventChanges
+
+ return filtered // ❌ ExtensionChanges are lost!
+}
+```
+
+**After** (correct):
+```go
+func FilterPostgresArchiveSchema(diff *MetadataDiff) *MetadataDiff {
+ // ... filter schema-scoped objects ...
+
+ // Extensions and Events are database-level objects, not schema-specific, so copy them all
+ filtered.ExtensionChanges = diff.ExtensionChanges // ✅ Added
+ filtered.EventChanges = diff.EventChanges
+
+ return filtered
+}
+```
+
+#### Symptoms of Forgetting This
+
+- ✅ SDL parsing works correctly
+- ✅ Diff calculation detects changes correctly
+- ✅ All unit tests pass
+- ❌ **bb rollout execution silently drops the object**
+- ❌ Dependent objects fail with "relation does not exist" errors
+
+**Real-world example**: Extension implementation forgot this, causing:
+```
+ERROR: type "citext" does not exist (SQLSTATE 42704)
+```
+Even though the SDL file contained `CREATE EXTENSION "citext"` and the diff correctly detected it!
+
+#### Test for This
+
+Always add a filter test to catch this issue:
+
+```go
+func TestXXXNotFilteredByArchiveSchemaFilter(t *testing.T) {
+ diff := &schema.MetadataDiff{
+ ExtensionChanges: []*schema.ExtensionDiff{
+ {
+ Action: schema.MetadataDiffActionCreate,
+ ExtensionName: "test_extension",
+ },
+ },
+ TableChanges: []*schema.TableDiff{
+ {
+ Action: schema.MetadataDiffActionCreate,
+ SchemaName: "bbdataarchive", // Should be filtered
+ TableName: "archive_table",
+ },
+ },
+ }
+
+ filtered := schema.FilterPostgresArchiveSchema(diff)
+
+ // Extension should be preserved (database-level)
+ require.Equal(t, 1, len(filtered.ExtensionChanges))
+
+ // Archive schema table should be filtered out
+ require.Equal(t, 0, len(filtered.TableChanges))
+}
+```
+
+---
+
## Critical Points & Common Pitfalls
### 🚨 Most Common Mistakes
@@ -1914,6 +2024,41 @@ case "MATERIALIZED VIEW", "MATERIALIZEDVIEW":
// handle comment
```
+#### 6. Forgetting to Update Archive Schema Filter (CRITICAL!)
+
+**The #1 mistake that breaks production but passes all tests!**
+
+**Problem**: Adding the object to all processing functions but forgetting `FilterPostgresArchiveSchema`.
+
+**Symptom**:
+- ✅ All tests pass
+- ✅ SDL parsing works
+- ✅ Diff detection works
+- ❌ **bb rollout silently drops the object during execution**
+
+**Why it happens**: The filter function is **not** in the normal implementation flow. It's an integration point that only gets called during actual `bb rollout` execution.
+
+**Fix**: Always check and update both patterns:
+
+**For database-level objects** (Extensions, Events):
+```go
+// In FilterPostgresArchiveSchema:
+filtered.ExtensionChanges = diff.ExtensionChanges // Direct copy
+filtered.EventChanges = diff.EventChanges
+```
+
+**For schema-scoped objects** (Tables, Views, etc.):
+```go
+// In FilterPostgresArchiveSchema:
+for _, tableChange := range diff.TableChanges {
+ if tableChange.SchemaName != archiveSchemaName {
+ filtered.TableChanges = append(filtered.TableChanges, tableChange)
+ }
+}
+```
+
+**Prevention**: Always add a `TestXXXNotFilteredByArchiveSchemaFilter` test (see Phase 6.1).
+
---
### ✅ Verification Checklist
@@ -1975,17 +2120,22 @@ Use this checklist to ensure complete implementation:
- [ ] All tests pass
- [ ] Linter passes
+#### Integration Points (CRITICAL!)
+- [ ] **Added to `FilterPostgresArchiveSchema` (database-level: direct copy; schema-scoped: filter by schema)**
+- [ ] **Filter test added (`TestXXXNotFilteredByArchiveSchemaFilter`)**
+
---
## Summary
-Adding a new database object to SDL mode requires changes in **5 major phases**:
+Adding a new database object to SDL mode requires changes in **6 major phases**:
1. **Parser**: Extract AST nodes and associate COMMENT statements
2. **SDL Diff**: Detect CREATE/DROP/MODIFY and comment-only changes + **Drift handling (REQUIRED)**
3. **Migration Generation**: Add to topological sort with **AST-only dependency extraction** (both CREATE and DROP!)
4. **SDL Output**: Generate single-file and multi-file SDL formats
5. **Testing**: Comprehensive tests including dependency ordering
+6. **Integration Points**: Update `FilterPostgresArchiveSchema` and add filter test
The **most critical** and **most often forgotten** parts are:
@@ -2007,3 +2157,23 @@ Without this, the object type will not work correctly when:
- Database schema differs from SDL (drift detection)
All other object types (tables, views, functions, sequences, materialized views) implement drift handling. Your new object type must too.
+
+### 3. Archive schema filter (MOST CRITICAL - Breaks production!)
+> **Add object to `FilterPostgresArchiveSchema` in `differ.go`**
+
+This is **the #1 mistake** that:
+- ✅ Passes all unit tests
+- ✅ Works correctly in SDL parsing and diff calculation
+- ❌ **Silently fails in production `bb rollout`**
+
+Without this:
+- The object will be correctly detected in diff
+- But **filtered out** before migration execution
+- Causing "relation does not exist" errors for dependent objects
+
+**Prevention**:
+- For database-level objects: `filtered.ExtensionChanges = diff.ExtensionChanges`
+- For schema-scoped objects: Filter by `schemaName != archiveSchemaName`
+- Always add `TestXXXNotFilteredByArchiveSchemaFilter` test
+
+See **Phase 6.1** for detailed explanation and real-world example.