دليل Go Migrate

1. نظرة عامة على Go Migrate

Go Migrate هي أداة لإدارة هجرة قاعدة البيانات مكتوبة بلغة Go. يمكن استخدامها على شكل واجهة سطر الأوامر (CLI) أو استيرادها كمكتبة لمشاريع Go. يمكن لـ Go Migrate قراءة ملفات الهجرة من مصادر مختلفة وتطبيقها على قاعدة البيانات في الترتيب الصحيح. يدعم تنويعات السائقين لقواعد البيانات المختلفة ومصادر الهجرة.

2. الإصدارات

يدعم Go Migrate عدة إصدارات، بما في ذلك:

• Master: أحدث إصدار، بما في ذلك الميزات الجديدة وإصلاحات الأخطاء
• v4: الإصدار الثابت، مناسب لبيئات الإنتاج
• v3: لم يعد مدعومًا ويجب عدم استخدامه

3. التثبيت

لاستخدام Go Migrate، يجب عليك تثبيت حزمة Go. قم بتشغيل الأمر التالي للتثبيت:

go get -u -d github.com/golang-migrate/migrate/v4
cd $GOPATH/src/github.com/golang-migrate/migrate/v4

3. استخدام Go Migrate

يمكن استخدام Go Migrate من خلال واجهة سطر الأوامر (CLI) أو كمكتبة في مشروع Go.

3.0. عناوين اتصال قاعدة البيانات (URL)

سواء كنت تستخدم واجهة سطر الأوامر (CLI) أو كود Go، يجب تكوين عناوين قاعدة البيانات للاتصال بقاعدة البيانات.

تنسيق عنوان URL:

dbdriver://username:password@host:port/dbname?param1=true&param2=false

هذا العنوان URL لاتصال قاعدة البيانات يُستخدم للاتصال بقاعدة البيانات وتحديد معلمات الاتصال. إليك شرح لكل جزء:

1. dbdriver://: هذا هو معرف البروتوكول لسائق قاعدة البيانات المستخدم لتحديد أي سائق قاعدة بيانات لاستخدامه، على سبيل المثال، mysql.
2. username:password: هذا هو اسم المستخدم وكلمة المرور المستخدمة للمصادقة. عادةً ما يتم فصل اسم المستخدم وكلمة المرور بفاصلة (:).
3. @: يُستخدم هذا الرمز لفصل اسم المستخدم وكلمة المرور عن اسم الخادم المضيف والمنفذ.
4. host:port: هذا هو اسم المضيف ورقم المنفذ لخادم قاعدة البيانات. اسم المضيف هو عنوان IP أو اسم النطاق لخادم قاعدة البيانات، ورقم المنفذ هو المنفذ الذي يستمع عليه خادم قاعدة البيانات.
5. /dbname: هذا هو اسم قاعدة البيانات المراد الاتصال بها.
6. ?param1=true&param2=false: هذا الجزء هو معلمات الاستعلام المستخدمة لتحديد معلمات اتصال إضافية. في هذا المثال، يوجد معلمتان.

يمكن تعيين هذه المعلمات على أساس متطلبات السائق الخاص بقاعدة البيانات وخادم قاعدة البيانات لتكوين سمات أو سلوك معين للاتصال.

معلمات اتصال Postgres

postgres://postgres:password@localhost:5432/example?sslmode=disable

معلمات اتصال SQLite

sqlite3://path/to/database?query

معلمات اتصال MongoDB

mongodb://user:password@host:port/dbname?query

3.1 استخدام واجهة سطر الأوامر (CLI)

3.1.1 الاستخدام الأساسي

لاستخدام واجهة سطر الأوامر (CLI)، قم بتشغيل الأمر التالي:

migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2

يطبق هذا الأمر الهجرات من المصدر المحدد على قاعدة البيانات المعطاة. الرقم "2" يشير إلى عدد الهجرات لتطبيقها.

3.1.2 استخدام Docker

يمكن أيضًا استخدام Go Migrate مع Docker. قم بتشغيل الأمر التالي:

docker run -v {{مجلد الهجرة}}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/database up 2

