Utiliser depuis Go
L’API publique du paquet racine suit SemVer ; internal/* n’en fait pas partie. L’appelant gère la fermeture du pool et sérialise les migrations sur une même base avec un context adapté.
Config.DryRun et DryRunOutput prévisualisent les changements, mais Create() crée toujours l’historique. Le logger par défaut est NoopLogger. Pour embarquer des scripts, utilisez FSSource et ses dépendances.
Avec OpenConnection, utilisez Connection.Context() pour Ping et le service, puis Close(). Les pilotes réseau sont enregistrés ; SQLite exige un enregistrement côté appelant. ConnectionOptions.Prompt et HostKeyPrompt sont facultatifs et doivent gérer l’annulation. Sans eux, aucune saisie ni confiance automatique envers les hôtes inconnus.
En plus du CLI, github.com/exc-works/migrate peut être importé directement depuis le code de votre service pour exécuter les migrations — pratique pour les tests unitaires, les hooks de démarrage ou les panneaux d’administration.
Installation
go get github.com/exc-works/migrateImportez le pilote de base de données dont vous avez besoin (la bibliothèque n’en fige aucun) :
import (
_ "modernc.org/sqlite" // sqlite
_ "github.com/jackc/pgx/v5/stdlib" // postgres
_ "github.com/go-sql-driver/mysql" // mysql / mariadb / tidb
// ...
)Exemple minimal
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 { // idempotent : crée la table d’historique si absente
panic(err)
}
if err := svc.Up(); err != nil {
panic(err)
}
}API clé
migrate.NewService(ctx, migrate.Config)construit un exécuteur de migrationssvc.Create()crée la table d’historiquemigration_schema(idempotent)svc.Up()applique toutes les migrations en attentesvc.Down(toVersion, all)revient à une version cible ou à toutsvc.Status()retourne[]migrate.MigrationStatussvc.Baseline()marque les fichiers en attente existants commebaseline
Types courants :
- Dialectes (préférez les constructeurs — ils renvoient l’interface
Dialect) :migrate.NewPostgresDialect(),NewMySQLDialect(),NewSQLiteDialect(),NewMSSQLDialect(),NewOracleDialect(),NewClickHouseDialect(),NewMariaDBDialect(),NewTiDBDialect(),NewRedshiftDialect(), oumigrate.DialectFromName("postgres")pour une résolution par nom - Sources :
DirectorySource(système de fichiers),StringSource(slice en mémoire),FSSource(n’importe quelfs.FS, par ex.//go:embedouos.DirFS),CombinedSource(fusionne plusieurs sources) - Loggers :
migrate.NoopLogger{}(par défaut),migrate.NewStdLogger("info", os.Stdout), ou tout type implémentantmigrate.Logger