PG Schema Diff

https://github.com/stripe/pg-schema-diff
Admin
Computes differences between Postgres database schemas and generates SQL for minimal downtime...
Tokens:57,115
Snippets:399
Trust Score:9.7
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Example: creating a factory and a temp database

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Shows how to create a temp database factory with `tempdb.NewOnInstanceFactory`, configure it with a root database, a prefix, and a logger, then create a temporary database. The example includes error handling and cleanup via `ContextualCloser`. The resulting `tempDb.ConnPool` is ready for DDL execution or introspection.

```go
tempDbFactory, err := tempdb.NewOnInstanceFactory(ctx,
	func(ctx context.Context, dbName string) (*sql.DB, error) {
		cfg := connConfig.Copy()
		cfg.Database = dbName
		return openDbWithPgxConfig(cfg)
	},
	tempdb.WithRootDatabase(connConfig.Database),
	tempdb.WithDbPrefix("mycompany_tmp_"),
	tempdb.WithLogger(log.SimpleLogger()),
)
if err != nil {
	panic("creating temp db factory")
}
defer tempDbFactory.Close()

tempDb, err := tempDbFactory.Create(ctx)
if err != nil {
	panic("creating temp db")
}
defer func(closer tempdb.ContextualCloser) {
	if err := closer.Close(ctx); err != nil {
		panic(err) // database drop failed — inspect the metadata table for cleanup
	}
}(tempDb.ContextualCloser)

// tempDb.ConnPool is ready for DDL execution / introspection
```

--------------------------------

### Example — creating a factory and a temp database

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Example code demonstrating how to create an onInstanceFactory and use it to create a temporary database.

```APIDOC
## Example — creating a factory and a temp database

### Description
Example code demonstrating how to create an onInstanceFactory and use it to create a temporary database.

### Code
```go
tempDbFactory, err := tempdb.NewOnInstanceFactory(ctx,
	func(ctx context.Context, dbName string) (*sql.DB, error) {
		cfg := connConfig.Copy()
		cfg.Database = dbName
		return openDbWithPgxConfig(cfg)
	},
	tempdb.WithRootDatabase(connConfig.Database),
	tempdb.WithDbPrefix("mycompany_tmp_"),
	tempdb.WithLogger(log.SimpleLogger()),
)
if err != nil {
	panic("creating temp db factory")
}
defer tempDbFactory.Close()

tempDb, err := tempDbFactory.Create(ctx)
if err != nil {
	panic("creating temp db")
}
defer func(closer tempdb.ContextualCloser) {
	if err := closer.Close(ctx); err != nil {
		panic(err) // database drop failed — inspect the metadata table for cleanup
	}
}(tempDb.ContextualCloser)

// tempDb.ConnPool is ready for DDL execution / introspection
```

```

--------------------------------

### Example - mixing sources (database to directory)

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Example showing how to combine DBSchemaSource and DirSchemaSource to generate a diff plan.

```APIDOC
## Example - mixing sources (database to directory)

### Description
Shows how to create a schema source from a live database and from a directory of SQL files, then generate a diff plan.

### Code
```go
fromSchema := diff.DBSchemaSource(connPool)              // current DB
toSchema, err := diff.DirSchemaSource([]string{"./schema"}) // desired DDL
if err != nil {
	panic(err)
}

plan, err := diff.Generate(ctx, fromSchema, toSchema,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithIncludeSchemas("public"),
)
if err != nil {
	panic(err)
}
for _, stmt := range plan.Statements {
	// execute each statement, honoring stmt.Timeout / stmt.LockTimeout
}
```

```

--------------------------------

### Bash: version command example with output

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

Prints the version using debug.ReadBuildInfo(). Fails with "build information not available" when build info is missing.

```bash
$ pg-schema-diff version
version=0.14.1
```

--------------------------------

### Install pg-schema-diff via Go toolchain

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Installs the pg-schema-diff CLI using the Go toolchain.

```bash
go install github.com/stripe/pg-schema-diff/cmd/pg-schema-diff@latest
```

--------------------------------

### pg-schema-diff plan example

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

Example command that generates a plan from a Postgres DSN to a directory of SQL files, including only the public schema, and outputs in pretty format.

```bash
pg-schema-diff plan \
  --from-dsn "postgres://postgres:postgres@localhost:5432/postgres" \
  --to-dir ./schema \
  --include-schema public \
  --output-format pretty
```

--------------------------------

### Example — injecting the default logger

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/log.md

Shows how to create a `log.SimpleLogger()` and pass it to `diff.Generate` via `diff.WithLogger`. The logger is used for non-fatal error reporting.

```go
logger := log.SimpleLogger()

plan, err := diff.Generate(ctx, fromSchema, toSchema,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithLogger(logger),
)
if err != nil {
	panic(err)
}
```

--------------------------------

### Example: mixing sources (database → directory)

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Shows how to combine a live database source (current DB) with a directory source (desired DDL) and generate a migration plan. The plan's statements should be executed honoring stmt.Timeout / stmt.LockTimeout.

```go
fromSchema := diff.DBSchemaSource(connPool)              // current DB
toSchema, err := diff.DirSchemaSource([]string{"./schema"}) // desired DDL
if err != nil {
	panic(err)
}

plan, err := diff.Generate(ctx, fromSchema, toSchema,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithIncludeSchemas("public"),
)
if err != nil {
	panic(err)
}
for _, stmt := range plan.Statements {
	// execute each statement, honoring stmt.Timeout / stmt.LockTimeout
}
```

--------------------------------

