Panduan Migrasi Go

1. Gambaran Migrasi Go

Go Migrate adalah alat untuk mengelola migrasi database yang ditulis dalam bahasa Go. Ini dapat digunakan sebagai antarmuka baris perintah (CLI) atau diimpor sebagai pustaka untuk proyek Go. Go Migrate dapat membaca file migrasi dari berbagai sumber dan menerapkannya ke database dalam urutan yang benar. Ini mendukung berbagai driver database dan sumber migrasi.

2. Versi

Go Migrate mendukung beberapa versi, termasuk:

Master: Versi terbaru, termasuk fitur-fitur baru dan perbaikan bug
v4: Versi stabil, cocok untuk lingkungan produksi
v3: Tidak lagi didukung dan sebaiknya tidak digunakan

3. Instalasi

Untuk menggunakan Go Migrate, Anda perlu menginstal paket Go. Jalankan perintah berikut untuk instalasi:

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

4. Menggunakan Go Migrate

Go Migrate dapat digunakan melalui CLI atau sebagai pustaka dalam proyek Go.

4.0. URL Koneksi Database

Baik menggunakan CLI atau kode Go, URL database perlu dikonfigurasi untuk terhubung ke database.

Format URL:

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

URL ini adalah URL koneksi database yang digunakan untuk menghubungkan ke database dan menentukan parameter koneksi. Berikut ini adalah penjelasan untuk setiap bagian:

dbdriver://: Ini adalah pengenal protokol untuk driver database yang digunakan untuk menentukan driver database yang digunakan, misalnya, mysql.
username:password: Ini adalah username dan password yang digunakan untuk otentikasi. Biasanya, username dan password dipisahkan oleh titik dua (:).
@: Simbol ini digunakan untuk memisahkan username dan password dari nama host dan port.
host:port: Ini adalah nama host dan nomor port dari server database. Nama host adalah alamat IP atau nama domain dari server database, dan nomor port adalah port yang didengarkan oleh server database.
/dbname: Ini adalah nama database yang akan dihubungkan.
?param1=true&param2=false: Bagian ini adalah parameter kueri yang digunakan untuk menentukan parameter koneksi tambahan. Dalam contoh ini, terdapat dua parameter.

Parameter kueri ini dapat diatur sesuai dengan kebutuhan spesifik dari driver database dan server database untuk mengkonfigurasi atribut atau perilaku koneksi tertentu.

Parameter Koneksi Postgres

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

Parameter Koneksi SQLite

sqlite3://path/to/database?query

Parameter Koneksi MongoDB

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

4.1 Penggunaan CLI

4.1.1 Penggunaan Dasar

Untuk menggunakan CLI, jalankan perintah berikut:

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

Perintah ini menerapkan migrasi dari sumber yang ditentukan ke database yang diberikan. Angka "2" menunjukkan jumlah migrasi yang akan diterapkan.

4.1.2 Penggunaan Docker

Go Migrate juga dapat digunakan dengan Docker. Jalankan perintah berikut:

docker run -v {{ migration dir }}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/database up 2

Perintah ini menjalankan Go Migrate dalam sebuah wadah Docker dan menerapkan migrasi dari sumber tertentu ke database yang diberikan.

3.2 Menggunakan dalam Proyek Go Anda

Untuk menggunakan Go Migrate dalam proyek Go Anda, Anda perlu mengimpor paket dan pustaka yang diperlukan. Berikut adalah contohnya:

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

Kode ini menginisialisasi Go Migrate dengan sumber dan database yang ditentukan, kemudian menerapkan 2 migrasi menggunakan metode Steps.

Jika Anda ingin menggunakan klien database yang sudah ada, silakan lihat contoh berikut:

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

Kode ini mengimpor paket yang diperlukan dan menginisialisasi klien database dengan paket sql. Kemudian membuat instansi Go Migrate baru dengan menggunakan metode NewWithDatabaseInstance, menentukan sumber dan driver database. Terakhir, menerapkan migrasi menggunakan metode Up.

4. Driver Database yang Didukung

Go Migrate mendukung beberapa driver database termasuk:

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. Sumber Migrasi yang Didukung

Go Migrate mendukung beberapa sumber migrasi termasuk:

