Documentation
¶
Overview ¶
Package migrate applies paired .up.sql and .down.sql files using database/sql. It intentionally does not choose a SQL driver or hide the underlying *sql.DB.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrPendingMigration means that integrity verification found an unapplied // migration after verifying all recorded migrations. It does not apply it. ErrPendingMigration = errors.New("migrate: pending migration") // ErrMigrationDrift means a recorded migration no longer matches its source, // or a row has lost its checksum despite an integrity-enabled ledger. Removal // of an entire source pair, changed names, and changed up-script checksums are // drift. An incomplete or inconsistently named pair is invalid source instead. ErrMigrationDrift = errors.New("migrate: migration drift") // ErrInvalidMigrationSource means discovered migration source has an incomplete // pair, an empty script, or inconsistent names for one version. Source is // validated before ledger inspection, so this does not establish whether the // affected version was applied. Filesystem I/O errors are not this category. ErrInvalidMigrationSource = errors.New("migrate: invalid migration source") // ErrLedgerUpgradeRequired means the ledger is uninitialized or uses legacy // checksum bookkeeping. Verify never creates or upgrades the ledger. ErrLedgerUpgradeRequired = errors.New("migrate: ledger upgrade required") )
Functions ¶
This section is empty.
Types ¶
type Dialect ¶
type Dialect string
const ( // Postgres migrations are serialized with a database advisory lock and each // migration is atomic when its SQL is transaction-safe. Postgres Dialect = "postgres" // MySQL is supported for bindings and bookkeeping, but MySQL DDL may commit // implicitly and therefore is not promised to be atomic. MySQL Dialect = "mysql" // SQLite relies on SQLite's transaction and locking behavior. SQLite Dialect = "sqlite" )
type Migrator ¶
type Migrator struct {
DB *sql.DB
Files fs.FS
Dir string
Dialect Dialect
Table string
// LockID identifies the PostgreSQL advisory lock used to serialize a complete
// migration run. Zero selects GoForge's stable default lock ID.
LockID int64
// contains filtered or unexported fields
}
func (*Migrator) Down ¶
Down reverses the latest applied versions. A nonpositive step count means one. On error, the result includes earlier committed reversals.
func (*Migrator) Up ¶
Up applies pending migrations in version order. A nonpositive limit applies all pending migrations. On error, the result includes earlier committed work.
func (*Migrator) Verify ¶ added in v0.9.0
Verify checks migration integrity without creating or altering database objects. It is suitable for request-path readiness checks; use Status for operational inspection that may upgrade a legacy migration ledger. Integrity failures wrap ErrLedgerUpgradeRequired, ErrMigrationDrift, or ErrPendingMigration for errors.Is classification. Invalid source pairs wrap ErrInvalidMigrationSource before the ledger is inspected. Other failures retain their underlying database or filesystem error; error details are not safe to expose to untrusted users.
Source Files