Documentation
¶
Index ¶
- func ChecksumContent(content string) string
- func ForceLockForTest(ctx context.Context, drv driver.Driver) error
- func ForceUnlockForTest(ctx context.Context, drv driver.Driver) error
- func WriteMigration(dir, name, upSQL, downSQL string) (string, error)
- type LintResult
- type Migration
- type MigrationState
- type MigrationStatus
- type Runner
- func (r *Runner) Dialect() string
- func (r *Runner) Down(ctx context.Context) error
- func (r *Runner) Lint(ctx context.Context) ([]LintResult, error)
- func (r *Runner) Pending(ctx context.Context) ([]Migration, error)
- func (r *Runner) Status(ctx context.Context) ([]MigrationStatus, error)
- func (r *Runner) Up(ctx context.Context) (int, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ChecksumContent ¶
ChecksumContent returns the SHA-256 hex digest of the given content string.
func ForceLockForTest ¶ added in v0.5.0
ForceLockForTest acquires the SQLite/libSQL sentinel lock out of band. Test-only.
func ForceUnlockForTest ¶ added in v0.5.0
ForceUnlockForTest releases the SQLite/libSQL sentinel lock. Test-only.
func WriteMigration ¶
WriteMigration creates a new migration file pair in the given directory. It returns the generated version string (timestamp in YYYYMMDDHHmmss format).
Types ¶
type LintResult ¶
LintResult reports a migration file whose content has changed after it was applied to the database.
type Migration ¶
Migration represents a single versioned migration with up and down SQL.
func MergeMigrations ¶ added in v0.7.0
MergeMigrations reads every filesystem and returns one set sorted by version, so the migrations of several modules run in the order they were written.
A version that appears in two modules is an error. Two slices generated in the same second, or on two branches, produce the same version, and there is no correct order between them. A failed start is better than a wrong apply order, so the error names both files.
func ParseMigrationDir ¶
ParseMigrationDir reads a directory of migration files and returns them sorted by version. Files must follow the naming convention:
<version>_<name>.up.sql <version>_<name>.down.sql
If the directory does not exist, it returns nil with no error.
type MigrationState ¶
type MigrationState string
MigrationState indicates the lifecycle state of a migration.
const ( // StateApplied means the migration is in the directory and has been applied // with a matching checksum. StateApplied MigrationState = "applied" // StatePending means the migration is in the directory but has not been applied. StatePending MigrationState = "pending" // StateModified means the migration has been applied but the file content // no longer matches the stored checksum. StateModified MigrationState = "modified" // StateMissing means the migration was applied but the file no longer exists // in the migration directory. StateMissing MigrationState = "missing" )
type MigrationStatus ¶
type MigrationStatus struct {
Version string
Name string
State MigrationState
// Applied is true when the migration has been applied to the database,
// regardless of whether the file still matches. Kept for backward compatibility.
Applied bool
}
MigrationStatus represents the state of a single migration.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes migrations against a database using the driver interface.
func NewRunner ¶
NewRunner creates a Runner that reads migration files from dir and executes them against the provided driver. dialect ("postgres", "sqlite", or "libsql") selects the migration-lock strategy used by Up/Down.
func NewRunnerFS ¶ added in v0.7.0
NewRunnerFS creates a Runner that reads its migrations from one or more filesystems instead of a directory. A module embeds its own migrations with //go:embed, and the sets merge in version order.
func (*Runner) Dialect ¶ added in v0.5.0
Dialect returns the dialect string the Runner was constructed with.
func (*Runner) Lint ¶
func (r *Runner) Lint(ctx context.Context) ([]LintResult, error)
Lint checks all applied migrations for checksum mismatches, detecting files that were modified after being applied.
func (*Runner) Pending ¶ added in v0.5.0
Pending returns the migrations present in the directory that have not yet been applied to the database, in version order. It is the basis for `migrate check`: generating a new migration while unapplied files exist compounds snapshot drift, so callers should surface a clear error.
func (*Runner) Status ¶
func (r *Runner) Status(ctx context.Context) ([]MigrationStatus, error)
Status returns the status of all migrations, including those in the directory and those applied to the database. Each migration is classified as one of: applied, pending, modified, or missing.
func (*Runner) Up ¶
Up applies every pending migration in order and returns how many it applied.
Up takes the migration lock first, so several replicas that boot at one time serialise: one applies the migrations and the others wait and then find nothing to do.
Do not call Up from two goroutines of one process that share one connection pool. Each waiting call holds a pool connection while it waits for the lock, so a pool smaller than the count of callers starves the winner. Separate processes hold separate pools and are not affected.
Source Files