Database Migration

A. Ringkasan & Definition of Done

Sistem migration AlurKerja terdiri dari dua alat yang terpisah tugasnya:

Halaman ini fokus pada penggunaan kedua alat — terutama runner migrate — sampai cara pengecekan dan expected result yang sudah divalidasi lewat simulasi.

Model pelacakannya mengikuti migration Laravel: setiap file migration dicatat per nama, lalu dikelompokkan ke dalam release (padanan konsep batch di Laravel). Satu release = satu unit rollback.

Definition of Done (DoD) — migration dianggap selesai bila:

• make migrate selesai tanpa error dan menampilkan Selesai. N migration baru ter-apply (atau Nothing to migrate bila memang sudah sinkron).
• make migrate-status menampilkan seluruh migration dalam status [x] ter-apply, 0 menunggu.
• Jumlah objek (tabel/view/function) di database tujuan sesuai dengan yang diharapkan.

B. Prasyarat

Langkah 1–3 memastikan environment siap. Jangan lanjut sebelum semua terpenuhi.

1. Verifikasi klien psql terpasang

Aksi

psql --version

Expected output

psql (PostgreSQL) 14.x atau lebih baru.

Jika gagal: install paket klien PostgreSQL (postgresql-client di Debian/Ubuntu, brew install libpq di macOS).

2. Verifikasi akses ke database tujuan

Aksi

PGPASSWORD='<DB_PASS>' psql -X "host=<DB_HOST> port=<DB_PORT> user=<DB_USER> dbname=<DB_NAME>" -tAc 'SELECT 1'

Expected output

Angka 1 tercetak tanpa error.

Jika gagal: pastikan host/port benar, kredensial valid, dan (bila database di jaringan internal) VPN aktif.

3. Verifikasi folder migration tersedia

Aksi

ls migrations/*/*/ | head

Expected output

Terlihat folder per schema dan per release, mis. migrations/public/2026.07.3.1/ berisi file *.up.sql dan *.down.sql.

Jika kosong: file migration belum di-generate. Jalankan make schema-diff lebih dulu (lihat halaman schema-diff).

C. Konsep: struktur folder & tabel pelacak

Struktur folder

File migration ditata per schema, lalu per release:

migrations/
  public/
    2026.01.1.1/    baseline  — dari config/public.sql (1 file)
    2026.07.3.1/    release   — selisih baseline vs server (31 file per konteks)
  camunda/
    2026.01.1.1/    baseline  — dari config/camunda.sql
    2026.07.3.1/    release   — hanya tabel act_* + trigger (3 file)

Setiap migration punya pasangan *.up.sql (maju) dan *.down.sql (rollback). Nama file berprefix timestamp 14 digit, mis. 20260716090100_create_access_logs.up.sql.

Tabel pelacak migrate.migrations

Runner mencatat migration yang sudah diterapkan di tabel berikut, dibuat otomatis di schema terpisah migrate (bukan public):

CREATE TABLE migrate.migrations (
    id          bigserial   PRIMARY KEY,
    schema_name text        NOT NULL,   -- 'public' | 'camunda'
    migration   text        NOT NULL,   -- '20260716090100_create_access_logs'
    release     text        NOT NULL,   -- '2026.07.3.1'  ← "batch" ala Laravel
    applied_at  timestamptz NOT NULL DEFAULT now(),
    UNIQUE (schema_name, migration)
);

Tiga aturan yang wajib dipegang

1. Pelacakan berbasis (schema, migration). Timestamp restart di tiap schema (public dan camunda bisa punya 20260716090000 yang sama), jadi nama migration hanya unik di dalam satu schema. Runner sudah menangani ini; jangan pernah menggabung (flatten) kedua schema ke satu folder.
2. Urutan schema: public dulu, baru camunda. camunda memiliki foreign key ke public (mis. camunda.tenant_certificates → public.tenants). Runner menerapkannya dalam urutan ini; rollback memakai urutan terbalik.
3. Release yang sudah deploy = beku. Jangan pernah regenerate release yang sudah diterapkan di server. Perubahan berikutnya masuk ke release baru (make schema-diff otomatis menaikkan nomor release).

