feat(cli): set up platform baseline before declarative apply (#5515)

Refs CLI-1601 —
https://linear.app/supabase/issue/CLI-1601/support-auth-dependencies-in-shadow-db-migrations

Provision the Supabase platform schema (auth, storage, realtime, etc.)
on shadow databases before applying declarative schemas, ensuring
Supabase-managed dependencies resolve correctly during both declarative
apply and cache warmup.

## Changes

- **New `SetupShadowDatabase` function** in `diff.go`: Provisions the
platform baseline on a freshly created shadow database without applying
user migrations. This allows declarative apply to share the same
starting point as migration-based workflows.

- **Refactored shadow setup logic**: Extracted common platform baseline
setup into `setupShadowConn` helper, used by both `SetupShadowDatabase`
and `MigrateShadowDatabase` to avoid duplication.

- **Updated declarative apply flow**:
- `Generate` now calls `setupShadowDatabase` when reusing the baseline
shadow for cache warmup
- `getDeclarativeCatalogRef` calls `setupShadowDatabase` before applying
declarative schemas
- This ensures platform objects (auth.sessions, auth.jwt(), etc.) are
available during schema application and cancel out of diffs

- **Added tests**: `TestSetupShadowDatabase` validates that the function
sets up the platform baseline without applying migrations, and the
`Generate` reuse test asserts the baseline is set up before declarative
apply.

## Note on baseline caching

A persistent "replayable SQL" baseline cache (so services don't boot on
cold runs) was considered and intentionally not pursued — the
`supabase/postgres` image pre-bakes part of the `auth` schema (overlap
on replay), a full `pg_dumpall` replay is fragile
(extensions/`shared_preload_libraries`/pgsodium/roles), and a
pg-delta-derived baseline currently drops grants. See CLI-1601 for the
full rationale.

https://claude.ai/code/session_01ACrX8NXcsYLENnCRXAub3S

Co-authored-by: Claude <noreply@anthropic.com>

Author: avallete

apps/cli-go/internal/db/declarative/declarative.go

@@ -58,6 +58,11 @@ var (
 	exportCatalog        = diff.ExportCatalogPgDelta
 	applyDeclarative     = pgdelta.ApplyDeclarative
 	declarativeExportRef = diff.DeclarativeExportPgDeltaRef
+	// setupShadowDatabase provisions the Supabase platform baseline (auth/storage/
+	// realtime) on a shadow database before declarative schemas are applied, so
+	// Supabase-managed dependencies (auth.sessions, auth.jwt(), ...) resolve. It is
+	// a package var so tests can inject a no-op without a real shadow database.
+	setupShadowDatabase = diff.SetupShadowDatabase
 	// generateBaselineCatalogRefResolver allows Generate to reuse a freshly
 	// provisioned baseline shadow for declarative cache warmup.
 	generateBaselineCatalogRefResolver = getGenerateBaselineCatalogRef
@@ -118,6 +123,13 @@ func Generate(ctx context.Context, schema []string, config pgconn.Config, overwr
 	// can reuse it without provisioning another shadow database.
 	if !noCache {
 		if baseline.shadow != nil {
+			// The baseline catalog was already exported from the empty image
+			// baseline above. Set up the platform baseline on the reused shadow
+			// before applying declarative schemas so Supabase-managed dependencies
+			// (auth.sessions, auth.jwt(), ...) resolve during cache warmup.
+			if err := setupShadowDatabase(ctx, baseline.shadow.container, fsys, options...); err != nil {
+				return err
+			}
 			hash, err := hashDeclarativeSchemas(fsys)
 			if err != nil {
 				return err
@@ -392,6 +404,14 @@ func getDeclarativeCatalogRef(ctx context.Context, noCache bool, fsys afero.Fs,
 		return "", err
 	}
 	defer utils.DockerRemove(shadow)
+	// Apply the Supabase platform baseline (auth/storage/realtime) before applying
+	// declarative schemas so dependencies on Supabase-managed objects (auth.sessions,
+	// auth.jwt(), ...) resolve. This keeps the declarative shadow in parity with the
+	// migrations shadow (diff.MigrateShadowDatabase), so platform objects cancel out
+	// of the diff instead of surfacing as spurious changes or "stuck" applies.
+	if err := setupShadowDatabase(ctx, shadow, fsys, options...); err != nil {
+		return "", err
+	}
 	return writeDeclarativeCatalogFromConfig(ctx, config, hash, prefix, noCache, fsys, options...)
 }
 

apps/cli-go/internal/db/declarative/declarative_test.go

@@ -436,16 +436,19 @@ func TestGenerateReusesBaselineShadowForDeclarativeWarmup(t *testing.T) {
 	originalResolver := declarativeCatalogRefResolver
 	originalApplyDeclarative := applyDeclarative
 	originalExportCatalog := exportCatalog
+	originalSetupShadow := setupShadowDatabase
 	t.Cleanup(func() {
 		utils.Config.Experimental.PgDelta = originalPgDelta
 		declarativeExportRef = originalExportRef
 		generateBaselineCatalogRefResolver = originalBaselineResolver
 		declarativeCatalogRefResolver = originalResolver
 		applyDeclarative = originalApplyDeclarative
 		exportCatalog = originalExportCatalog
+		setupShadowDatabase = originalSetupShadow
 	})
 
 	const baselinePath = ".temp/pgdelta/catalog-baseline-test.json"
+	const shadowContainer = "test-shadow-container"
 	shadowConfig := pgconn.Config{
 		Host:     "127.0.0.1",
 		Port:     5432,
@@ -457,10 +460,17 @@ func TestGenerateReusesBaselineShadowForDeclarativeWarmup(t *testing.T) {
 		return generateBaselineCatalogRef{
 			ref: baselinePath,
 			shadow: &shadowSession{
-				config: shadowConfig,
+				container: shadowContainer,
+				config:    shadowConfig,
 			},
 		}, nil
 	}
+	setupCalled := false
+	setupShadowDatabase = func(_ context.Context, container string, _ afero.Fs, _ ...func(*pgx.ConnConfig)) error {
+		setupCalled = true
+		assert.Equal(t, shadowContainer, container)
+		return nil
+	}
 	declarativeExportRef = func(_ context.Context, sourceRef, _ string, _ []string, _ string, _ ...func(*pgx.ConnConfig)) (diff.DeclarativeOutput, error) {
 		assert.Equal(t, baselinePath, sourceRef)
 		return diff.DeclarativeOutput{
@@ -488,6 +498,7 @@ func TestGenerateReusesBaselineShadowForDeclarativeWarmup(t *testing.T) {
 
 	err := Generate(t.Context(), nil, pgconn.Config{Host: "127.0.0.1", Port: 5432, User: "postgres", Password: "postgres", Database: "postgres"}, true, false, fsys)
 	require.NoError(t, err)
+	assert.True(t, setupCalled, "generate should set up the platform baseline on the reused shadow before applying declarative schema")
 	assert.True(t, applyCalled, "generate should apply declarative schema using reused baseline shadow")
 	assert.False(t, fallbackCalled, "fallback declarative resolver should not run when baseline shadow is reusable")
 

apps/cli-go/internal/db/diff/diff.go

@@ -141,6 +141,35 @@ func ConnectShadowDatabase(ctx context.Context, timeout time.Duration, options .
 // Required to bypass pg_cron check: https://github.com/citusdata/pg_cron/blob/main/pg_cron.sql#L3
 const CREATE_TEMPLATE = "CREATE DATABASE contrib_regression TEMPLATE postgres"
 
+// setupShadowConn applies the Supabase platform schema (auth, storage, realtime,
+// etc.) to an already-connected shadow database and creates the pg_cron template
+// database. It deliberately stops short of applying user migrations so that
+// callers which only need the platform baseline (declarative apply) share the
+// exact same starting point as callers that also replay migrations.
+func setupShadowConn(ctx context.Context, conn *pgx.Conn, container string, fsys afero.Fs) error {
+	if err := start.SetupDatabase(ctx, conn, container[:12], os.Stderr, fsys); err != nil {
+		return err
+	}
+	if _, err := conn.Exec(ctx, CREATE_TEMPLATE); err != nil {
+		return errors.Errorf("failed to create template database: %w", err)
+	}
+	return nil
+}
+
+// SetupShadowDatabase provisions the Supabase platform baseline (service schemas
+// such as auth/storage/realtime) on a freshly created shadow database, without
+// applying user migrations. Declarative apply uses this so the shadow matches the
+// real database closely enough for Supabase-managed dependencies (auth.sessions,
+// auth.jwt(), ...) to resolve.
+func SetupShadowDatabase(ctx context.Context, container string, fsys afero.Fs, options ...func(*pgx.ConnConfig)) error {
+	conn, err := ConnectShadowDatabase(ctx, 10*time.Second, options...)
+	if err != nil {
+		return err
+	}
+	defer conn.Close(context.Background())
+	return setupShadowConn(ctx, conn, container, fsys)
+}
+
 func MigrateShadowDatabase(ctx context.Context, container string, fsys afero.Fs, options ...func(*pgx.ConnConfig)) error {
 	migrations, err := migration.ListLocalMigrations(utils.MigrationsDir, afero.NewIOFS(fsys))
 	if err != nil {
@@ -151,12 +180,9 @@ func MigrateShadowDatabase(ctx context.Context, container string, fsys afero.Fs,
 		return err
 	}
 	defer conn.Close(context.Background())
-	if err := start.SetupDatabase(ctx, conn, container[:12], os.Stderr, fsys); err != nil {
+	if err := setupShadowConn(ctx, conn, container, fsys); err != nil {
 		return err
 	}
-	if _, err := conn.Exec(ctx, CREATE_TEMPLATE); err != nil {
-		return errors.Errorf("failed to create template database: %w", err)
-	}
 	return migration.ApplyMigrations(ctx, migrations, conn, afero.NewIOFS(fsys))
 }
 

apps/cli-go/internal/db/diff/diff_test.go

@@ -186,6 +186,49 @@ func TestMigrateShadow(t *testing.T) {
 	})
 }
 
+func TestSetupShadowDatabase(t *testing.T) {
+	utils.Config.Db.MajorVersion = 14
+
+	t.Run("sets up platform baseline without applying migrations", func(t *testing.T) {
+		utils.Config.Db.ShadowPort = 54320
+		utils.GlobalsSql = "create schema public"
+		utils.InitialSchemaPg14Sql = "create schema private"
+		// A migration exists on disk, but SetupShadowDatabase must not apply it:
+		// the mock below only scripts the platform setup + template, so any
+		// migration-history query would surface as an unmatched request.
+		fsys := afero.NewMemMapFs()
+		path := filepath.Join(utils.MigrationsDir, "0_test.sql")
+		require.NoError(t, afero.WriteFile(fsys, path, []byte("create schema test"), 0644))
+		// Setup mock postgres
+		conn := pgtest.NewConn()
+		defer conn.Close(t)
+		conn.Query(utils.GlobalsSql).
+			Reply("CREATE SCHEMA").
+			Query(utils.InitialSchemaPg14Sql).
+			Reply("CREATE SCHEMA").
+			Query(CREATE_TEMPLATE).
+			Reply("CREATE DATABASE")
+		// Run test
+		err := SetupShadowDatabase(context.Background(), "test-shadow-db", fsys, conn.Intercept)
+		// Check error
+		assert.NoError(t, err)
+	})
+
+	t.Run("throws error on globals schema", func(t *testing.T) {
+		utils.Config.Db.ShadowPort = 54320
+		utils.GlobalsSql = "create schema public"
+		// Setup mock postgres
+		conn := pgtest.NewConn()
+		defer conn.Close(t)
+		conn.Query(utils.GlobalsSql).
+			ReplyError(pgerrcode.DuplicateSchema, `schema "public" already exists`)
+		// Run test
+		err := SetupShadowDatabase(context.Background(), "test-shadow-db", afero.NewMemMapFs(), conn.Intercept)
+		// Check error
+		assert.ErrorContains(t, err, `ERROR: schema "public" already exists (SQLSTATE 42P06)`)
+	})
+}
+
 func TestDiffDatabase(t *testing.T) {
 	utils.Config.Db.MajorVersion = 14
 	utils.Config.Db.ShadowPort = 54320