### Basic plan generation example

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Shows how to create a temp DB factory and generate a plan using DBSchemaSource and DDLSchemaSource. Requires a connConfig and openDbWithPgxConfig function. The plan is generated with WithTempDbFactory and WithDataPackNewTables options.

```go
import (
	"context"
	"github.com/stripe/pg-schema-diff/pkg/diff"
	"github.com/stripe/pg-schema-diff/pkg/tempdb"
)

ctx := context.New()

tempDbFactory, err := tempdb.NewOnInstanceFactory(ctx,
	func(ctx context.Context, dbName string) (*sql.DB, error) {
		copiedConfig := connConfig.Copy()
		copiedConfig.Database = dbName
		return openDbWithPgxConfig(copiedConfig)
	})
if err != nil {
	panic("creating temp db factory")
}
defer tempDbFactory.Close()

plan, err := diff.Generate(ctx,
	diff.DBSchemaSource(connPool),
	diff.DDLSchemaSource([]string{
		"CREATE TABLE foobar (id int PRIMARY KEY, message text NOT NULL);",
	}),
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithDataPackNewTables(),
)
if err != nil {
	panic("generating plan failed")
}
```

--------------------------------

### Example — with exclusions and error handling

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/schema.md

Computes the schema hash with both include and exclude filters. The comment shows an example error message when a schema is both included and excluded, e.g., "getting public schema: schemas [app] are both included and excluded".

```go
hash, err := schema.GetSchemaHash(ctx, connPool,
	schema.WithIncludeSchemas("app", "billing"),
	schema.WithExcludeSchemas("audit_log"),
)
if err != nil {
	// e.g. "getting public schema: schemas [app] are both included and excluded"
	panic(err)
}
```

--------------------------------

### Example - inspecting hazards

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Iterates over plan statements and prints a warning for each hazard of type MigrationHazardTypeDeletesData.

```go
for _, stmt := range plan.Statements {
	for _, hazard := range stmt.Hazards {
		if hazard.Type == diff.MigrationHazardTypeDeletesData {
			fmt.Println("WARNING:", hazard.Message)
		}
	}
}
```

--------------------------------

### Install pg-schema-diff via Homebrew

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Installs the pg-schema-diff CLI using Homebrew on macOS.

```bash
brew install pg-schema-diff
```

--------------------------------

### Example - executing a statement with its timeouts

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Executes each statement in the plan, setting session statement_timeout and lock_timeout before running the SQL. No automatic rollback is performed on error.

```go
for _, stmt := range plan.Statements {
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION statement_timeout = %d", stmt.Timeout.Milliseconds())); err != nil {
		panic(err)
	}
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION lock_timeout = %d", stmt.LockTimeout.Milliseconds())); err != nil {
		panic(err)
	}
	if _, err := conn.ExecContext(ctx, stmt.ToSQL()); err != nil {
		// the database may be in a dirty state — no automatic rollback is performed
		panic(err)
	}
}
```

--------------------------------

### pg-schema-diff apply example

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

Example command that applies a migration from a PostgreSQL DSN to a schema directory, allowing the INDEX_BUILD hazard type.

```bash
pg-schema-diff apply \
  --from-dsn "postgres://postgres:postgres@localhost:5432/postgres" \
  --to-dir ./schema \
  --allow-hazards INDEX_BUILD
```

--------------------------------

### Install pg-schema-diff as a Go library

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Adds pg-schema-diff as a dependency to a Go project.

```bash
go get -u github.com/stripe/pg-schema-diff@latest
```

--------------------------------

### onInstanceFactory.Create method signature

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Creates a temp database named `dbPrefix + uuid` (hyphens replaced with underscores) using `template0`, connects to it, and writes the metadata row. On failure, the partially-created database is dropped and the connection pool closed. The returned `Database.ContextualCloser` closes the pool and drops the database; dropping is refused if the name does not start with `dbPrefix`.

```go
func (o *onInstanceFactory) Create(ctx context.Context) (_ *Database, _retErr error)
```

--------------------------------

### Example — basic use of GetSchemaHash

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/schema.md

Computes the schema hash with an include filter for the "public" schema and compares it against a stored plan's `CurrentSchemaHash` to detect drift. Panics if the hashes differ, otherwise prints the current hash.

```go
hash, err := schema.GetSchemaHash(ctx, connPool, schema.WithIncludeSchemas("public"))
if err != nil {
	panic(err)
}

if hash != plan.CurrentSchemaHash {
	panic("schema drifted; regenerate the plan before applying")
}
fmt.Printf("current schema hash: %s\n", hash)
```

--------------------------------

### Example — serializing statements and checking the schema hash

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Shows how to serialize a statement to JSON and verify the current schema hash matches the plan's hash before applying a stored plan. Uses schema.GetSchemaHash with WithIncludeSchemas("public").

```go
// Serialize one statement (e.g. to ship to a reviewer):
jsonBytes, err := stmt.MarshalJSON()
if err != nil {
	panic(err)
}
fmt.Println(string(jsonBytes)) // {"ddl":..., "timeout_ms":..., "lock_timeout_ms":..., "hazards":[...]}

// Later, before applying a stored plan from another process, verify schema A is unchanged:
currentHash, err := schema.GetSchemaHash(ctx, conn, schema.WithIncludeSchemas("public"))
if err != nil {
	panic(err)
}
if currentHash != plan.CurrentSchemaHash {
	panic("schema has changed since the plan was generated — regenerate the plan")
}
```

--------------------------------

### Bash: dump command example

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

Dumps the schema of a PostgreSQL database to a file. The output is raw DDL statements joined by ";\n\n" with no metadata.

