Documentation
¶
Overview ¶
Package migrations wraps Atlas versioned migrations for Gombit apps.
MakeMigrations generates SQL via Atlas Program Mode. Migrate, Status, and Rollback apply and report those migrations while recording D4 metadata in framework_migrations. Seed runs ordered SQL files from database/seeds, and Reset drops the schema then migrate + seed.
Index ¶
- func AtlasURL(cfg config.DatabaseConfig) (string, error)
- func DownFilename(upFilename string) (string, error)
- func DownPath(migrationDir string, version string, name string) string
- func DropSchema(ctx context.Context, opts ApplyOptions) error
- func MakeMigrations(ctx context.Context, opts Options) error
- func Migrate(ctx context.Context, opts ApplyOptions) error
- func ParseDownFilename(filename string) (version string, name string, err error)
- func ParseMigrationFilename(filename string) (version string, name string, err error)
- func RegistryPath(migrationDir string) string
- func Reset(ctx context.Context, opts ResetOptions) error
- func Rollback(ctx context.Context, opts ApplyOptions) error
- func SaveRegistry(migrationDir string, models []Model) error
- func Seed(ctx context.Context, opts SeedOptions) error
- func Status(ctx context.Context, opts ApplyOptions) error
- type ApplyOptions
- type MigrationFile
- type Model
- type Options
- type ResetOptions
- type Revision
- type SeedOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtlasURL ¶
func AtlasURL(cfg config.DatabaseConfig) (string, error)
AtlasURL converts a Gombit database config into an Atlas --url value.
func DownFilename ¶
DownFilename returns the companion down filename (basename) for an up migration file.
func DownPath ¶
DownPath returns the path to the Gombit-owned down SQL for an up migration. Downs live under <migrationDir>/downs/ so Atlas never scans them (Atlas panics on golang-migrate-style .down.sql files in the versioned migration directory).
func DropSchema ¶
func DropSchema(ctx context.Context, opts ApplyOptions) error
DropSchema removes all user tables and views from the configured database.
Driver wipe strategy:
- SQLite: DROP every non-sqlite_* table/view from sqlite_master
- Postgres: DROP SCHEMA atlas_schema_revisions CASCADE (Atlas default); DROP SCHEMA public CASCADE; CREATE SCHEMA public; restore grants
- MySQL: disable FK checks, DROP every base table and view, re-enable checks
The SQLite database file is not deleted so in-memory and shared-cache DSNs work.
func MakeMigrations ¶
MakeMigrations generates an Atlas Program Mode loader and runs atlas migrate diff.
func Migrate ¶
func Migrate(ctx context.Context, opts ApplyOptions) error
Migrate applies pending Atlas migrations and mirrors them into framework_migrations.
After atlas migrate apply succeeds, only pending versions that appear in atlas_schema_revisions are recorded. This keeps Gombit's ledger aligned with Atlas when the two previously diverged or when Atlas applies a subset.
func ParseDownFilename ¶
ParseDownFilename parses a Gombit companion down migration filename.
func ParseMigrationFilename ¶
ParseMigrationFilename parses an Atlas up migration filename.
func RegistryPath ¶
RegistryPath returns the path to the persisted model registry inside migrationDir.
func Reset ¶
func Reset(ctx context.Context, opts ResetOptions) error
Reset drops the database schema, applies migrations, then runs seeders.
When Environment is production, Force must be true.
func Rollback ¶
func Rollback(ctx context.Context, opts ApplyOptions) error
Rollback rolls back the latest framework_migrations batch using companion down SQL. Each down file is split into individual statements (like Seed) and executed one Exec per statement, so a down file is no longer required to be a single SQL statement on MySQL.
On SQLite and PostgreSQL, down SQL and revision deletes run in one transaction so a mid-batch failure leaves neither schema nor revision ledgers partially updated. MySQL DDL often auto-commits, so a mid-batch failure can leave the schema partially rolled back while revision rows remain — including inside a single down file, if an earlier statement in it already committed before a later one failed; the error message names the failing statement and file, and revision rows are not deleted until every down succeeds.
func SaveRegistry ¶
SaveRegistry persists models to migrationDir, sorted for stable diffs regardless of the order callers passed them in.
func Seed ¶
func Seed(ctx context.Context, opts SeedOptions) error
Seed executes SQL seed files from the configured seed directory in lexical order.
Missing or empty seed directories succeed with "No seed files.". Non-.sql entries and nested subdirectories are skipped with a warning on stderr. Each file may contain multiple statements separated by `;`; statements are executed in order and execution stops on the first SQL error.
Types ¶
type ApplyOptions ¶
type ApplyOptions struct {
WorkDir string
MigrationDir string
AtlasBinary string
Database config.DatabaseConfig
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
ApplyOptions configures migrate, rollback, and status commands.
type MigrationFile ¶
MigrationFile is one Atlas versioned migration on disk.
func ListMigrationFiles ¶
func ListMigrationFiles(dir string) ([]MigrationFile, error)
ListMigrationFiles lists Atlas up migrations in dir, with optional down paths. Non-matching *.sql filenames (other than atlas.sum) are skipped with a warning. Companion downs live under downs/ and are not listed as up files.
func ListMigrationFilesWithSkipped ¶
func ListMigrationFilesWithSkipped(dir string) ([]MigrationFile, []string, error)
ListMigrationFilesWithSkipped lists migrations and returns skipped *.sql names.
type Model ¶
Model identifies one GORM model type imported by the generated Atlas loader.
func LoadRegistry ¶
LoadRegistry reads the model set previously persisted in migrationDir. A missing file is not an error — it means no migration has been generated there yet — and returns a nil slice.
func MergeModels ¶
MergeModels unions existing (typically the persisted registry) with additional (typically the --model flags for this invocation), removing duplicates. additional's relative order is preserved first — it is what the caller explicitly asked for this run — followed by any existing-only models in sorted order.
func ParseModel ¶
ParseModel parses a model spec in the form "import/path.TypeName".
func SubtractModels ¶
SubtractModels returns models with every entry in remove removed.
type Options ¶
type Options struct {
WorkDir string
Name string
Driver config.DatabaseDriver
MigrationDir string
AtlasBinary string
// Models are the GORM models this invocation is declaring. They are
// merged with whatever is already in the persisted registry
// (RegistryPath) — not the entire desired schema by themselves — so a
// migration for one new model does not implicitly drop tables for
// models used in earlier migrations.
Models []Model
// ForgetModels removes models from the persisted registry (and this
// invocation's desired schema), the explicit way to let Atlas propose
// dropping a table that's genuinely going away.
ForgetModels []Model
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
Options configures MakeMigrations.
type ResetOptions ¶
type ResetOptions struct {
ApplyOptions
SeedDir string
Force bool
Environment config.Environment
}
ResetOptions configures gombit db reset (drop + migrate + seed).
type Revision ¶
type Revision struct {
Version string `gorm:"column:version;primaryKey;size:64"`
Name string `gorm:"column:name;size:255;not null"`
Batch int `gorm:"column:batch;not null"`
AppliedAt time.Time `gorm:"column:applied_at;not null"`
}
Revision is one applied migration recorded in framework_migrations (D4).
type SeedOptions ¶
type SeedOptions struct {
WorkDir string
SeedDir string
Database config.DatabaseConfig
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
SeedOptions configures gombit db seed.
Source Files
Directories