الاستخدام من Go
واجهة الحزمة الجذرية تتبع SemVer؛ internal/* ليست عامة. يدير المستدعي إغلاق المجمع وcontext ويجعل ترحيلات القاعدة الواحدة متسلسلة.
تعرض Config.DryRun وDryRunOutput الخطة، لكن Create() ينشئ السجل دائمًا. المسجل الافتراضي NoopLogger. استخدم FSSource وتبعياته لتضمين السكربتات.
مع OpenConnection استخدم Connection.Context() في Ping والخدمة، ثم Close(). السائقون الشبكيون مسجلون، أما SQLite فعليك تسجيله. ConnectionOptions.Prompt وHostKeyPrompt اختياريان ويجب أن يحترما الإلغاء. دون callbacks لا طلب إدخال ولا ثقة بمضيف غير معروف.
بالإضافة إلى واجهة CLI، يمكن استيراد github.com/exc-works/migrate مباشرةً من كود خدمتك لتشغيل عمليات الترحيل — وهو مفيد لاختبارات الوحدة، وخطوات بدء التشغيل، أو لوحات الإدارة.
التثبيت
go get github.com/exc-works/migrateاستورد مشغّل قاعدة البيانات الذي تحتاجه (المكتبة لا تربط واحدًا بعينه):
import (
_ "modernc.org/sqlite" // sqlite
_ "github.com/jackc/pgx/v5/stdlib" // postgres
_ "github.com/go-sql-driver/mysql" // mysql / mariadb / tidb
// ...
)مثال مختصر
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.MigrationStatussvc.Baseline()يُعلّم الملفات المعلّقة الحالية بأنهاbaseline
الأنواع الشائعة:
- اللهجات (يُفضَّل استخدام الدوال البانية — فهي تُعيد واجهة
Dialect):migrate.NewPostgresDialect(),NewMySQLDialect(),NewSQLiteDialect(),NewMSSQLDialect(),NewOracleDialect(),NewClickHouseDialect(),NewMariaDBDialect(),NewTiDBDialect(),NewRedshiftDialect()، أوmigrate.DialectFromName("postgres")للبحث بالاسم - المصادر:
DirectorySource(نظام الملفات)،StringSource(شريحة في الذاكرة)،FSSource(أيfs.FS، مثل//go:embedأوos.DirFS)،CombinedSource(يجمع عدة مصادر) - السجلات:
migrate.NoopLogger{}(افتراضي)،migrate.NewStdLogger("info", os.Stdout)، أو أي نوع يُطبّقmigrate.Logger