```bash
mkdir -p schema && pg-schema-diff dump --dsn "postgres://postgres:postgres@localhost:5432/postgres" > schema/schema.sql
```

--------------------------------

### Example — post-processing a plan (timeout overrides + insertion)

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Shows how to apply timeout modifiers and insert a statement into a plan. The inserted statement uses a pg_advisory_lock and includes Timeout, LockTimeout, Hazards, and SkipValidation fields.

```go
plan = plan.ApplyStatementTimeoutModifier(regexp.Compile("CREATE INDEX"), 10*time.Minute)
plan = plan.ApplyLockTimeoutModifier(regexp.Compile("DROP TABLE"), 60*time.Second)

var plan2 diff.Plan
plan2, err = plan.InsertStatement(0, diff.Statement{
	DDL:         "SELECT pg_advisory_lock(42)",
	Timeout:     5*time.Second,
	LockTimeout: 5*time.Second,
	Hazards:     nil,
	SkipValidation: false,
})
if err != nil {
	panic(err) // index out of range
}
```

--------------------------------

### Example - skipping validation-sensitive statements

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Prints the DDL of statements that have SkipValidation set to true, indicating they depend on cluster-level objects like roles.

```go
for _, stmt := range plan.Statements {
	if stmt.SkipValidation {
		fmt.Println("statement depends on cluster-level objects (e.g. roles):", stmt.DDL)
	}
}
```

--------------------------------

### Example — implementing a custom Logger

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/log.md

Shows a custom `Logger` implementation that collects error messages. The `collectingLogger` struct implements `Errorf` and `Warnf` by appending formatted messages to a slice. It is passed to `diff.Generate` via `diff.WithLogger`.

```go
type collectingLogger struct {
	errors []string
}

func (l *collectingLogger) Errorf(msg string, args ...any) {
	l.errors = append(l.errors, fmt.Sprintf(msg, args...))
}

func (l *collectingLogger) Warnf(msg string, args ...any) {
	l.errors = append(l.errors, fmt.Sprintf(msg, args...))
}

plan, err := diff.Generate(ctx, fromSchema, toSchema,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithLogger(&collectingLogger{}),
)
```

--------------------------------

### Acceptance Test Case Structure

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Example structure for an acceptance test case, showing fields for name, old and new schema DDL, expected hazard types, expected plan DDL, and optional flags.

```go
acceptanceTestCase{
    name:                 "test name",
    oldSchemaDDL:        []string{"CREATE TABLE ..."},
    newSchemaDDL:        []string{"CREATE TABLE ... (modified)"},
    expectedHazardTypes: []diff.MigrationHazardType{...},
    expectedPlanDDL:     []string{"ALTER TABLE ..."},  // optional: assert exact DDL
    expectEmptyPlan:     false,                         // optional: assert no changes
    planOpts:            []diff.PlanOpt{...},           // optional: custom plan options
}
```

--------------------------------

### CLI commands for plan and apply

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Shows how to generate migration plans from a database to DDL files, between two databases, apply a migration with hazard approval, and specify output format.

```bash
# Generate migration plan (from database to DDL files)
pg-schema-diff plan \
    --from-dsn "postgres://user:pass@localhost:5432/mydb" \
    --to-dir ./schema

# Generate plan between two databases
pg-schema-diff plan \
    --from-dsn "postgres://..." \
    --to-dsn "postgres://..."

# Apply migration (requires hazard approval)
pg-schema-diff apply \
    --from-dsn "postgres://user:pass@localhost:5432/mydb" \
    --to-dir ./schema \
    --allow-hazards INDEX_BUILD,ACQUIRES_ACCESS_EXCLUSIVE_LOCK

# Output formats: sql (default), json, pretty
pg-schema-diff plan --from-dsn "..." --to-dir ./schema --output-format json
```

--------------------------------

### Create schema directory and initial SQL files

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Creates a schema directory and generates initial SQL files for the foobar and bar tables.

```bash
mkdir schema
echo "CREATE TABLE foobar (id int);" > schema/foobar.sql
echo "CREATE TABLE bar (id varchar(255), message TEXT NOT NULL);" > schema/bar.sql
```

--------------------------------

### onInstanceFactoryOptions struct with defaults

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Shows the default values for each option, including the default database prefix, metadata schema/table, logger, root database, drop timeout, and random reader.

```go
type onInstanceFactoryOptions struct {
	dbPrefix       string   // DefaultOnInstanceDbPrefix = "pgschemadiff_tmp_"
	metadataSchema string   // DefaultOnInstanceMetadataSchema = "pgschemadiff_tmp_metadata"
	metadataTable  string   // DefaultOnInstanceMetadataTable = "metadata"
	logger         log.Logger // log.SimpleLogger()
	rootDatabase   string   // "postgres"
	dropTimeout    time.Duration // DefaultStatementTimeout = 3s
	randReader     io.Reader  // rand.Reader
}
```

--------------------------------

### Generate and apply schema diff plan with pg-schema-diff

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Shows how to create a temp database factory, define schema sources, generate a migration plan, and apply its statements with session timeouts. Requires a database connection and schema directory.

