README
¶
gas/migrate
Part of the Gas monorepo · Documentation · All modules
Database migrations for the Gas framework. Services declare the schema they own; migrate applies everything in global version order, with dirty-state detection and rollback.
Implements gas.MigrationManager.
go get github.com/gasmod/gas/migrate
gas.WithSingletonService[gas.MigrationManager](migrate.New()),
migrate.New() needs gas.DatabaseProvider.
| Dialect | Driver names |
|---|---|
| PostgreSQL | postgres, pgx |
| MySQL | mysql |
| SQLite | sqlite, sqlite3 |
Documentation
The full guide, with configuration, testing, and worked examples, is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.
- Guide: Connect a database
- API reference: pkg.go.dev/github.com/gasmod/gas/migrate
- Contributing: CONTRIBUTING.md
License
Documentation
¶
Overview ¶
Package migrate provides database migration management for the Gas ecosystem. Provides registration, RunPending, Down/rollback, dirty-state handling, and sqlc multi-dialect adapters.
See the module README for usage examples and design rationale.
SPDX-License-Identifier: MIT
Index ¶
- func New() func(gas.DatabaseProvider) *Service
- type Service
- func (s *Service) CheckReady(ctx context.Context) error
- func (s *Service) Close() error
- func (s *Service) Down(n int) error
- func (s *Service) Init() error
- func (s *Service) Name() string
- func (s *Service) Register(service string, migration gas.Migration)
- func (s *Service) RegisterFS(service string, fsys fs.FS) error
- func (s *Service) RegisterSlice(service string, migrations []gas.Migration)
- func (s *Service) RunPending() error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New() func(gas.DatabaseProvider) *Service
New returns a DI-injectable constructor for the migration manager service.
Types ¶
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service implements gas.Service and gas.MigrationManager. It tracks database migrations across all Gas services, applying pending migrations on startup and supporting rollback operations.
func (*Service) CheckReady ¶
CheckReady reports whether the service is ready to accept traffic. It returns an error if the service is closed, not initialized, has any dirty migrations, or has registered migrations that have not yet been applied.
func (*Service) Init ¶
Init validates dependencies, selects the correct sqlc adapter based on the configured database driver, and creates the migrations tracking table.
func (*Service) RegisterFS ¶
RegisterFS reads migration files from an fs.FS and registers them for the given service. Files must follow the naming convention:
{version}_{description}.up.sql — the up (apply) SQL
{version}_{description}.down.sql — the down (rollback) SQL
The version is the first underscore-delimited segment, and the description is the remaining underscored segments converted to spaces. Every .up.sql file must have a matching .down.sql file.
func (*Service) RegisterSlice ¶
RegisterSlice adds multiple migrations at once for the given service.
func (*Service) RunPending ¶
RunPending applies all unapplied migrations in global version order. If any migration is marked dirty, execution is blocked until resolved.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
db
|
|
|
Package migratetest provides a mock implementation of gas.MigrationManager for use in tests.
|
Package migratetest provides a mock implementation of gas.MigrationManager for use in tests. |