Mengelola Database Migration di Project Golang

sandidharma.ac.id – Halo-halo! Beberapa waktu yang Lampau bekerja dengan project golang yang menggunakan golang-migrate Demi mengelola database migration. Seperti pada umumnya, project ini dikerjakan oleh beberapa developer dengan pembagian tugas yang sudah diatur. Development experience Tetap terasa menyenangkan hingga tiba Ketika dimana terjadi kekacauan pada database migration yang kami buat. Apabila dituliskan, kira-kira kasusnya seperti ini:

Developer A Membangun migrasi Demi Membangun tabel users
Developer B Membangun migrasi Demi mengedit tabel roles
Developer A dan B open merge request
Merge request dari developer B diterima, migrasi dijalankan
Masalah: Merge request dari developer A diterima, migrasi dijalankan tapi Tak tereksekusi karena secara history, migrasi dari developer B lebih terbaru dan golang-migrate menganggap Tak Terdapat migrasi Tengah yang perlu dijalankan.

Dari pengalaman itu, saya jadi merindukan kemudahan migrasi database yang dimiliki oleh Laravel, hahaha.

Singkatnya, pengalaman itu menghasilkan sebuah ide Demi Membangun database migration tool versi saya sendiri yang menyimpan Seluruh history migrasi seperti yang dilakukan Laravel, dan jadilah Qafoia.

Apa itu Qafoia?

Qafoia adalah sebuah package opensource yang dapat kita gunakan Demi mengelola migrasi database di project golang. Fitur-fitur yang ditawarkan antara lain sebagai berikut:

Registrasikan migrasi menggunakan go struct, tulis sql script di dalamnya.
Jalankan migrasi, rollback, refresh, reset dengan mudah.
Debug SQL script Ketika migrasi dijalankan.
Mekanis generate template go struct Demi menulis migrasi.
Track history migrasi pada tabel Tertentu yang dapat disesuaikan namanya.
Ketika ini tersedia MySQL dan Postgres driver yang siap digunakan
Dapat dengan mudah Membangun driver versi Anda sendiri.

Penggunaan

Qafoia dirancang agar mudah Demi digunakan tanpa konfigurasi yang terlalu rumit. Anda dapat mengikuti langkah-langkah berikut.

Install Qafoia

go get -u github.com/ruangdeveloper/qafoia

Inisialisasi Driver

Pada Teladan ini kita menggunakan MySqlDriver yang sudah disediakan.

driver, err := qafoia.NewMySqlDriver(
    "localhost",
    "3306",
    "db username",
    "db password",
    "db name",
    "utf8mb4"
)

Inisialisasi Qafoia

qafoia, err := qafoia.New(&qafoia.Config{
    Driver              : driver, // driver yang sudah diinisialisasi
    MigrationFilesDir   : "migrations", // default migrations
    MigrationTableName  : "migrations", // default migrations
})

Registrasi Migrasi

err := qafoia.Register(
  // nanti migration file kita registrasi ke sini
)

Setelah Seluruh diinisialisasi, kita dapat melakukan beberapa operasi dasar migrasi seperti berikut:

READ Ketahui 7 Metode Mengatasi Error 403 Forbidden pada Website

List Migration

list, err := q.List(context.Background())

if err != nil {
    log.Fatal(err)
}

list.Print()

Teladan output:

+-----------------------------------+-------------+-------------+
| Migration Name                    | Is Executed | Executed At |
+-----------------------------------+-------------+-------------+
| 20250427064746_create_users_table | false       | N/A         |
+-----------------------------------+-------------+-------------+

Output akan menyesuaikan dengan migrasi yang kita registrasikan.

Create Migration

err = q.Create("create_users_table")

if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 06:47:46 migration file created: migrations/20250427064746_create_users_table.go

Migration file akan disimpan pada direktori yang sudah diatur ketika inisialisasi Qafoia.

Teladan migration file yang dibuat:

package migrations

type M20250427064746CreateUsersTable struct{}

