Skip to content

الإعدادات ​

أنشئ migration_config.yml وعدّله داخل مجلد المشروع:

sh
migrate new config

الاتصال بقاعدة البيانات ​

مثال PostgreSQL يقرأ الاتصال من DATABASE_DSN:

yaml
# نوع قاعدة البيانات
dialect: postgres
# اضبط DATABASE_DSN قبل التشغيل
data_source_name: "${DATABASE_DSN}"
# مجلد ملفات الترحيل
migration_source: migrations
# جدول الإصدارات المطبقة
schema_name: migration_schema
الحقلالغرضالافتراضي
dialectنوع قاعدة البياناتpostgres
data_source_nameاتصال واحد؛ لا يجتمع مع data_sourcesمطلوب لقاعدة واحدة
data_sourcesاتصالات مسماةغير مفعّل
migration_sourceمجلد الملفاتmigrations
schema_nameجدول السجلmigration_schema
working_directoryأساس البحث عن الملفاتالمجلد الحالي
migrate_out_of_orderتطبيق الإصدارات المعلقة الأقدمfalse
logger_leveldebug أو info أو warn أو errorinfo

أمثلة الاتصال ​

غيّر المضيف والمنفذ واسم القاعدة أو خدمة Oracle واضبط DB_USER وDB_PASSWORD. يستخدم SQLite مسار ملف.

yaml
dialect: postgres
data_source_name: "postgres://${DB_USER}:${DB_PASSWORD}@db.example:5432/app?sslmode=require"
yaml
dialect: mysql
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:3306)/app?parseTime=true"
yaml
dialect: mariadb
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:3306)/app?parseTime=true"
yaml
dialect: sqlite
data_source_name: "./demo.sqlite"
yaml
dialect: oracle
data_source_name: "oracle://${DB_USER}:${DB_PASSWORD}@db.example:1521/FREEPDB1"
yaml
dialect: mssql
data_source_name: "sqlserver://${DB_USER}:${DB_PASSWORD}@db.example:1433?database=app"
yaml
dialect: clickhouse
data_source_name: "clickhouse://${DB_USER}:${DB_PASSWORD}@db.example:9000/app"
yaml
dialect: tidb
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:4000)/app?parseTime=true"
yaml
dialect: redshift
data_source_name: "postgres://${DB_USER}:${DB_PASSWORD}@cluster.example:5439/app?sslmode=require"

في روابط URL، رمّز المحارف الخاصة في المستخدم وكلمة المرور مثل @ و: و/. استبدال المتغيرات لا يرمّزها تلقائيًا. صيغة MySQL/MariaDB/TiDB ‏user:password@tcp(...) لا تستخدم ترميز URL. اضبط TLS/SSL حسب متطلبات الخادم.

مستويات السجل ​

القيمةالرسائل
debugتنقيح ومعلومات وتحذيرات وأخطاء
infoمعلومات وتحذيرات وأخطاء
warnتحذيرات وأخطاء؛ يقبل warning أيضًا
errorأخطاء فقط
yaml
logger_level: debug # إظهار رسائل التنقيح

متغيرات البيئة ​

يتطلب ${DATABASE_DSN} متغيرًا مضبوطًا، بينما يستخدم ${DB_NAME:app} القيمة app عند غيابه. شارك YAML بين البيئات وقدّم الأسرار عبر متغيرات أو مخزن أسرار. مضيف SSH والمستخدم وعنوان الوكيل يقبلون المتغيرات أيضًا.

ترتيب البحث ​

يُستخدم أول ملف موجود في مجلد العمل:

  1. migration_config.yml
  2. migration_config.yaml
  3. migration_config.json

لا تُدمج الملفات. الملف المختار غير الصالح أو غير المقروء يسبب خطأ. مع -c يُستخدم الملف المحدد فقط، حتى إن كان مفقودًا.

sh
migrate -c ./configs/dev.yml status

إنشاء إعدادات حسب الحالة ​

الحالةالأمر
قاعدة واحدةmigrate new config
اسم مخصصmigrate new config dev.yml
عدة قواعدmigrate new config --multi
أربع قواعدmigrate new config --multi --shards 4
SSH Agentmigrate new config --ssh-tunnel
مفتاح خاصmigrate new config --ssh-tunnel --ssh-auth private_key
كلمة مرور SSHmigrate new config --ssh-tunnel --ssh-auth password
SOCKS5migrate new config --ssh-tunnel --proxy socks5
HTTP CONNECTmigrate new config --ssh-tunnel --proxy http

يمكن جمع الخيارات. استخدم --force للكتابة فوق ملف، وmigrate new config --help لجميع الخيارات.

sh
migrate new config shards.yml --multi --shards 4 --ssh-tunnel --proxy socks5

عدة قواعد بيانات ​

استخدم data_sources بدل data_source_name. النوع والملفات واسم جدول السجل مشتركة. تبدأ الأسماء المولدة من shard_0 والمتغيرات من SHARD_0_DSN.

yaml
dialect: postgres
migration_source: migrations
schema_name: migration_schema
data_sources:
  shard_0:
    data_source_name: "${SHARD_0_DSN}" # اتصال قاعدة البيانات الأولى
  shard_1:
    data_source_name: "${SHARD_1_DSN}" # اتصال قاعدة البيانات الثانية

ملفات الترحيل → shard_0 / shard_1 → النتائج

sh
migrate create
migrate up --dry-run
migrate up
migrate status

تختار كل قاعدة الإصدارات المعلقة بحسب سجلها وتنفذها بالترتيب دون تكرار الناجح. ينشئ new version ملفًا مشتركًا واحدًا. التوازي الافتراضي 8؛ يستخدم --parallel 1 التنفيذ المتسلسل.

sh
migrate up --parallel 4
migrate status --output json

فشل قاعدة لا يوقف البقية. تُجمع النتائج بالاسم وأي فشل يعيد رمز خروج غير صفري. ليست معاملة بين القواعد؛ لا تُلغى نجاحات القواعد الأخرى. يوقف Ctrl+C المهام الجديدة ويلغي النشطة.

يمكن مشاركة ssh_tunnel في المستوى الأعلى. كائن محلي يستبدله كاملًا، أما غيابه أو null فيرثه. انظر SSH. لا تسجل القاعدة الفعلية مرتين ولا تشغّل عليها أوامر متداخلة. ثبّت الملفات والتبعيات أثناء التشغيل وافحص البيانات والسجل قبل إعادة المحاولة.

مجلد العمل ​

sh
migrate -w ./deploy up
migrate -w ./deploy -c configs/dev.yml status

يحدد -w البحث ويستبدل working_directory. المسار النسبي migration_source يبدأ منه؛ -c وحده لا يغيره. مسارات ملفات SSH النسبية تبدأ من مجلد ملف الإعدادات.