Pola Expand/Contract untuk Migrasi Skema yang Aman

Deploy paling menakutkan yang saya jalankan bukanlah perubahan kode. Itu adalah perubahan skema pada tabel yang sedang dibaca dan ditulis oleh layanan live ribuan kali per detik. Ganti nama kolom dalam satu migrasi dan Anda punya jendela di mana aplikasi yang ter-deploy mengharapkan nama lama sementara database hanya punya yang baru, atau sebaliknya. Selama rolling deploy kedua versi aplikasi berjalan bersamaan, jadi tidak ada momen di mana rename yang merusak itu aman.

Solusinya adalah pola dengan beberapa nama: expand/contract, atau parallel change. Alih-alih satu perubahan atomik, Anda membuat skema menahan bentuk lama dan baru pada saat yang sama, bermigrasi melewatinya dalam langkah-langkah kecil yang kompatibel mundur, dan hanya menghapus bentuk lama setelah tidak ada lagi yang membacanya. Saya menggunakannya untuk setiap perubahan skema destruktif pada tabel yang penting.

Lima langkah, dan mengapa urutan penting

Seluruh pola ini adalah sebuah janji: tidak pernah ada titik di mana database dan aplikasi yang sedang ter-deploy berselisih tentang apa yang harus ada. Setiap langkah adalah commit sendiri dan deploy sendiri. Anda tidak pernah menggabungkan expand dengan contract dalam rilis yang sama. Berikut bentuknya, memakai contoh klasik: memecah satu kolom full_name menjadi first_name dan last_name.

Langkah 1: Expand tanpa mengunci tabel

Langkah expand harus murah. Pada PostgreSQL 11 ke atas, menambah kolom dengan default konstan adalah operasi metadata-only yang disimpan di katalog sistem dan diterapkan saat baca, jadi tidak lagi menulis ulang tabel. Sebelum versi 11, statement yang sama menulis ulang setiap baris di bawah lock ACCESS EXCLUSIVE, yang pada tabel besar berarti menit-menit lalu lintas terblokir. Bahkan di Postgres modern, default volatile seperti UUID acak tetap memaksa rewrite penuh, jadi tambahkan kolom sebagai nullable dan backfill terpisah.

-- Expand: cheap, metadata-only, no table rewrite.
-- Add columns as NULLABLE. Do NOT add NOT NULL yet --
-- an unpopulated NOT NULL column would reject every insert.
ALTER TABLE users ADD COLUMN first_name text;
ALTER TABLE users ADD COLUMN last_name  text;

Langkah 2: Backfill secara batch, bukan satu UPDATE besar

Satu UPDATE users SET ... di jutaan baris memakan satu transaksi panjang, menahan row lock sepanjang waktu, dan membengkakkan tabel dengan dead tuple yang lalu harus dikejar vacuum. Batch-kan. Update beberapa ribu baris per transaksi, commit, tidur sebentar, ulangi. Ini menjaga setiap lock tetap pendek, membiarkan autovacuum mengejar, dan berarti kegagalan hanya me-rollback batch saat ini alih-alih pekerjaan berjam-jam.

-- Backfill loop: run outside a single transaction.
-- Each batch commits on its own.
DO $$
DECLARE
  rows_updated integer;
BEGIN
  LOOP
    UPDATE users
    SET first_name = split_part(full_name, ' ', 1),
        last_name  = substr(full_name, length(split_part(full_name,' ',1)) + 2)
    WHERE first_name IS NULL
      AND id IN (
        SELECT id FROM users WHERE first_name IS NULL LIMIT 5000
      );
    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    EXIT WHEN rows_updated = 0;
    COMMIT;            -- procedural COMMIT, Postgres 11+
    PERFORM pg_sleep(0.1);
  END LOOP;
END $$;

Langkah 3 dan 4: Tulis ganda, lalu balik baca

Setelah backfill mencakup baris historis, Anda masih punya celah: baris yang ditulis antara backfill dan switch hanya akan mengisi kolom lama. Tulis ganda menutupnya. Deploy kode aplikasi yang menulis baik full_name lama maupun first_name/last_name baru pada setiap insert dan update. Kini kedua representasi tetap identik ke depan. Hanya setelah deploy itu ter-rollout penuh barulah Anda mengirim deploy berikutnya yang membaca dari kolom baru.

// Step 3 deploy: write BOTH shapes. Reads still use full_name.
await db.user.update({
  where: { id },
  data: {
    fullName:  `${firstName} ${lastName}`, // old, still authoritative
    firstName,                              // new, now kept in sync
    lastName,
  },
});

// Step 4 deploy (next release): reads switch to the new columns.
// Writes still populate both until the contract step lands.
const { firstName, lastName } = await db.user.findUniqueOrThrow({
  where: { id },
  select: { firstName: true, lastName: true },
});

Langkah 5: Kontraksi, dan tambah constraint dengan cara aman

Contract adalah cermin dari expand. Pertama deploy kode yang berhenti menulis kolom lama, pastikan tidak ada yang mereferensikannya, lalu hapus dalam migrasi terakhir. Di sinilah Anda juga menaikkan kolom baru menjadi NOT NULL bila domain mengharuskannya. Menambah NOT NULL langsung memindai seluruh tabel di bawah lock berat; sebaliknya tambahkan constraint CHECK ... NOT VALID, yang melewati pemindaian, lalu VALIDATE CONSTRAINT terpisah di bawah lock SHARE UPDATE EXCLUSIVE yang lebih ringan yang tidak memblokir baca dan tulis.

-- Enforce NOT NULL without a blocking full-table scan:
ALTER TABLE users
  ADD CONSTRAINT users_first_name_not_null
  CHECK (first_name IS NOT NULL) NOT VALID;   -- instant, no scan

ALTER TABLE users
  VALIDATE CONSTRAINT users_first_name_not_null; -- scans, but lighter lock

-- Finally, the contract itself:
ALTER TABLE users DROP COLUMN full_name;

Kapan repotnya sepadan

Lima deploy untuk satu rename kolom adalah overhead nyata, dan saya tidak memakainya di mana-mana. Pada tabel internal berlalu-lintas rendah saya ambil jendela pemeliharaan singkat dan rename sekali jalan. Expand/contract layak biayanya pada tabel yang besar, panas, dan berada di depan layanan yang tidak boleh mati. Daftar di bawah kira-kira cara saya memutuskan.

• Pakai saat: tabel cukup besar sehingga rewrite mengunci secara terasa, atau layanan punya target uptime ketat dan rolling deploy berarti dua versi aplikasi berjalan sekaligus.
• Lewati saat: tabel kecil atau internal, lalu lintas rendah, dan downtime pemeliharaan beberapa detik memang bisa diterima.
• Selalu: jaga setiap langkah dalam migrasinya sendiri dan deploy-nya sendiri, dan jangan pernah mencampur expand dan contract dalam satu rilis.
• Bonus: bentuk yang sama berlaku di luar kolom — memecah tabel, mengubah tipe, atau memindah foreign key semuanya mengikuti expand, migrate, switch, contract.

Model mental yang membuat semua ini masuk akal: deploy bukan satu hal atomik. Database Anda dan beberapa versi aplikasi Anda hidup berdampingan selama beberapa menit sekaligus. Expand/contract sekadar menolak membiarkan versi-versi yang berdampingan itu berselisih tentang skema. Begitu Anda menghayati itu, migrasi menakutkan berhenti menakutkan — ia menjadi checklist membosankan yang Anda jalankan dengan cara sama setiap kali.