Hướng dẫn sử dụng Go Migrate

1. Tổng quan về Go Migrate

Go Migrate là một công cụ quản lý di dời cơ sở dữ liệu được viết bằng ngôn ngữ Go. Nó có thể được sử dụng dưới dạng giao diện dòng lệnh (CLI) hoặc được nhập như một thư viện cho các dự án Go. Go Migrate có thể đọc các tệp di dời từ các nguồn khác nhau và áp dụng chúng vào cơ sở dữ liệu theo thứ tự đúng đắn. Nó hỗ trợ nhiều trình điều khiển cơ sở dữ liệu và nguồn di dời khác nhau.

2. Phiên bản

Go Migrate hỗ trợ nhiều phiên bản, bao gồm:

  • Master: Phiên bản mới nhất, bao gồm các tính năng mới và sửa lỗi
  • v4: Phiên bản ổn định, phù hợp cho môi trường sản xuất
  • v3: Không còn được hỗ trợ và không nên sử dụng

3. Cài đặt

Để sử dụng Go Migrate, bạn cần cài đặt gói Go. Chạy lệnh sau để cài đặt:

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

4. Sử dụng Go Migrate

Go Migrate có thể được sử dụng thông qua CLI hoặc như một thư viện trong dự án Go.

4.0. URL Kết nối Cơ sở dữ liệu

Cho dù sử dụng CLI hay mã Go, URL cơ sở dữ liệu cần được cấu hình để kết nối với cơ sở dữ liệu.

Định dạng URL:

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

URL này là URL kết nối cơ sở dữ liệu được sử dụng để kết nối với cơ sở dữ liệu và chỉ định các tham số kết nối. Đây là giải thích cho mỗi phần:

  1. dbdriver://: Đây là bộ nhận diện giao thức cho trình điều khiển cơ sở dữ liệu được sử dụng để chỉ định trình điều khiển cơ sở dữ liệu nào được sử dụng, ví dụ: mysql.
  2. username:password: Đây là tên người dùng và mật khẩu được sử dụng để xác thực. Thông thường, tên người dùng và mật khẩu được phân cách bằng dấu hai chấm (:).
  3. @: Ký hiệu này được sử dụng để phân tách tên người dùng và mật khẩu từ tên máy chủ và cổng.
  4. host:port: Đây là tên máy chủ và số cổng của máy chủ cơ sở dữ liệu. Tên máy chủ là địa chỉ IP hoặc tên miền của máy chủ cơ sở dữ liệu và số cổng là cổng mà máy chủ cơ sở dữ liệu đang lắng nghe.
  5. /dbname: Đây là tên cơ sở dữ liệu để kết nối.
  6. ?param1=true&param2=false: Phần này là các tham số truy vấn được sử dụng để chỉ định các tham số kết nối bổ sung. Trong ví dụ này, có hai tham số.

Các tham số truy vấn này có thể được thiết lập theo yêu cầu cụ thể của trình điều khiển cơ sở dữ liệu và máy chủ cơ sở dữ liệu để cấu hình các thuộc tính hoặc hành vi cụ thể của kết nối.

Tham số Kết nối Postgres

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

Tham số Kết nối SQLite

sqlite3://path/to/database?query

Tham số Kết nối MongoDB

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

4.1 Sử dụng qua CLI

4.1.1 Sử dụng Cơ bản

Để sử dụng CLI, chạy lệnh sau:

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

Lệnh này áp dụng các di dời từ nguồn được chỉ định vào cơ sở dữ liệu đã cho. Số "2" chỉ ra số lượng di dời cần áp dụng.

4.1.2 Sử dụng qua Docker

Go Migrate cũng có thể được sử dụng với Docker. Chạy lệnh sau:

docker run -v {{ thư mục di dời }}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/database up 2

Lệnh này chạy Go Migrate trong một container Docker và áp dụng các di dời từ nguồn được chỉ định vào cơ sở dữ liệu đã cho.

3.2 Sử dụng trong Dự án Go của bạn

Để sử dụng Go Migrate trong dự án Go của bạn, bạn cần import các gói và thư viện cần thiết. Dưới đây là một ví dụ:

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)
}

Đoạn mã này khởi tạo Go Migrate với nguồn và cơ sở dữ liệu cụ thể, sau đó áp dụng 2 bước di chuyển bằng phương thức Steps.

Nếu bạn muốn sử dụng một client cơ sở dữ liệu hiện có, vui lòng xem ví dụ dưới đây:

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()
}

Đoạn mã này import các gói cần thiết và khởi tạo client cơ sở dữ liệu với gói sql. Sau đó tạo một phiên bản Go Migrate mới sử dụng phương thức NewWithDatabaseInstance, chỉ định nguồn và driver cơ sở dữ liệu. Cuối cùng, áp dụng di chuyển bằng phương thức Up.

4. Các Driver Cơ Sở Dữ Liệu Được Hỗ Trợ

Go Migrate hỗ trợ nhiều driver cơ sở dữ liệu bao gồm:

  • 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. Nguồn Di Chuyển Được Hỗ Trợ

