Migrasi skema

Migrasi bukan sekadar cara membuat tabel. Ia adalah kontrak antara versi lama dan versi baru aplikasimu yang selama rolling update berjalan bersamaan.

Bentuk berkasnya

migrations/
├── 000001_buat_produk.up.sql
├── 000001_buat_produk.down.sql
├── 000002_tambah_index_nama.up.sql
├── 000002_tambah_index_nama.down.sql
├── 000003_tambah_kolom_slug.up.sql
└── 000003_tambah_kolom_slug.down.sql

-- 000001_buat_produk.up.sql
CREATE TABLE produk (
    id           bigserial PRIMARY KEY,
    nama         text        NOT NULL,
    harga        bigint      NOT NULL CHECK (harga >= 0),
    dibuat       timestamptz NOT NULL DEFAULT now(),
    dihapus_pada timestamptz
);

-- 000001_buat_produk.down.sql
DROP TABLE produk;

migrate -path migrations -database "$DATABASE_URL" up
migrate -path migrations -database "$DATABASE_URL" down 1
migrate -path migrations -database "$DATABASE_URL" version
migrate -path migrations -database "$DATABASE_URL" force 3   # setelah gagal

Menyematkan migrasi ke dalam binari

//go:embed migrations/*.sql
var migrasiFS embed.FS

func Migrasi(dsn string) error {
	src, err := iofs.New(migrasiFS, "migrations")
	if err != nil {
		return err
	}
	m, err := migrate.NewWithSourceInstance("iofs", src, dsn)
	if err != nil {
		return err
	}
	defer m.Close()

	if err := m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
		return fmt.Errorf("migrasi: %w", err)
	}
	return nil
}

Di mana migrasi dijalankan

Kompatibel dua arah

Selama rolling update:

  waktu →
  v1 v1 v1 v1        ← semua lama
  v1 v1 v1 v2        ← BERCAMPUR: v1 dan v2 memakai SKEMA YANG SAMA
  v1 v1 v2 v2
  v2 v2 v2 v2        ← semua baru

Karena baris tengah itu ada — selama beberapa menit di setiap deploy — skema harus bisa dipakai oleh kedua versi kode sekaligus.

Ganti nama kolom dalam tiga deploy

Deploy 1  migrasi: ALTER TABLE produk ADD COLUMN judul text;
          kode   : TULIS ke nama DAN judul; BACA dari nama

Deploy 2  migrasi: UPDATE produk SET judul = nama WHERE judul IS NULL;
          kode   : TULIS ke keduanya; BACA dari judul

Deploy 3  migrasi: ALTER TABLE produk DROP COLUMN nama;
          kode   : hanya judul

Terasa berlebihan sampai kamu pernah mengalami deploy yang gagal di tengah dan harus mengembalikan versi lama — dengan skema yang sudah tidak mendukungnya lagi. Ini juga alasan rollback tidak boleh mengandalkan down.sql: mengembalikan kode itu murah, mengembalikan skema yang sudah kehilangan data itu mustahil.

Migrasi pada tabel besar

-- ❌ mengunci seluruh tabel; di 50 juta baris bisa berjam-jam
CREATE INDEX idx_produk_nama ON produk (nama);

-- ✅ tidak mengunci tulisan. TIDAK BOLEH di dalam transaksi —
--    beri tahu golang-migrate lewat komentar berikut.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_produk_nama ON produk (nama);

-- 000004_index_nama.up.sql
-- migrate:no-transaction
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_produk_nama ON produk (nama);