```go
import (
    "github.com/stripe/pg-schema-diff/pkg/diff"
    "github.com/stripe/pg-schema-diff/pkg/tempdb"
)

// Create temp database factory for plan validation
tempDbFactory, _ := tempdb.NewOnInstanceFactory(ctx, func(ctx context.Context, dbName string) (*sql.DB, error) {
    return sql.Open("postgres", fmt.Sprintf(".../%s", dbName))
})

// Define schema sources
currentSchema := diff.DBSchemaSource(db)  // db is *sql.DB or sqldb.Queryable
targetSchema, _ := diff.DirSchemaSource([]string{"./schema"})  // returns (SchemaSource, error)

// Generate plan
plan, _ := diff.Generate(ctx, currentSchema, targetSchema,
    diff.WithTempDbFactory(tempDbFactory),
)

// Apply statements (set timeouts before each statement)
for _, stmt := range plan.Statements {
    conn.ExecContext(ctx, fmt.Sprintf("SET SESSION statement_timeout = %d", stmt.Timeout.Milliseconds()))
    conn.ExecContext(ctx, fmt.Sprintf("SET SESSION lock_timeout = %d", stmt.LockTimeout.Milliseconds()))
    conn.ExecContext(ctx, stmt.ToSQL())
}
```

--------------------------------

### Plan generation with error handling and options

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Shows how to use DirSchemaSource to load a target schema from a directory, and how to pass multiple options to diff.Generate, including WithIncludeSchemas, WithExcludeSchemas, WithDoNotValidatePlan, and WithNoConcurrentIndexOps. Error handling checks for errTempDbFactoryRequired.

```go
target, err := diff.DirSchemaSource([]string{"./schema"})
if err != nil {
	// Bad directory / unreadable .sql files surface here as (nil, nil, err) via the factory
	panic(err)
}

plan, err := diff.Generate(ctx,
	diff.DBSchemaSource(connPool),
	target,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithIncludeSchemas("public"),
	diff.WithExcludeSchemas("audit"),
	diff.WithDoNotValidatePlan(),       // skip temp-db replay
	diff.WithNoConcurrentIndexOps(),    // emit plain CREATE/DROP INDEX
)
if err != nil {
	switch {
	case errors.Is(err, errTempDbFactoryRequired): // only reachable when validation enabled
		panic("temp db factory missing for validation")
	default:
		panic(err)
	}
}
```

--------------------------------

### Plan.ApplyLockTimeoutModifier

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Returns a new plan where every statement whose DDL matches the given regex gets its LockTimeout set to the specified duration. The receiver is mutated and returned.

```APIDOC
## Plan.ApplyLockTimeoutModifier

### Description
Returns a new plan where every statement whose DDL matches the given regex gets its LockTimeout set to the specified duration. The receiver is mutated and returned.

### Method
ApplyLockTimeoutModifier

### Signature
func (p Plan) ApplyLockTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan

### Parameters
- **regex** (*regexp.Regexp) - Required - Regular expression to match against statement DDL.
- **timeout** (time.Duration) - Required - Lock timeout duration to set for matching statements.

### Returns
- **Plan** - The mutated plan with updated lock timeouts.
```

--------------------------------

### Plan.ApplyStatementTimeoutModifier

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Returns a new plan where every statement whose DDL matches the given regex gets its Timeout set to the specified duration. The receiver is mutated and returned.

```APIDOC
## Plan.ApplyStatementTimeoutModifier

### Description
Returns a new plan where every statement whose DDL matches the given regex gets its Timeout set to the specified duration. The receiver is mutated and returned.

### Method
ApplyStatementTimeoutModifier

### Signature
func (p Plan) ApplyStatementTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan

### Parameters
- **regex** (*regexp.Regexp) - Required - Regular expression to match against statement DDL.
- **timeout** (time.Duration) - Required - Timeout duration to set for matching statements.

### Returns
- **Plan** - The mutated plan with updated timeouts.
```

--------------------------------

### Generate migration plan with diff.Generate

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Creates a temporary database factory using tempdb.NewOnInstanceFactory, then generates a migration plan by comparing a database schema source and a DDL schema source. Uses options WithTempDbFactory and WithDataPackNewTables. Panics if factory creation or plan generation fails.

```go
// The tempDbFactory is used in plan generation to extract the new schema and validate the plan
tempDbFactory, err := tempdb.NewOnInstanceFactory(ctx, func(ctx context.Context, dbName string) (*sql.DB, error) {
	copiedConfig := connConfig.Copy()
	copiedConfig.Database = dbName
	return openDbWithPgxConfig(copiedConfig)
})
if err != nil {
	panic("Generating the TempDbFactory failed")
}
defer tempDbFactory.Close()
// Generate the migration plan
plan, err := diff.Generate(ctx, diff.DBSchemaSource(connPool), diff.DDLSchemaSource(ddl),
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithDataPackNewTables(),
)
if err != nil {
	panic("Generating the plan failed")
}	
```

--------------------------------

### Plan.ApplyStatementTimeoutModifier method signature

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/plan.md

Returns a new plan where every statement whose DDL matches the regex gets Timeout set to the given timeout. The receiver is mutated and returned.

```go
func (p Plan) ApplyStatementTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan
```

--------------------------------

### Wrapping a pool for a schema source

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/sqldb.md

Shows how to open a *sql.DB pool using pgx stdlib and pass it directly to diff.DBSchemaSource. The pool is set to a max of 5 open connections.

```go
import (
	"github.com/jackc/pgx/v4/stdlib"
	"github.com/stripe/pg-schema-diff/pkg/diff"
)

// *sql.DB implements sqldb.Queryable, so it can be passed directly:
connPool := stdlib.OpenDB(connConfig)
connPool.SetMaxOpenConns(5)

fromSchema := diff.DBSchemaSource(connPool)
```

--------------------------------

### SequenceOwner and Sequence structs

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/types.md

SequenceOwner links a sequence to a table column. Sequence holds sequence properties such as type, start value, increment, max/min values, cache size, and cycle flag.