Go Migrate hỗ trợ nhiều nguồn di chuyển bao gồm:

  • Hệ thống Tệp: Đọc di chuyển từ hệ thống tệp cục bộ.
  • io/fs: Đọc di chuyển bằng gói io/fs của Go.
  • Go-Bindata: Đọc di chuyển từ dữ liệu nhúng nhị phân sử dụng gói jteeuwen/go-bindata.
  • pkger: Đọc di chuyển từ dữ liệu nhúng nhị phân sử dụng gói markbates/pkger.
  • GitHub: Đọc di chuyển từ kho lưu trữ GitHub từ xa.
  • GitHub Enterprise: Đọc di chuyển từ kho lưu trữ GitHub Enterprise từ xa.
  • Bitbucket: Đọc di chuyển từ kho lưu trữ Bitbucket từ xa.
  • Gitlab: Đọc di chuyển từ kho lưu trữ Gitlab từ xa.
  • AWS S3: Đọc di chuyển từ Amazon Web Services S3.
  • Google Cloud Storage: Đọc di chuyển từ Lưu trữ Google Cloud Platform.

Tùy thuộc vào yêu cầu dự án của bạn, bạn có thể lưu trữ các tệp di chuyển cơ sở dữ liệu trong các nguồn lưu trữ tệp được hỗ trợ đã được đề cập ở trên.

6. Tệp Di Chuyển

Các tệp di chuyển trong Go Migrate có định dạng tên tệp và nội dung cụ thể.

6.1 Định dạng Tên Tệp Di Chuyển

Mỗi di chuyển bao gồm một tệp di chuyển "up" và một tệp di chuyển "down" tương ứng. Tên tệp di chuyển phải tuân theo định dạng sau:

{phiên_bản}_{tiêu_đề}.up.{phần_mở_rộng}
{phiên_bản}_{tiêu_đề}.down.{phần_mở_rộng}

phiên_bản là một số duy nhất biểu thị thứ tự mà các di chuyển sẽ được áp dụng. tiêu_đề là mô tả tùy chọn của di chuyển. phần_mở_rộng phụ thuộc vào hệ thống cơ sở dữ liệu đang sử dụng (ví dụ, đối với các biến thể SQL, sử dụng .sql).

6.2 Định dạng Nội Dung Tệp Di Chuyển

Nội dung của các tệp di chuyển thay đổi tùy thuộc vào hệ thống cơ sở dữ liệu, thường thì nó liên quan trực tiếp đến việc viết SQL.

Ví dụ, dưới đây là hai tệp di chuyển:

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

Tệp di chuyển 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
);

Tệp di chuyển 000001_create_users_table.down.sql, tệp down chủ yếu được sử dụng để hoàn tác các hoạt động trước đó, thường là cho mục đích quay lại trạng thái trước.

DROP TABLE IF EXISTS users;

6.3 Khả năng hoàn nguyên của Di dời

Viết các di dời có thể hoàn nguyên được coi là thực hành tốt nhất. Điều này có nghĩa là các di dời lên và xuống phải có thể chạy đến bất kỳ phiên bản nào, hiệu quả để tạo lại và dọn dẹp trạng thái cơ sở dữ liệu.

Để đảm bảo tính hoàn nguyên, mỗi di dời nên có một tập tin di dời "lên" và "xuống" tương ứng. Tập tin di dời "lên" chứa các thao tác để áp dụng di dời, trong khi tập tin di dời "xuống" chứa các thao tác để hoàn nguyên di dời.

7. Sử dụng MySQL

Go Migrate cung cấp hỗ trợ cho cơ sở dữ liệu MySQL. Để kết nối với cơ sở dữ liệu MySQL, URL của cơ sở dữ liệu cần ở dạng sau:

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

URL có thể bao gồm các tham số truy vấn, như tên bảng di dời, tham số TLS, v.v. Để có danh sách đầy đủ các tham số truy vấn, vui lòng tham khảo tài liệu Go Migrate MySQL.

7.1 Tham số Truy vấn URL

  • x-migrations-table: Tên của bảng di dời.
  • x-no-lock: Đặt thành true để bỏ qua các câu lệnh GET_LOCK/RELEASE_LOCK. Hữu ích cho các phiên bản MySQL multi-master.
  • x-statement-timeout: Hủy bỏ bất kỳ câu lệnh nào vượt quá số mili giây cụ thể.
  • dbname: Tên cơ sở dữ liệu để kết nối.
  • user: Người dùng đăng nhập.
  • password: Mật khẩu của người dùng.
  • host: Máy chủ để kết nối.
  • port: Cổng để ràng buộc.
  • tls: Tham số kết nối mã hóa TLS/SSL.
  • x-tls-ca: Vị trí của tệp CA (Certificate Authority).
  • x-tls-cert: Vị trí của tệp chứng chỉ của máy khách.
  • x-tls-key: Vị trí của tệp khóa riêng.
  • x-tls-insecure-skip-verify: Có sử dụng SSL hay không.

7.2 Sử dụng với Các Khoản Thanh Toán Hiện Có

Nếu bạn dự định sử dụng Go Migrate với một khoản thanh toán MySQL hiện có, hãy đảm bảo sử dụng tham số multiStatements=true khi tạo khoản thanh toán. Dưới đây là một ví dụ:

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)
}

Mã này nhập các gói cần thiết, tạo một khoản thanh toán cơ sở dữ liệu MySQL và khởi tạo Go Migrate với trường hợp cơ sở dữ liệu. Sau đó, nó áp dụng hai di dời sử dụng phương thức Steps.