func (m *M20250427064746CreateUsersTable) Name() string {
	// Don't change this name
	return "20250427064746_create_users_table"
}

func (m *M20250427064746CreateUsersTable) UpScript() string {
	// Write your migration SQL here
	return ""
}

func (m *M20250427064746CreateUsersTable) DownScript() string {
	// Write your rollback SQL here
	return ""
}

Kita Bisa menuliskan script SQL Demi migrasi dalam fungsi UpScript() dan menuliskan script SQL Demi rollback dalam fungsi DownScript().

Setelah file migrasi dan script SQL dibuat, kita Bisa meregistrasikannya seperti berikut:

err := qafoia.Register(
  &migrations.M20250427064746CreateUsersTable{},
)

Run Migration

Demi menjalankan migrasi, kita Bisa menggunakan fungsi Migrate()

err = q.Migrate(context.Background())

if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 06:56:44 🚀 Applying 1 migration(s)...
2025/04/27 06:56:44 📦 Migrating: 20250427064746_create_users_table
2025/04/27 06:56:44 ✅ Migrated: 20250427064746_create_users_table

Cek ke tabel migrations di database

name                             |executed_at            |
---------------------------------+-----------------------+
20250427064746_create_users_table|2025-04-27 06:56:44.000|

Rollback Migration

Demi melakukan rollback, kita Bisa menggunakan fungsi Rollback(). Fungsi ini menerima parameter step yang dapat kita gunakan Demi menentukan akan rollback Tamat berapa migrasi.

err = c.qafoia.Rollback(context.Background(), 1)
if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 07:02:15 🔁 Rolling back 1 migration(s)...
2025/04/27 07:02:15 🔄 Rolling back: 20250427064746_create_users_table
2025/04/27 07:02:15 ✅ Rolled back: 20250427064746_create_users_table

Fresh Migration

Fresh migration akan menghapus Seluruh tabel dalam database Lampau menjalankan Seluruh migrasi dari awal. Demi melakukan fresh migration, kita Bisa menggunakan fungsi Fresh().

err = c.qafoia.Fresh(context.Background())
if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 07:06:33 🧹 Cleaning database...
2025/04/27 07:06:33 🚀 Running fresh migrations...
2025/04/27 07:06:33 🚀 Applying 1 migration(s)...
2025/04/27 07:06:33 📦 Migrating: 20250427064746_create_users_table
2025/04/27 07:06:33 ✅ Migrated: 20250427064746_create_users_table
2025/04/27 07:06:33 ✅ Fresh migration completed successfully

Reset Migration

Reset migration akan menjalankan rollback Seluruh migrasi yang sudah dieksekusi kemudian menjalankan migrasi ulang. Demi melakukan reset migration, kita Bisa menggunakan fungsi Reset().

err = c.qafoia.Reset(context.Background())
if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 07:09:01 🔁 Resetting 1 executed migration(s)...
2025/04/27 07:09:01 🔁 Rolling back 1 migration(s)...
2025/04/27 07:09:01 🔄 Rolling back: 20250427064746_create_users_table
2025/04/27 07:09:01 ✅ Rolled back: 20250427064746_create_users_table
2025/04/27 07:09:01 🚀 Applying 1 migration(s)...
2025/04/27 07:09:01 📦 Migrating: 20250427064746_create_users_table
2025/04/27 07:09:01 ✅ Migrated: 20250427064746_create_users_table
2025/04/27 07:09:01 ✅ Migration reset completed successfully

Clean Migration

Clean akan menghapus Seluruh tabel yang Terdapat di database. Demi melakukan clean migration, kita Bisa menggunakan fungsi Clean().

err = c.qafoia.Clean(context.Background())
if err != nil {
    log.Fatal(err)
}

Teladan output:

2025/04/27 07:10:31 🧹 Cleaning database...
2025/04/27 07:10:31 ✅ Database cleaned successfully

CLI Helper

