feat(db): add --use-shadow-db flag to test db command

Runs pgTAP tests against an ephemeral shadow database built from
migrations, keeping the local dev database untouched. Reuses the
existing CreateShadowDatabase/MigrateShadowDatabase machinery from
db diff. Uses host networking so pg_prove can reach the shadow
container via 127.0.0.1:<shadow_port>.

Author: lightstrike

cmd/db.go

@@ -238,7 +238,8 @@ var (
 		Use:    "test [path] ...",
 		Short:  "Tests local database with pgTAP",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return test.Run(cmd.Context(), args, flags.DbConfig, afero.NewOsFs())
+			useShadow, _ := cmd.Flags().GetBool("use-shadow-db")
+			return test.Run(cmd.Context(), args, flags.DbConfig, useShadow, afero.NewOsFs())
 		},
 	}
 )
@@ -349,6 +350,7 @@ func init() {
 	testFlags.String("db-url", "", "Tests the database specified by the connection string (must be percent-encoded).")
 	testFlags.Bool("linked", false, "Runs pgTAP tests on the linked project.")
 	testFlags.Bool("local", true, "Runs pgTAP tests on the local database.")
+	testFlags.Bool("use-shadow-db", false, "Creates a temporary database from migrations for running tests in isolation.")
 	dbTestCmd.MarkFlagsMutuallyExclusive("db-url", "linked", "local")
 	rootCmd.AddCommand(dbCmd)
 }

cmd/test.go

@@ -41,6 +41,7 @@ func init() {
 	dbFlags.String("db-url", "", "Tests the database specified by the connection string (must be percent-encoded).")
 	dbFlags.Bool("linked", false, "Runs pgTAP tests on the linked project.")
 	dbFlags.Bool("local", true, "Runs pgTAP tests on the local database.")
+	dbFlags.Bool("use-shadow-db", false, "Creates a temporary database from migrations for running tests in isolation.")
 	testDbCmd.MarkFlagsMutuallyExclusive("db-url", "linked", "local")
 	testCmd.AddCommand(testDbCmd)
 	// Build new command

internal/db/test/test.go

@@ -16,6 +16,8 @@ import (
 	"github.com/jackc/pgx/v4"
 	"github.com/spf13/afero"
 	"github.com/spf13/viper"
+	"github.com/supabase/cli/internal/db/diff"
+	"github.com/supabase/cli/internal/db/start"
 	"github.com/supabase/cli/internal/utils"
 	cliConfig "github.com/supabase/cli/pkg/config"
 )
@@ -25,7 +27,31 @@ const (
 	DISABLE_PGTAP = "drop extension if exists pgtap"
 )
 
-func Run(ctx context.Context, testFiles []string, config pgconn.Config, fsys afero.Fs, options ...func(*pgx.ConnConfig)) error {
+func Run(ctx context.Context, testFiles []string, config pgconn.Config, useShadowDb bool, fsys afero.Fs, options ...func(*pgx.ConnConfig)) error {
+	// Create and migrate shadow database if requested
+	if useShadowDb {
+		fmt.Fprintln(os.Stderr, "Creating shadow database for testing...")
+		shadow, err := diff.CreateShadowDatabase(ctx, utils.Config.Db.ShadowPort)
+		if err != nil {
+			return err
+		}
+		defer utils.DockerRemove(shadow)
+		if err := start.WaitForHealthyService(ctx, utils.Config.Db.HealthTimeout, shadow); err != nil {
+			return err
+		}
+		if err := diff.MigrateShadowDatabase(ctx, shadow, fsys, options...); err != nil {
+			return err
+		}
+		// Override config to point at shadow DB
+		config = pgconn.Config{
+			Host:     utils.Config.Hostname,
+			Port:     utils.Config.Db.ShadowPort,
+			User:     "postgres",
+			Password: utils.Config.Db.Password,
+			Database: "postgres",
+		}
+		fmt.Fprintln(os.Stderr, "Shadow database ready. Running tests...")
+	}
 	// Build test command
 	if len(testFiles) == 0 {
 		absTestsDir, err := filepath.Abs(utils.DbTestsDir)
@@ -79,7 +105,11 @@ func Run(ctx context.Context, testFiles []string, config pgconn.Config, fsys afe
 	// Use custom network when connecting to local database
 	// disable selinux via security-opt to allow pg-tap to work properly
 	hostConfig := container.HostConfig{Binds: binds, SecurityOpt: []string{"label:disable"}}
-	if utils.IsLocalDatabase(config) {
+	if useShadowDb {
+		// Shadow container has no Docker DNS alias; use host networking
+		// so pg_prove reaches it via 127.0.0.1:<ShadowPort>
+		hostConfig.NetworkMode = network.NetworkHost
+	} else if utils.IsLocalDatabase(config) {
 		config.Host = utils.DbAliases[0]
 		config.Port = 5432
 	} else {

internal/db/test/test_test.go

@@ -44,7 +44,7 @@ func TestRunCommand(t *testing.T) {
 		apitest.MockDockerStart(utils.Docker, utils.GetRegistryImageUrl(config.Images.PgProve), containerId)
 		require.NoError(t, apitest.MockDockerLogs(utils.Docker, containerId, "Result: SUCCESS"))
 		// Run test
-		err := Run(context.Background(), []string{"nested"}, dbConfig, fsys, conn.Intercept)
+		err := Run(context.Background(), []string{"nested"}, dbConfig, false, fsys, conn.Intercept)
 		// Check error
 		assert.NoError(t, err)
 	})
@@ -54,7 +54,7 @@ func TestRunCommand(t *testing.T) {
 		fsys := afero.NewMemMapFs()
 		require.NoError(t, utils.WriteConfig(fsys, false))
 		// Run test
-		err := Run(context.Background(), nil, dbConfig, fsys)
+		err := Run(context.Background(), nil, dbConfig, false, fsys)
 		// Check error
 		assert.ErrorContains(t, err, "failed to connect to postgres")
 	})
@@ -69,7 +69,7 @@ func TestRunCommand(t *testing.T) {
 		conn.Query(ENABLE_PGTAP).
 			ReplyError(pgerrcode.DuplicateObject, `extension "pgtap" already exists, skipping`)
 		// Run test
-		err := Run(context.Background(), nil, dbConfig, fsys, conn.Intercept)
+		err := Run(context.Background(), nil, dbConfig, false, fsys, conn.Intercept)
 		// Check error
 		assert.ErrorContains(t, err, "failed to enable pgTAP")
 	})
@@ -93,7 +93,7 @@ func TestRunCommand(t *testing.T) {
 			Get("/v" + utils.Docker.ClientVersion() + "/images/" + utils.GetRegistryImageUrl(config.Images.PgProve) + "/json").
 			ReplyError(errNetwork)
 		// Run test
-		err := Run(context.Background(), nil, dbConfig, fsys, conn.Intercept)
+		err := Run(context.Background(), nil, dbConfig, false, fsys, conn.Intercept)
 		// Check error
 		assert.ErrorIs(t, err, errNetwork)
 		assert.Empty(t, apitest.ListUnmatchedRequests())

pkg/config/templates/config.toml

@@ -27,7 +27,7 @@ enabled = false
 [db]
 # Port to use for the local database URL.
 port = 54322
-# Port used by db diff command to initialize the shadow database.
+# Port used by db diff and test db commands to initialize the shadow database.
 shadow_port = 54320
 # Maximum amount of time to wait for health check when starting the local database.
 health_timeout = "2m"