D. Konfigurasi koneksi

Runner membaca koneksi dari scripts/migrate.env (di-gitignore, tidak ikut ter-commit).

4. Siapkan scripts/migrate.env

Aksi

cp scripts/migrate.env.example scripts/migrate.env
# lalu edit isinya

Isi minimal:

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASS=<password>
DB_NAME=<nama-database>

# Urutan schema WAJIB benar: public dulu (camunda punya FK ke public).
SCHEMAS=public camunda

E. Perintah yang tersedia

Sifat penting runner:

• Idempoten — migration yang sudah tercatat otomatis dilewati; up aman dijalankan berulang.
• Atomik per file — tiap *.up.sql diterapkan dengan psql --single-transaction digabung dengan pencatatannya dalam satu transaksi. Bila gagal di tengah, seluruhnya di-rollback dan tidak tercatat, sehingga cukup dijalankan ulang setelah masalah diperbaiki.
• Terkunci — dua proses up/rollback tidak bisa jalan bersamaan di database yang sama (lock berbasis baris, dengan pembersihan lock basi otomatis).

F. Simulasi end-to-end & expected result

Berikut simulasi lengkap yang sudah divalidasi pada Postgres lokal (container some-postgres, PostgreSQL 18 dengan pgvector) menggunakan database uji alur_migrate_test. Ikuti untuk memastikan sistem berfungsi sebelum dipakai ke database sungguhan.

5. Siapkan database uji kosong lalu apply (up)

Aksi

# 5a. buat database uji kosong
PGPASSWORD='<DB_PASS>' psql -X "host=<DB_HOST> port=<DB_PORT> user=<DB_USER> dbname=postgres" \
  -c "DROP DATABASE IF EXISTS alur_migrate_test WITH (FORCE)" \
  -c "CREATE DATABASE alur_migrate_test"

# 5b. buang schema public bawaan — baseline public menjalankan CREATE SCHEMA public
PGPASSWORD='<DB_PASS>' psql -X "host=<DB_HOST> port=<DB_PORT> user=<DB_USER> dbname=alur_migrate_test" \
  -c "DROP SCHEMA IF EXISTS public CASCADE"

# 5c. terapkan seluruh migration
DB_NAME=alur_migrate_test ./scripts/migrate.sh up

Expected output

Runner menerapkan seluruh migration berurutan — public dulu (baseline + release), baru camunda:

==> migrate up  (postgres@localhost:5432/alur_migrate_test)
  public   2026.01.1.1  20260101000000_baseline_public_schema ... OK
  public   2026.07.3.1  20260716090000_enable_extensions_and_types ... OK
  public   2026.07.3.1  20260716090100_create_access_logs ... OK
  ... (31 migration release public) ...
  camunda  2026.01.1.1  20260101000000_baseline_camunda_schema ... OK
  camunda  2026.07.3.1  20260716090000_add_constraints_and_indexes_to_existing_tables ... OK
  camunda  2026.07.3.1  20260716090100_create_functions_views_triggers ... OK
  camunda  2026.07.3.1  20260716090200_review_manual ... OK
  Selesai. 36 migration baru ter-apply.

Yang harus benar: total 36 migration ter-apply — 32 public (1 baseline + 31 release) dan 4 camunda (1 baseline + 3 release).

Jika gagal di tengah: migration yang gagal di-rollback (transaksi tunggal) dan tidak tercatat. Perbaiki penyebabnya, lalu jalankan ./scripts/migrate.sh up — yang sudah sukses tidak diulang.

6. Uji idempotensi (up kedua kali)

Aksi

DB_NAME=alur_migrate_test ./scripts/migrate.sh up

Expected output

==> migrate up  (postgres@localhost:5432/alur_migrate_test)
  Nothing to migrate. Semua sudah ter-apply.