Qafoia dirancang agar kita Bisa menggunakan Langkah kita sendiri dalam mengeksekusi operasi migrasi. Tetapi Apabila kita Ingin Langkah yang Segera, kita Bisa memanfaatkan CLI helper yang sudah disediakan. Dengan menggunakan cli helper, kita Bisa menjalankan migrasi melalui command line. Beberapa perintah yang tersedia sebagai berikut:

clean – Clean database (delete all tables)
create – Create a new migration
help – Help about any command
list – List all migrations
migrate – Run all pending migrations (use –fresh flag for fresh migration)
reset – Rollback all migrations and re-run all migrations
rollback – Rollback the last migration (use –step flag for setting rollback step)

READ Fitur Terbaru Laravel 10.33 - Blog Sandi Dharma

Demi menggunakan CLI helper, cukup tambahkan kode berikut:

cli, err := qafoia.NewCli(qafoia.CliConfig{
    Qafoia: qafoia, // Qafoia yang sudah diinisialisasi
})

if err != nil {
    log.Fatal(err)
}

err = cli.Execute(context.Background())

if err != nil {
    log.Fatal(err)
}

Setelah inisialisasi CLI, kita Bisa menjalankan perintah seperti berikut:

Menjalankan migrasi

Atau dengan fresh

go run main.go migrate --fresh

Membangun file migrasi

go run main.go create "Create Users Table"

Menampilkan list migrasi

Rollback migrasi

Atau dengan menentukan step

go run main.go rollback --step 2

Reset migrasi

Clean database

Teladan File Akhir

File: main.go

package main

import (
    "context"
    "log"
    "test_qafoia_published/migrations"

    "github.com/ruangdeveloper/qafoia"
)

func main() {
    d, err := qafoia.NewMySqlDriver(
        "localhost",
        "3306",
        "db user",
        "db pass",
        "db name",
        "utf8mb4",
    )

    if err != nil {
        log.Fatal(err)
    }

    q, err := qafoia.New(&qafoia.Config{
        Driver:             d,
        MigrationFilesDir:  "migrations",
        MigrationTableName: "migrations",
    })

    if err != nil {
        log.Fatal(err)
    }

    err = q.Register(
        &migrations.M20250427064746CreateUsersTable{},
    )

    if err != nil {
        log.Fatal(err)
    }

    cli, err := qafoia.NewCli(qafoia.CliConfig{
	      Qafoia: q,
    })

    if err != nil {
        log.Fatal(err)
    }

    err = cli.Execute(context.Background())

    if err != nil {
        log.Fatal(err)
    }
}

Hasil

Dari pengalaman menggunakan golang-migrate di proyek Golang, saya menemukan tantangan ketika beberapa developer Membangun migrasi dalam waktu berdekatan. Karena golang-migrate hanya mencatat satu versi terakhir yang dijalankan, Tak Seluruh histori migrasi tersimpan.
Akibatnya, migrasi Bisa saling bertabrakan, urutan migrasi menjadi Tak konsisten, dan potensi error di database pun semakin besar.
Dari situ lahir ide Demi Membangun sebuah tool baru yang lebih terstruktur, seperti konsep migrasi di Laravel.

READ #36: Package dan Import - Belajar Golang Dari Dasar

Qafoia mengelola migrasi menggunakan struct, mencatat histori di tabel Tertentu, dan sudah mendukung MySQL serta Postgres. Seluruh operasi seperti migrate, rollback, fresh, reset, hingga clean database dapat dilakukan dengan perintah yang sederhana. Tersedia juga CLI helper Demi mempermudah penggunaan.

Karena ini adalah proyek open source, saya mengundang Kolega-Kolega developer yang tertarik Demi ikut berkontribusi, memberikan masukan, atau membantu mengembangkan Qafoia ke depannya. 🚀

Apa itu Qafoia?

Penggunaan

Install Qafoia

Inisialisasi Driver

Inisialisasi Qafoia

Registrasi Migrasi

List Migration

Create Migration

Run Migration

Rollback Migration

Fresh Migration

Reset Migration

Clean Migration

CLI Helper

Teladan File Akhir

Hasil

Useful Links

Subscribe Now