```go
type SequenceOwner struct {
	TableName  SchemaQualifiedName
	ColumnName string
}
type Sequence struct {
	SchemaQualifiedName
	Owner      *SequenceOwner
	Type       string
	StartValue int64
	Increment  int64
	MaxValue   int64
	MinValue   int64
	CacheSize  int64
	Cycle      bool
}
```

--------------------------------

### Go: dump command implementation using diff.Generate

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

Shows how the dump command builds a plan from an empty DDL schema to the live database schema. Always applies diff.WithDoNotValidatePlan() and diff.WithNoConcurrentIndexOps().

```go
plan, err := diff.Generate(ctx, diff.DDLSchemaSource([]string{}), diff.DBSchemaSource(connPool),
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithIncludeSchemas(params.includeSchemas...),
	diff.WithExcludeSchemas(params.excludeSchemas...),
	diff.WithDoNotValidatePlan(),
	diff.WithNoConcurrentIndexOps(),
)
```

--------------------------------

### onInstanceFactory.Create

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Creates a temporary database with a unique name, connects to it, and writes metadata. On failure, cleans up partially-created resources.

```APIDOC
## onInstanceFactory.Create

### Description
Creates a temp database named `dbPrefix + uuid` (hyphens replaced with underscores) using `template0`, connects to it, and writes the metadata row. On failure, the partially-created database is dropped and the connection pool closed. The returned `Database.ContextualCloser` closes the pool and drops the database; dropping is refused if the name does not start with `dbPrefix`.

### Method
Create

### Signature
```go
func (o *onInstanceFactory) Create(ctx context.Context) (_ *Database, _retErr error)
```

### Parameters
- **ctx** (context.Context) - Required - The context for the operation.

### Returns
- **\*Database** - The created temporary database.
- **error** - An error if creation fails.

### Errors
- `"creating uuid: %w"`
- `"openConnectionWithDefaults: %w"`
- `"creating temporary database: %w"`
- `"connecting to temporary database: %w"`
- `"assertConnPoolIsOnExpectedDatabase: %w"`
- `"creating metadata in temporary database: %w"`
- `"drop non-temporary database: %s"` - if the database name does not start with `dbPrefix`.

```

--------------------------------

### Development Commands

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Common commands for running tests, linting, regenerating sqlc code, and tidying dependencies. Requires Docker or local Postgres for tests.

```bash
# Run all tests (requires Docker or local Postgres)
go test -v -race ./... -timeout 30m

# Run specific acceptance tests
go test -v ./internal/migration_acceptance_tests/... -run TestIndexAcceptance

# Lint
make lint

# Fix lint issues
make lint_fix

# Regenerate sqlc code
make sqlc

# Tidy dependencies
make go_mod_tidy
```

--------------------------------

### GetSchemaHash function signature

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/schema.md

Signature of the `GetSchemaHash` function. It computes a stable hash of the schema reachable through `queryable` with the given options. Returns a hex string on success or an error wrapped as "getting public schema: %w" or "hashing schema: %w".

```go
func GetSchemaHash(ctx context.Context, queryable sqldb.Queryable, opts ...GetSchemaOpt) (string, error)
```

--------------------------------

### DirSchemaSource constructor

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Returns a SchemaSource that reads all .sql files under each directory (recursively, lexical order) and executes them in a temporary database. Requires WithTempDbFactory. Errors: "walking path %q: %w", "reading file %q: %w".

```go
func DirSchemaSource(dirs []string) (SchemaSource, error)
```

--------------------------------

### main() error handling

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/cli.md

The main function executes the root command and exits with code 1 on any error.

```go
func main() {
	if err := buildRootCmd().Execute(); err != nil {
		os.Exit(1)
	}
}
```

--------------------------------

### WithGetSchemaOpts

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Passthrough for arbitrary schema-fetch options from pkg/schema.

```APIDOC
## WithGetSchemaOpts

### Description
Passthrough for arbitrary schema-fetch options from `pkg/schema` (see [schema.md](schema.md)).

### Function Signature
```go
func WithGetSchemaOpts(getSchemaOpts ...externalschema.GetSchemaOpt) PlanOpt
```

### Parameters
- **getSchemaOpts** (externalschema.GetSchemaOpt) - Required - The schema-fetch options to pass through.

### Source
`pkg/diff/plan_generator.go:93`
```

--------------------------------

### Running Tests with Docker

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Commands to build and run the test Docker image with a specified PostgreSQL major version.

```bash
docker build -f build/Dockerfile.test --build-arg PG_MAJOR=15 -t pg-schema-diff-test .
docker run pg-schema-diff-test
```

--------------------------------

### pkg/sqldb, pkg/log, pkg/schema types: Queryable, Logger, simpleLogger, GetSchemaOpt

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/types.md

Queryable interface for SQL operations, Logger interface for error and warning logging, simpleLogger empty struct, and GetSchemaOpt alias for schema options.

```go
type Queryable interface {
	ExecContext(context.Context, string, ...interface{}) (sql.Result, error)
	PrepareContext(context.Context, string) (*sql.Stmt, error)
	QueryContext(context.Context, string, ...interface{}) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...interface{}) *sql.Row
}
type Logger interface {
	Errorf(msg string, args ...any)
	Warnf(msg string, args ...any)
}
type simpleLogger struct{}
type GetSchemaOpt = internalschema.GetSchemaOpt
```

--------------------------------

### DBSchemaSource constructor

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Returns a SchemaSource backed by a live database connection. queryable must implement sqldb.Queryable; the doc comment recommends a *sql.DB with a max number of connections set. Schema extraction is concurrent when the queryable is a *sql.DB (50-way goroutine limiter), sequential otherwise.