Menjalankan up berkali-kali aman dan tidak mengubah apa pun bila skema sudah sinkron.

7. Periksa status

Aksi

DB_NAME=alur_migrate_test ./scripts/migrate.sh status

Expected output (dipersingkat)

==> status  (alur_migrate_test)

  public/2026.01.1.1
    [x] 20260101000000_baseline_public_schema

  public/2026.07.3.1
    [x] 20260716090000_enable_extensions_and_types
    [x] 20260716090100_create_access_logs
    ...

  camunda/2026.07.3.1
    [x] 20260716090100_create_functions_views_triggers
    [x] 20260716090200_review_manual

  36 ter-apply, 0 menunggu.

Yang harus benar: 36 ter-apply, 0 menunggu — semua migration bertanda [x].

G. Cara pengecekan (verifikasi hasil)

Selain status, verifikasi langsung ke database bahwa objek benar-benar terbentuk.

8. Hitung objek per schema

Aksi

PGPASSWORD='<DB_PASS>' psql -X "host=<DB_HOST> port=<DB_PORT> user=<DB_USER> dbname=alur_migrate_test" -c "
  SELECT n.nspname AS schema,
         count(*) FILTER (WHERE c.relkind='r') AS tabel
  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
  WHERE n.nspname IN ('public','camunda')
  GROUP BY n.nspname ORDER BY 1;"

Expected output

 schema  | tabel
---------+-------
 camunda |    49
 public  |   109

Yang harus benar: public 109 tabel, camunda 49 tabel (persis 49 tabel act_* Camunda).

9. Periksa isi tabel pelacak per release

Aksi

PGPASSWORD='<DB_PASS>' psql -X "host=<DB_HOST> port=<DB_PORT> user=<DB_USER> dbname=alur_migrate_test" -c "
  SELECT schema_name, release, count(*)
  FROM migrate.migrations GROUP BY 1,2 ORDER BY 1,2;"

Expected output

 schema_name |   release   | count
-------------+-------------+-------
 camunda     | 2026.01.1.1 |     1
 camunda     | 2026.07.3.1 |     3
 public      | 2026.01.1.1 |     1
 public      | 2026.07.3.1 |    31

H. Rollback

10. Mundurkan release terakhir

Aksi

DB_NAME=alur_migrate_test ./scripts/migrate.sh rollback

Expected output (dipersingkat)

==> rollback  release 2026.07.3.1  (alur_migrate_test)
  camunda  20260716090200_review_manual ... OK
  camunda  20260716090100_create_functions_views_triggers ... OK
  camunda  20260716090000_add_constraints_and_indexes_to_existing_tables ... OK
  public   20260716093000_review_manual ... OK
  ... (release public, urutan mundur) ...
  public   20260716090000_enable_extensions_and_types ... OK
  Selesai. 34 migration di release 2026.07.3.1 di-rollback.

Yang harus benar:

• 34 migration release 2026.07.3.1 di-rollback (31 public + 3 camunda) — urutan terbalik: camunda dulu, lalu public dari timestamp terbesar ke terkecil.
• Setelah rollback, status menunjukkan 2 ter-apply, 34 menunggu (hanya dua baseline yang tersisa).
• Hitung objek kembali ke kondisi baseline: public 60 tabel (turun dari 109), camunda 49 (release camunda hanya menambah constraint/trigger, bukan tabel, sehingga jumlah tabel tidak berubah).

I. Troubleshooting

J. Catatan untuk database produksi

Untuk server on-premise yang sudah berisi skema (sudah pada kondisi baseline), file baseline tidak boleh diterapkan ulang — cukup terapkan release baru saja. Alur amannya:

1. Tandai baseline sebagai sudah-applied di tabel migrate.migrations tanpa menjalankan SQL-nya (agar up hanya menerapkan release di atas baseline).
2. Jalankan make migrate-status untuk memastikan hanya release baru yang berstatus menunggu.
3. Jalankan make migrate.