Documentation
¶
Overview ¶
Package sqlmigrate is the shared forward-only SQL migration runner for Harbor's SQLite and Postgres persistence drivers. It is the single home of the migration contract that was previously copy-pasted per driver: the `NNNN_<slug>.sql` filename rule, the partial-apply precheck against `schema_migrations`, the per-migration transaction, and (Postgres) the FNV-64a advisory-key derivation that serialises concurrent boots.
Forward-only contract (unchanged from the per-driver runners): migrations are numbered monotonically; editing a merged migration is forbidden; future schema changes land as new files. A bad filename in the embed set is a build-time bug and is surfaced loudly, never skipped.
SQLite and Postgres keep deliberately distinct runners — they differ in the migrations-table DDL (`TIMESTAMP`/`CURRENT_TIMESTAMP` vs `TIMESTAMPTZ`/`NOW()`), in who records the applied version (the SQLite runner inserts it; the Postgres migration body inserts its own row), and in concurrency control (Postgres apply mode takes a session `pg_advisory_lock`, while Postgres verify mode and SQLite need none). Each driver passes its own embedded `migrations/` FS and error prefix so wrapped errors read exactly as before.
Index ¶
- func RunPostgres(ctx context.Context, db *sql.DB, migrationsFS fs.FS, ...) error
- func RunPostgresNamed(ctx context.Context, db *sql.DB, migrationsFS fs.FS, ...) error
- func RunSQLite(ctx context.Context, db *sql.DB, migrationsFS fs.FS, errPrefix string) error
- func ValidateDirectMigrationDSN(dsn string) error
- type Mode
- type PostgresMigrationSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunPostgres ¶
func RunPostgres(ctx context.Context, db *sql.DB, migrationsFS fs.FS, errPrefix, advisoryLockName string, mode Mode) error
RunPostgres applies or verifies the forward-only migrations in migrationsFS. Empty mode resolves to ModeApply, which wraps application in a session-level `pg_advisory_lock` derived from advisoryLockName so concurrent New() calls across replicas don't race. ModeVerify performs only a read-only query of the existing `schema_migrations` ledger: it creates no table, begins no transaction, takes no advisory lock, and fails when an embedded migration is not recorded. errPrefix is the driver's error-wrap prefix (e.g. "postgres", "memory/postgres"). Migration bodies record their own schema_migrations row.
func RunPostgresNamed ¶ added in v1.29.1
func RunPostgresNamed(ctx context.Context, db *sql.DB, migrationsFS fs.FS, spec PostgresMigrationSpec, errPrefix, advisoryLockName, dsn string, mode Mode) error
RunPostgresNamed applies or verifies a namespaced, checksummed Postgres migration ledger. It is the v1.29.1 runner used by all six Harbor-owned Postgres stores. Historical migration files remain immutable: the runner computes their SHA-256 and records it in harbor_schema_migrations.
Apply mode requires direct PostgreSQL connectivity (normally port 5432) because it takes a session advisory lock. Verify mode is read-only and is compatible with transaction-pooled PgBouncer traffic on port 6432.
func RunSQLite ¶
RunSQLite applies any forward-only migrations in migrationsFS whose version is not already present in `schema_migrations` to db. errPrefix is the driver's error-wrap prefix (e.g. "state/sqlite"). Each migration runs inside a single transaction; the runner records the applied version with `INSERT OR IGNORE` so a partially-applied DB (DDL applied but the trailing INSERT lost) is still recoverable.
func ValidateDirectMigrationDSN ¶ added in v1.29.1
ValidateDirectMigrationDSN refuses the well-known transaction-pooled endpoint. PgBouncer transaction mode cannot safely hold a session advisory lock across migration statements; ordinary verify traffic remains safe.
Types ¶
type Mode ¶ added in v1.28.7
type Mode string
Mode controls how a Postgres-backed store treats its embedded migrations when the store opens. The zero value resolves to ModeApply so existing configurations retain their migration-at-boot behavior.
const ( // ModeApply takes the subsystem's session advisory lock and applies every // embedded migration that is not yet recorded in schema_migrations. ModeApply Mode = "apply" // ModeVerify performs a read-only schema_migrations ledger check. It takes // no session advisory lock and executes no DDL, transaction, or write. ModeVerify Mode = "verify" )
type PostgresMigrationSpec ¶ added in v1.29.1
type PostgresMigrationSpec struct {
Subsystem string
RequiredTables []string
RequiredColumns map[string][]string
}
PostgresMigrationSpec describes the identity and required schema of one Harbor-owned Postgres projection. The subsystem is part of the migration identity; version numbers are never interpreted globally.
Source Files