يقوم هذا الأمر بتشغيل Go Migrate في حاوية Docker وتطبيق الهجرات من المصدر المحدد على قاعدة البيانات المعطاة.

3.2 كيفية استخدام Go Migrate في مشروع Go الخاص بك

لكي تستخدم Go Migrate في مشروع Go الخاص بك، يجب عليك استيراد الحزم والمكتبات المطلوبة. فيما يلي مثال:

import (
    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/github"
)

func main() {
    m, err := migrate.New(
        "github://mattes:personal-access-token@mattes/migrate_test",
        "postgres://localhost:5432/database?sslmode=enable")
    m.Steps(2)
}

هذا الكود يقوم بتهيئة Go Migrate بالمصدر وقاعدة البيانات المحددة، ثم يقوم بتطبيق 2 عملية تطوير باستخدام الطريقة Steps.

إذا كنت ترغب في استخدام عميل قاعدة بيانات موجود، يرجى الرجوع إلى المثال التالي:

import (
    "database/sql"
    _ "github.com/lib/pq"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable")
    driver, err := postgres.WithInstance(db, &postgres.Config{})
    m, err := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "postgres", driver)
    m.Up()
}

يقوم هذا الكود باستيراد الحزم المطلوبة وتهيئة عميل قاعدة البيانات باستخدام حزمة sql، ثم يقوم بإنشاء مثيل جديد لـ Go Migrate باستخدام الطريقة NewWithDatabaseInstance، مُحددًا المصدر ومشغل قاعدة البيانات. وأخيرًا، يطبق العملية التطوير باستخدام الطريقة Up.

4. المشغلات المدعومة لقواعد البيانات

Go Migrate تدعم العديد من مشغلات قواعد البيانات بما في ذلك:

• PostgreSQL
• PGX v4
• PGX v5
• Redshift
• Ql
• Cassandra
• SQLite
• SQLite3
• SQLCipher
• MySQL/MariaDB
• Neo4j
• MongoDB
• CrateDB
• Shell
• Google Cloud Spanner
• CockroachDB
• YugabyteDB
• ClickHouse
• Firebird
• MS SQL Server

5. المصادر المدعومة للتطوير

Go Migrate تدعم العديد من مصادر التطوير بما في ذلك:

• نظام الملفات: قراءة عمليات التطوير من نظام الملفات المحلي.
• io/fs: قراءة عمليات التطوير باستخدام حزمة io/fs في Go.
• Go-Bindata: قراءة عمليات التطوير من البيانات الثنائية المضمنة باستخدام حزمة jteeuwen/go-bindata.
• pkger: قراءة عمليات التطوير من البيانات الثنائية المضمنة باستخدام حزمة markbates/pkger.
• GitHub: قراءة عمليات التطوير من مستودع GitHub عن بعد.
• GitHub Enterprise: قراءة عمليات التطوير من مستودع GitHub Enterprise عن بعد.
• Bitbucket: قراءة عمليات التطوير من مستودع Bitbucket عن بعد.
• Gitlab: قراءة عمليات التطوير من مستودع Gitlab عن بعد.
• AWS S3: قراءة عمليات التطوير من خدمة Amazon Web Services S3.
• Google Cloud Storage: قراءة عمليات التطوير من تخزين Google Cloud Platform.

اعتمادًا على متطلبات مشروعك، يمكنك تخزين ملفات تطوير قاعدة بيانات في مصادر تخزين الملفات المدعومة المذكورة أعلاه.

6. ملفات التطوير

ملفات التطوير في Go Migrate لديها تنسيقات محددة لأسماء الملفات والمحتوى.

6.1 تنسيق أسماء ملفات التطوير

كل عملية تطوير تتكون من ملف عملية تطوير "up" وملف عملية تطوير "down" متوافق. يجب أن تلتزم أسماء ملفات التطوير بالتنسيق التالي:

{version}_{title}.up.{extension}
{version}_{title}.down.{extension}

version رقم فريد يمثل الترتيب الذي يجب فيه تطبيق عمليات التطوير. title وصف اختياري للعملية التطويرية. extension يعتمد على نظام قاعدة البيانات المستخدم (مثل، للمتغيرات SQL، استخدم .sql).