Sistem File: Membaca migrasi dari sistem file lokal.
io/fs: Membaca migrasi menggunakan paket Go io/fs.
Go-Bindata: Membaca migrasi dari data biner tersemat menggunakan paket jteeuwen/go-bindata.
pkger: Membaca migrasi dari data biner tersemat menggunakan paket markbates/pkger.
GitHub: Membaca migrasi dari repositori GitHub jarak jauh.
GitHub Enterprise: Membaca migrasi dari repositori GitHub Enterprise jarak jauh.
Bitbucket: Membaca migrasi dari repositori Bitbucket jarak jauh.
Gitlab: Membaca migrasi dari repositori Gitlab jarak jauh.
AWS S3: Membaca migrasi dari Amazon Web Services S3.
Google Cloud Storage: Membaca migrasi dari Google Cloud Platform Storage.

Tergantung pada kebutuhan proyek Anda, Anda dapat menyimpan file migrasi database dalam sumber penyimpanan file yang didukung seperti yang disebutkan di atas.

6. File Migrasi

File migrasi dalam Go Migrate memiliki format nama file dan konten yang spesifik.

6.1 Format Nama File Migrasi

Setiap migrasi terdiri dari file migrasi "up" dan file migrasi "down" yang sesuai. Nama file migrasi harus sesuai dengan format berikut:

{versi}_{judul}.up.{ekstensi}
{versi}_{judul}.down.{ekstensi}

versi adalah nomor unik yang mewakili urutan di mana migrasi harus diterapkan. judul adalah deskripsi opsional dari migrasi. ekstensi bergantung pada sistem database yang digunakan (misalnya, untuk varian SQL, gunakan .sql).

6.2 Format Konten File Migrasi

Konten file migrasi bervariasi tergantung pada sistem database, biasanya melibatkan penulisan SQL secara langsung.

Sebagai contoh, berikut adalah dua file migrasi:

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

File migrasi 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
);

File migrasi 000001_create_users_table.down.sql, file "down" ini umumnya digunakan untuk membatalkan operasi sebelumnya, biasanya untuk tujuan rollback.

DROP TABLE IF EXISTS users;

6.3 Reversibilitas Migrasi

Menulis migrasi yang dapat dikembalikan adalah praktik terbaik. Ini berarti bahwa migrasi "up" dan "down" harus dapat dijalankan ke versi mana pun, secara efektif membuat ulang dan membersihkan status basis data.

Untuk memastikan reversibilitas, setiap migrasi harus memiliki file migrasi "up" dan "down" yang sesuai. File migrasi "up" berisi operasi untuk menerapkan migrasi, sedangkan file migrasi "down" berisi operasi untuk membatalkan migrasi.

7. Penggunaan MySQL

Go Migrate menyediakan dukungan untuk basis data MySQL. Untuk terhubung ke basis data MySQL, URL basis data harus berada dalam format berikut:

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

URL dapat mencakup parameter query, seperti nama tabel migrasi, parameter TLS, dll. Untuk daftar lengkap parameter query, silakan lihat dokumentasi Go Migrate MySQL.

7.1 Parameter Query URL

x-migrations-table: Nama tabel migrasi.
x-no-lock: Diatur ke true untuk melewati pernyataan GET_LOCK/RELEASE_LOCK. Berguna untuk versi MySQL multi-master.
x-statement-timeout: Membatalkan setiap pernyataan yang melebihi jumlah milidetik yang ditentukan.
dbname: Nama basis data yang akan dihubungkan.
user: Pengguna yang akan masuk.
password: Kata sandi pengguna.
host: Host yang akan dihubungkan.
port: Port yang akan diikat.
tls: Parameter koneksi enkripsi TLS/SSL.
x-tls-ca: Lokasi file CA (Certificate Authority).
x-tls-cert: Lokasi file sertifikat klien.
x-tls-key: Lokasi file kunci pribadi.
x-tls-insecure-skip-verify: Apakah akan menggunakan SSL.

7.2 Penggunaan dengan Klien Yang Ada

Jika Anda berniat untuk menggunakan Go Migrate dengan klien MySQL yang sudah ada, pastikan untuk menggunakan parameter multiStatements=true saat membuat klien. Berikut adalah contohnya:

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

Kode ini mengimpor paket-paket yang diperlukan, membuat klien basis data MySQL, dan menginisialisasi Go Migrate dengan instance basis data. Kemudian, ini menerapkan dua migrasi menggunakan metode Steps.

Manajemen Versi Database Go Migrate