```go
func DBSchemaSource(queryable sqldb.Queryable) SchemaSource
```

--------------------------------

### DDLSchemaSource constructor

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Returns a SchemaSource that runs the given DDL statements in a temporary database (requires WithTempDbFactory). Executing DDL fails with "running DDL%s: %w" (the debug suffix includes " (from <file>)" when the statement came from a file).

```go
func DDLSchemaSource(stmts []string) SchemaSource
```

--------------------------------

### Default onInstanceFactoryOptions struct literal

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/configuration.md

Shows the default values for the OnInstanceFactory options. The dbPrefix must be a simple Postgres identifier matching ^[a-z_][a-z0-9_$]*$.

```go
options := onInstanceFactoryOptions{
	dbPrefix:       DefaultOnInstanceDbPrefix,       // "pgschemadiff_tmp_"
	metadataSchema: DefaultOnInstanceMetadataSchema, // "pgschemadiff_tmp_metadata"
	metadataTable:  DefaultOnInstanceMetadataTable,  // "metadata"
	dropTimeout:    DefaultStatementTimeout,         // 3 * time.Second
	rootDatabase:   "postgres",
	logger:         log.SimpleLogger(),
	randReader:     rand.Reader,
}
```

--------------------------------

### Implementing a custom Queryable

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/sqldb.md

Shows a logging wrapper around sqldb.Queryable that logs each ExecContext call. The wrapper is then used with diff.DBSchemaSource to diff against a live database.

```go
type loggingQueryable struct {
	inner sqldb.Queryable
}

func (l *loggingQueryable) ExecContext(ctx context.Context, sql string, args ...interface{}) (sql.Result, error) {
	fmt.Println("exec:", sql)
	return l.inner.ExecContext(ctx, sql, args...)
}

func (l *loggingQueryable) PrepareContext(ctx context.Context, sql string) (*sql.Stmt, error) {
	return l.inner.PrepareContext(ctx, sql)
}

func (l *loggingQueryable) QueryContext(ctx context.Context, sql string, args ...interface{}) (*sql.Rows, error) {
	return l.inner.QueryContext(ctx, sql, args...)
}

func (l *loggingQueryable) QueryRowContext(ctx context.Context, sql string, args ...interface{}) *sql.Row {
	return l.inner.QueryRowContext(ctx, sql, args...)
}

// Diff against a live database through the wrapper:
source := diff.DBSchemaSource(&loggingQueryable{inner: connPool})
```

--------------------------------

### PlanOpt and planOptions struct

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/types.md

Defines the PlanOpt function type and the planOptions struct that holds configuration for plan generation. The struct includes fields for temp database factory, data packing for new tables, column order change handling, logger, validation, schema options, random reader, and concurrent index operations.

```go
type PlanOpt func(opts *planOptions)
type planOptions struct {
	tempDbFactory           tempdb.Factory
	dataPackNewTables       bool
	ignoreChangesToColOrder bool
	logger                  log.Logger
	validatePlan            bool
	getSchemaOpts           []schema.GetSchemaOpt
	randReader              io.Reader
	noConcurrentIndexOps    bool
}
```

--------------------------------

### Create tempdb factory with root database check and error handling

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Creates a new tempdb factory on an existing instance, specifying a root database. The error is checked and panics if the connection pool is not on the expected database, as shown in the error message.

```go
factory, err := tempdb.NewOnInstanceFactory(ctx, createConnPoolForDb,
	tempdb.WithRootDatabase("myapp"),
)
if err != nil {
	// This fails if createConnPoolForDb("myapp") connects somewhere else, e.g.:
	// "assertConnPoolIsOnExpectedDatabase: connection pool is on database X, expected myapp"
	panic(err)
}
```

--------------------------------

### Build test runner image with PostgreSQL 15

Source: https://github.com/stripe/pg-schema-diff/blob/main/CONTRIBUTING.md

Builds the Docker image for running tests with the postgresql15 image.

```bash
docker build -t pg-schema-diff-test-runner -f ./build/Dockerfile.test --build-arg POSTGRES_PACKAGE=postgresql15 .
```

--------------------------------

### Apply migration plan statements

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Iterates over each statement in the plan, setting session-level statement_timeout and lock_timeout based on the statement's Timeout and LockTimeout values, then executes the statement's SQL. Panics with a dirty-state warning if execution fails.

```go
for _, stmt := range plan.Statements {
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION statement_timeout = %d", stmt.Timeout.Milliseconds())); err != nil {
		panic(fmt.Sprintf("setting statement timeout: %s", err))
	}
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION lock_timeout = %d", stmt.LockTimeout.Milliseconds())); err != nil {
		panic(fmt.Sprintf("setting lock timeout: %s", err))
	}
	if _, err := conn.ExecContext(ctx, stmt.ToSQL()); err != nil {
		panic(fmt.Sprintf("executing migration statement. the database maybe be in a dirty state: %s: %s", stmt, err))
	}
}
```

--------------------------------

### diff.Generate Plan Options (PlanOpt)

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/configuration.md

Configuration options for the diff.Generate plan. Each option is set via a corresponding builder method (PlanOpt). Defaults are applied when no option is provided.

