Go から利用する
ルートパッケージの公開 API は SemVer に従います。internal/* は公開 API ではありません。
接続プールの終了処理は呼び出し側の責任です。同じ DB の移行は直列実行し、適切な context の期限を使います。Config.DryRun と DryRunOutput は変更をプレビューしますが、Create() は履歴テーブルを作成します。既定のログは NoopLogger です。
FSSource は embed.FS を使えます。スクリプトの依存は共有モジュールを参照してください。migrate に接続を管理させる場合は OpenConnection を使い、Connection.Context() で Ping とサービスを呼び、最後に Close() します。SQLite のドライバーは呼び出し側で登録します。ConnectionOptions.Prompt と HostKeyPrompt は明示的に設定し、キャンセルに対応させます。未指定なら入力や未知のホストへの信頼は行いません。
CLI に加えて、github.com/exc-works/migrate はサービスコードから直接 import してマイグレーションを実行できます。ユニットテスト、起動フック、管理画面への組み込みに便利です。
インストール
bash
go get github.com/exc-works/migrate必要なデータベースドライバを import してください(ライブラリは特定のドライバに依存しません):
go
import (
_ "modernc.org/sqlite" // sqlite
_ "github.com/jackc/pgx/v5/stdlib" // postgres
_ "github.com/go-sql-driver/mysql" // mysql / mariadb / tidb
// ...
)最小例
go
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: 履歴テーブルが無ければ作成
panic(err)
}
if err := svc.Up(); err != nil {
panic(err)
}
}主要 API
migrate.NewService(ctx, migrate.Config)はマイグレーション実行器を構築しますsvc.Create()は履歴テーブルmigration_schemaを作成します(idempotent)svc.Up()は未適用のマイグレーションをすべて適用しますsvc.Down(toVersion, all)は指定バージョンまたはすべてをロールバックしますsvc.Status()は[]migrate.MigrationStatusを返しますsvc.Baseline()は既存の pending ファイルをbaselineとしてマークします
よく使う型:
- Dialect(コンストラクタを推奨 —
Dialectインターフェースを返します):migrate.NewPostgresDialect(),NewMySQLDialect(),NewSQLiteDialect(),NewMSSQLDialect(),NewOracleDialect(),NewClickHouseDialect(),NewMariaDBDialect(),NewTiDBDialect(),NewRedshiftDialect()、または名前解決用のmigrate.DialectFromName("postgres") - Source:
DirectorySource(ファイルシステム)、StringSource(インメモリ)、FSSource(任意のfs.FS、例えば//go:embedやos.DirFS)、CombinedSource(複数ソースの結合) - Logger:
migrate.NoopLogger{}(デフォルト)、migrate.NewStdLogger("info", os.Stdout)、またはmigrate.Loggerを実装した任意の型