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 ¶
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 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.
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" )
Source Files