```APIDOC
## diff.Generate Plan Options (PlanOpt)

### Description
Configuration options for the diff.Generate plan. Each option is set via a corresponding builder method (PlanOpt). Defaults are applied when no option is provided.

### Default Plan Options
```go
planOptions := &planOptions{
    validatePlan:            true,
    ignoreChangesToColOrder: true,
    logger:                  log.SimpleLogger(),
    randReader:              rand.Reader,
}
```

### Options

#### `tempDbFactory`
- **Type**: `tempdb.Factory`
- **Required**: no
- **Default**: `nil`
- **Set by**: `WithTempDbFactory(factory tempdb.Factory)`

#### `dataPackNewTables`
- **Type**: `bool`
- **Required**: no
- **Default**: `false`
- **Set by**: `WithDataPackNewTables()`

#### `ignoreChangesToColOrder`
- **Type**: `bool`
- **Required**: no
- **Default**: `true`
- **Set by**: reversed by `WithRespectColumnOrder()`

#### `logger`
- **Type**: `log.Logger`
- **Required**: no
- **Default**: `log.SimpleLogger()`
- **Set by**: `WithLogger(logger log.Logger)`

#### `validatePlan`
- **Type**: `bool`
- **Required**: no
- **Default**: `true`
- **Set by**: `WithDoNotValidatePlan()`

#### `getSchemaOpts`
- **Type**: `[]schema.GetSchemaOpt`
- **Required**: no
- **Default**: `[]`
- **Set by**: `WithIncludeSchemas(...string)`, `WithExcludeSchemas(...string)`, `WithGetSchemaOpts(...externalschema.GetSchemaOpt)`

#### `randReader`
- **Type**: `io.Reader`
- **Required**: no
- **Default**: `rand.Reader`
- **Set by**: `WithRandReader(randReader io.Reader)`

#### `noConcurrentIndexOps`
- **Type**: `bool`
- **Required**: no
- **Default**: `false`
- **Set by**: `WithNoConcurrentIndexOps()`

### Constraints
- `dataPackNewTables = true` with `ignoreChangesToColOrder = false` fails plan generation with `"cannot data pack new tables without also ignoring changes to column order"`.
```

--------------------------------

### pkg/tempdb types: ContextualCloser, Database, Factory, OnInstanceFactoryOpt, CreateConnPoolForDbFn

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/types.md

Core types for temporary database management. Database embeds ContextualCloser and holds a connection pool. Factory creates Database instances and implements io.Closer. OnInstanceFactoryOpt configures instance factory options. CreateConnPoolForDbFn creates a connection pool for a given database name.

```go
type ContextualCloser interface { Close(context.Context) error }
type fnContextualCloser func(context.Context) error
type Database struct {
	ConnPool *sql.DB
	ExcludeMetadataOptions []schema.GetSchemaOpt
	ContextualCloser
}
type Factory interface {
	Create(ctx context.Context) (*Database, error)
	io.Closer
}
type OnInstanceFactoryOpt func(*onInstanceFactoryOptions)
type onInstanceFactoryOptions struct {
	dbPrefix       string
	metadataSchema string
	metadataTable  string
	logger         log.Logger
	rootDatabase   string
	dropTimeout    time.Duration
	randReader     io.Reader
}
type CreateConnPoolForDbFn func(ctx context.Context, dbName string) (*sql.DB, error)
```

--------------------------------

### WithDbPrefix

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/tempdb.md

Sets the prefix for temporary database names.

```APIDOC
## WithDbPrefix

### Description
Sets the prefix for temporary database names.

### Signature
`func WithDbPrefix(prefix string) OnInstanceFactoryOpt`

### Parameters
- **prefix** (string) - Required - The prefix to use for temporary database names.

### Returns
- **OnInstanceFactoryOpt** - The option to pass to the factory constructor.
```

--------------------------------

### DirSchemaSource

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Creates a SchemaSource that reads all .sql files under each directory (recursively, lexical order) and executes them in a temporary database. Requires WithTempDbFactory.

```APIDOC
## DirSchemaSource

### Description
Returns a SchemaSource that reads all `.sql` files under each directory (recursively, lexical order) and executes them in a temporary database. Requires `WithTempDbFactory`.

### Signature
```go
func DirSchemaSource(dirs []string) (SchemaSource, error)
```

### Parameters
- **dirs** ([]string) - Required - List of directories to read `.sql` files from.

### Returns
- **SchemaSource** - The schema source.
- **error** - Error if walking or reading files fails. Errors: `"walking path %q: %w"`, `"reading file %q: %w"`.

```

--------------------------------

### schemaSourcePlanDeps struct

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Defines the dependencies passed to GetSchema: a temp-db factory, logger, and schema-fetch options.

```go
type schemaSourcePlanDeps struct {
	tempDBFactory tempdb.Factory
	logger        log.Logger
	getSchemaOpts []schema.GetSchemaOpt
}
```

--------------------------------

### Build test runner image with PostgreSQL 14

Source: https://github.com/stripe/pg-schema-diff/blob/main/CONTRIBUTING.md

Builds the Docker image for running tests with the postgresql14 image. The build-arg can be omitted because postgresql14 is the default.

```bash
docker build -t pg-schema-diff-test-runner -f ./build/Dockerfile.test --build-arg POSTGRES_PACKAGE=postgresql14 .
```

--------------------------------

### Catching custom errors with errors.Is

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/errors.md

Shows how to handle errors from diff.Generate by checking for errTempDbFactoryRequired and ErrNotImplemented using errors.Is, with a default panic for unexpected errors.

```go
plan, err := diff.Generate(ctx, from, to, diff.WithTempDbFactory(factory))
if err != nil {
	switch {
	case errors.Is(err, errTempDbFactoryRequired):
		// a DDL schema source was used without a temp-db factory
	case errors.Is(err, ErrNotImplemented):
		// the diff contains an unsupported migration
	default:
		panic(err)
	}
}
```

