Usar em Go
A API pública do pacote raiz segue SemVer; internal/* não é público. O chamador fecha o pool, usa context apropriado e serializa migrações no mesmo banco.
Config.DryRun e DryRunOutput mostram a prévia, mas Create() sempre cria o histórico. Logger padrão: NoopLogger. Para scripts embutidos, use FSSource com dependências.
Com OpenConnection, use Connection.Context() para Ping e serviço e depois Close(). Drivers de rede são registrados; SQLite exige registro pelo chamador. ConnectionOptions.Prompt e HostKeyPrompt são opcionais e devem aceitar cancelamento. Sem callbacks não há entrada nem confiança em hosts desconhecidos.
Além do CLI, github.com/exc-works/migrate pode ser importado diretamente do código do seu serviço para executar migrações — útil para testes unitários, hooks de inicialização ou painéis administrativos.
Instalação
go get github.com/exc-works/migrateImporte o driver de banco de dados que precisar (a biblioteca não fixa nenhum):
import (
_ "modernc.org/sqlite" // sqlite
_ "github.com/jackc/pgx/v5/stdlib" // postgres
_ "github.com/go-sql-driver/mysql" // mysql / mariadb / tidb
// ...
)Exemplo mínimo
package main
import (
"context"
"database/sql"
_ "modernc.org/sqlite"
"github.com/exc-works/migrate"
)
func main() {
db, err := sql.Open("sqlite", "./app.sqlite")
if err != nil {
panic(err)
}
defer db.Close()
svc, err := migrate.NewService(context.Background(), migrate.Config{
Dialect: migrate.NewSQLiteDialect(),
DB: db,
MigrationSource: migrate.DirectorySource{Directory: "./migrations"},
})
if err != nil {
panic(err)
}
if err := svc.Create(); err != nil { // idempotente: cria a tabela de histórico se ausente
panic(err)
}
if err := svc.Up(); err != nil {
panic(err)
}
}API principal
migrate.NewService(ctx, migrate.Config)constrói um executor de migraçõessvc.Create()cria a tabela de históricomigration_schema(idempotente)svc.Up()aplica todas as migrações pendentessvc.Down(toVersion, all)reverte até uma versão alvo ou tudosvc.Status()retorna[]migrate.MigrationStatussvc.Baseline()marca arquivos pendentes existentes comobaseline
Tipos comuns:
- Dialetos (prefira os construtores — retornam a interface
Dialect):migrate.NewPostgresDialect(),NewMySQLDialect(),NewSQLiteDialect(),NewMSSQLDialect(),NewOracleDialect(),NewClickHouseDialect(),NewMariaDBDialect(),NewTiDBDialect(),NewRedshiftDialect(), oumigrate.DialectFromName("postgres")para busca por nome - Fontes:
DirectorySource(sistema de arquivos),StringSource(slice em memória),FSSource(qualquerfs.FS, como//go:embedouos.DirFS),CombinedSource(combina várias fontes) - Loggers:
migrate.NoopLogger{}(padrão),migrate.NewStdLogger("info", os.Stdout)ou qualquer tipo que implementemigrate.Logger