6.2 تنسيق محتوى ملفات التطوير

محتوى ملفات التطوير يتفاوت اعتمادًا على نظام قاعدة البيانات، عادةً ما يشمل كتابة SQL مباشرة.

على سبيل المثال، فيما يلي ملفين للتطوير:

• 000001_create_users_table.up.sql
• 000001_create_users_table.down.sql

ملف تطوير 000001_create_users_table.up.sql

CREATE TABLE IF NOT EXISTS users(
   user_id serial PRIMARY KEY,
   username VARCHAR (50) UNIQUE NOT NULL,
   password VARCHAR (50) NOT NULL,
   email VARCHAR (300) UNIQUE NOT NULL
);

ملف تطوير 000001_create_users_table.down.sql، يُستخدم الملف الخلفي أساسًا للتراجع عن العمليات السابقة، عادةً لأغراض الرجوع.

DROP TABLE IF EXISTS users;

6.3 قابلية عكسية الهجرة

كتابة الهجرات القابلة للعكس تُعتبر ممارسة جيدة. وهذا يعني أن يمكن تشغيل هجرات "تصاعدية" و "تنازلية" إلى أي إصدار، مما يعيد بشكل فعال وينظف حالة قاعدة البيانات.

لضمان القابلية للعكس، يجب أن تحتوي كل هجرة على ملف "تصاعدية" و "تنازلية" مقابل. ملف الهجرة "تصاعدية" يحتوي على العمليات المطبقة في الهجرة، بينما ملف الهجرة "تنازلية" يحتوي على العمليات لتراجع الهجرة.

7. استخدام MySQL

Go Migrate يوفر الدعم لقواعد بيانات MySQL. للاتصال بقاعدة بيانات MySQL، يجب أن يكون عنوان URL لقاعدة البيانات في الصيغة التالية:

mysql://user:password@tcp(host:port)/dbname?query

يمكن تضمين معلمات الاستعلام في العنوان URL، مثل اسم جدول الهجرة، معلمات TLS، إلخ. للحصول على قائمة كاملة لمعلمات الاستعلام، يرجى الرجوع إلى Go Migrate MySQL documentation.

7.1 معلمات استعلام العنوان URL

• x-migrations-table: اسم جدول الهجرة.
• x-no-lock: يُعين على true لتجاوز عبارات GET_LOCK/RELEASE_LOCK. مفيد لإصدارات MySQL متعددة الماستر.
• x-statement-timeout: يحدد أي عبارة تتجاوز عدد محدد من ميلي ثانية.
• dbname: اسم قاعدة البيانات المراد الاتصال بها.
• user: اسم المستخدم لتسجيل الدخول.
• password: كلمة مرور المستخدم.
• host: الخادم الذي يتم الاتصال به.
• port: المنفذ المراد الربط به.
• tls: معلمات اتصال التشفير TLS/SSL.
• x-tls-ca: موقع ملف السلطة الاصدارة (Certificate Authority).
• x-tls-cert: موقع ملف الشهادة الخاصة بالعميل.
• x-tls-key: موقع ملف المفتاح الخاص.
• x-tls-insecure-skip-verify: ما إذا كان سيتم استخدام SSL أم لا.

7.2 الاستخدام مع عملاق العملاء الحالي

إذا كنت تنوي استخدام Go Migrate مع عميل MySQL الحالي، تأكد من استخدام المعلمة multiStatements=true عند إنشاء العميل. فيما يلي مثال:

package main

import (
    "database/sql"
    
    _ "github.com/go-sql-driver/mysql"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/mysql"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, _ := sql.Open("mysql", "user:password@tcp(host:port)/dbname?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql", 
        driver,
    )
    
    m.Steps(2)
}

يقوم هذا الكود بإستيراد الحزم المطلوبة، وإنشاء عميل قاعدة بيانات MySQL، وتهيئة Go Migrate مع مثيل قاعدة البيانات. بعد ذلك، يطبق هجرتين باستخدام الطريقة Steps.