--------------------------------

### Apply schema to fresh database

Source: https://github.com/stripe/pg-schema-diff/blob/main/README.md

Applies the schema from the schema directory to a fresh database. The connection string spec is linked; setting PGPASSWORD is recommended to override any password in the connection string.

```bash
pg-schema-diff apply --from-dsn "postgres://postgres:postgres@localhost:5432/postgres" --to-dir schema
```

--------------------------------

### internal/pgengine types: ConnectionOption, ConnectionOptions, Engine

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/types.md

PostgreSQL engine configuration types. ConnectionOption constants for host, user, database, and port. ConnectionOptions map. Engine struct holds process and connection details.

```go
type ConnectionOption string
const (
	ConnectionOptionHost     ConnectionOption = "host"
	ConnectionOptionUser     ConnectionOption = "user"
	ConnectionOptionDatabase ConnectionOption = "dbname"
	ConnectionOptionPort     ConnectionOption = "port"
)
type ConnectionOptions map[ConnectionOption]string
type Engine struct {
	superuser string
	process  *os.Process
	dbPath   string
	sockPath string
}
```

--------------------------------

### Go Plan and Statement structs

Source: https://github.com/stripe/pg-schema-diff/blob/main/CLAUDE.md

Defines the Plan and Statement types used to represent a migration plan. Plan holds a list of statements and a schema hash for validation; Statement includes DDL, timeouts, and hazards.

```go
type Plan struct {
    Statements        []Statement
    CurrentSchemaHash string  // For validation before applying
}

type Statement struct {
    DDL         string           // SQL to execute
    Timeout     time.Duration    // statement_timeout
    LockTimeout time.Duration    // lock_timeout
    Hazards     []MigrationHazard
}
```

--------------------------------

### SimpleLogger()

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/log.md

Returns a bare-bones Logger implementation intended as a sensible default and for testing. It formats messages with fmt.Sprintf and emits via log.Printf with prefixes [ERROR] and [WARNING].

```APIDOC
## SimpleLogger()

### Description
Returns a bare-bones Logger implementation intended as a sensible default and for testing. The methods format the message with fmt.Sprintf(msg, args...) and emit via log.Printf (stdlib log package), prefixed with [ERROR] for Errorf and [WARNING] for Warnf.

### Method
- **SimpleLogger() Logger** - Returns a Logger implementation.

### Output
| Method | Output |
|---|---|
| Errorf(msg, args...) | `[ERROR] <formatted>` |
| Warnf(msg, args...) | `[WARNING] <formatted>` |

### Example
```go
logger := log.SimpleLogger()

plan, err := diff.Generate(ctx, fromSchema, toSchema,
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithLogger(logger),
)
if err != nil {
	panic(err)
}
```
```

--------------------------------

### Fetch schema with include/exclude schemas and iterate tables

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/internal-schema.md

Use schema.GetSchema with options to include and exclude schemas. The returned schema's Tables can be iterated to print table names and column counts. Finally, Normalize() is called on the schema.

```go
import (
	"github.com/stripe/pg-schema-diff/internal/schema"
)

sch, err := schema.GetSchema(ctx, connPool,
	schema.WithIncludeSchemas("public"),
	schema.WithExcludeSchemas("audit"),
)
if err != nil {
	panic(err)
}

for _, t := range sch.Tables {
	fmt.Printf("table %s has %d columns\n", t.GetFQEscapedName(), len(t.Columns))
}
normalized := sch.Normalize()
```

--------------------------------

### diff.Generate

Source: https://github.com/stripe/pg-schema-diff/blob/main/_autodocs/api-reference/diff.md

Generates a migration plan to migrate the database from fromSchema to targetSchema. It accepts context, schema sources, and optional plan options, returning a Plan or an error.

```APIDOC
## diff.Generate

### Description
Generates a migration plan to migrate the database from `fromSchema` to `targetSchema`. It fetches both schemas, diffs them, generates migration statements, hashes the current schema, and optionally validates the plan by replaying it on a temporary database.

### Method
Generate

### Endpoint
`func Generate(ctx context.Context, fromSchema SchemaSource, targetSchema SchemaSource, opts ...PlanOpt) (Plan, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `ctx` (context.Context) - Required - Cancellation/error context propagated to the database pool calls
- `fromSchema` (SchemaSource) - Required - Source of the current schema (the schema to migrate away from)
- `targetSchema` (SchemaSource) - Required - Source of the desired schema; pass a `DDLSchemaSource` when the target is encoded as DDL
- `opts` (...PlanOpt) - Optional - Options configuring plan generation (see below)

### Request Example
```go
plan, err := diff.Generate(ctx,
	diff.DBSchemaSource(connPool),
	diff.DDLSchemaSource([]string{
		"CREATE TABLE foobar (id int PRIMARY KEY, message text NOT NULL);",
	}),
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithDataPackNewTables(),
)
```

### Response
#### Success Response (200)
- `Plan` - A `Plan` whose `Statements` migrate schema A to schema B and whose `CurrentSchemaHash` is the hash of the current schema.

#### Response Example
```go
plan, err := diff.Generate(ctx, ...)
```

### Error Handling
- Errors are wrapped with contextual prefixes: `"getting current schema: %w"`, `"getting new schema: %w"`, `"generating plan statements: %w"`, `"generating current schema hash: %w"`, `"validating migration plan: %w"`.
- If validation is enabled (default) but no `tempDbFactory` is provided, returns an error wrapping `errTempDbFactoryRequired`.

```
Tokens:
Raw