Jika rilis CodeIgniter 4 memicu error setelah migrasi database dijalankan, prioritas utama bukan langsung menjalankan rollback secara membabi buta, melainkan menghentikan dampak, memverifikasi jenis ketidakcocokan, lalu memilih rollback yang paling aman. Dalam banyak kasus, masalah terjadi karena versi aplikasi baru mengharapkan skema baru, sementara rollback aplikasi lama justru tidak kompatibel dengan skema yang sudah berubah.

Runbook ini dirancang untuk situasi produksi yang realistis: deployment selesai, migrasi sudah terlanjur jalan, lalu muncul error pada API, halaman web, job latar belakang, atau proses tulis data. Fokusnya adalah langkah demi langkah untuk deteksi gejala, verifikasi dampak, keputusan rollback aplikasi vs rollback skema, maintenance mode, health check, logging, observability dasar, dan tindakan pencegahan.

Prinsip dasar: jangan anggap rollback selalu berarti mundurkan database

Kesalahan yang paling sering adalah menganggap semua insiden pasca-migrasi harus diselesaikan dengan rollback migrasi database. Padahal, rollback skema adalah tindakan berisiko tinggi jika:

  • migrasi sudah mengubah atau menghapus data,
  • aplikasi baru sudah menulis data ke kolom atau tabel baru,
  • rollback tidak benar-benar reversible,
  • ada proses async seperti queue, cron, atau worker yang masih aktif.

Karena itu, urutan berpikir yang lebih aman biasanya seperti ini:

  1. Stabilisasi trafik dan tulis data.
  2. Verifikasi apakah aplikasi lama masih kompatibel dengan skema baru.
  3. Jika kompatibel, lakukan rollback aplikasi saja.
  4. Jika tidak kompatibel, evaluasi apakah perlu rollback skema atau justru hotfix forward.

Catatan: rollback aplikasi sering lebih aman dibanding rollback skema, asalkan migrasi dibuat backward-compatible. Karena itu, desain migrasi sangat menentukan kemudahan recovery saat insiden.

Gejala umum saat migrasi CodeIgniter 4 menyebabkan error

Pada deployment CodeIgniter 4, error pasca-migrasi biasanya terlihat dari kombinasi log aplikasi, error database, dan penurunan health check.

Gejala yang perlu segera dikenali

  • HTTP 500 meningkat sesaat setelah deploy.
  • Query error seperti kolom tidak ditemukan, tabel tidak ditemukan, atau constraint gagal.
  • Endpoint health check gagal karena koneksi database tidak sehat.
  • Job background gagal karena struktur data berubah.
  • Write path error pada form, API create/update, checkout, atau proses transaksi.
  • Lonjakan log exception dari model, repository, atau service yang membaca kolom lama.

Contoh error yang relevan

DatabaseException: Unknown column 'status_code' in 'field list'
DatabaseException: Table 'app.orders_archive' doesn't exist
DatabaseException: Cannot add or update a child row: a foreign key constraint fails

Error seperti di atas biasanya menandakan salah satu dari tiga hal:

  1. Aplikasi baru tidak cocok dengan skema lama karena migrasi gagal sebagian.
  2. Aplikasi lama tidak cocok dengan skema baru setelah rollback kode.
  3. Migrasi sukses secara teknis tetapi memutus kontrak data pada bagian aplikasi lain.

Struktur deployment sederhana yang memudahkan rollback

Runbook rollback akan jauh lebih aman jika struktur deployment dibuat konsisten sejak awal. Tidak perlu arsitektur kompleks; cukup pola rilis yang dapat dipindahkan dengan cepat.

Contoh struktur direktori

/var/www/myapp/
  current -> /var/www/myapp/releases/20260615-101500
  releases/
    20260615-094000/
    20260615-101500/
  shared/
    writable/
    .env

Pola ini membantu karena:

  • kode rilis lama masih tersedia,
  • rollback aplikasi dapat dilakukan dengan memindahkan symlink atau target rilis aktif,
  • direktori writable dan file konfigurasi seperti .env tetap terpisah dari rilis.

Urutan deployment sederhana

  1. Upload rilis baru ke direktori baru.
  2. Pasang dependency dan build aset jika perlu.
  3. Jalankan migrasi.
  4. Jalankan smoke test atau health check.
  5. Arahkan current ke rilis baru.

Jika urutan aktual Anda berbeda, dokumentasikan dengan jelas. Yang terpenting adalah tahu kapan migrasi dijalankan relatif terhadap perpindahan rilis aktif, karena ini memengaruhi strategi rollback.

Checklist sebelum rilis untuk mengurangi risiko rollback sulit

Sebelum masuk ke runbook insiden, berikut checklist minimum yang sebaiknya selalu dilakukan sebelum deployment yang mengandung migrasi.

  • Pastikan ada backup database atau snapshot yang tervalidasi.
  • Pastikan migrasi punya metode up() dan, jika memungkinkan, down() yang aman.
  • Identifikasi apakah migrasi bersifat destruktif: drop kolom, rename kolom, ubah tipe, hapus indeks, ubah constraint.
  • Pastikan aplikasi mendukung fase kompatibilitas sementara jika ada perubahan schema besar.
  • Siapkan perintah health check, lokasi log, dan indikator error utama.
  • Pastikan worker, cron, atau proses tulis data bisa dihentikan sementara.
  • Tentukan keputusan rollback oleh siapa dan kapan dilakukan.

Migrasi yang lebih aman: backward-compatible dulu

Untuk sistem yang aktif dipakai, lebih aman memakai pola migrasi bertahap:

  1. Tambah dulu kolom/tabel baru tanpa menghapus yang lama.
  2. Ubah aplikasi agar bisa membaca struktur lama dan baru.
  3. Lakukan backfill data bila diperlukan.
  4. Setelah stabil, baru hapus struktur lama di rilis berikutnya.

Contoh yang aman: tambahkan kolom status_code tanpa langsung menghapus status. Aplikasi dapat menulis keduanya sementara waktu. Dengan cara ini, rollback aplikasi lama masih mungkin tanpa perlu rollback skema.

Runbook rollback CodeIgniter 4 langkah demi langkah

1. Deteksi gejala dan konfirmasi insiden

Segera konfirmasi bahwa error memang berkorelasi dengan deployment terakhir. Jangan hanya mengandalkan satu indikator.

  • Cek timestamp deployment.
  • Cek lonjakan HTTP 5xx.
  • Cek log aplikasi dan log web server.
  • Cek error query database.
  • Cek endpoint kritis: login, create, update, checkout, callback, API utama.

Di CodeIgniter 4, log aplikasi biasanya disimpan di direktori writable/logs. Cari exception yang muncul tepat setelah deploy.

tail -n 200 writable/logs/log-*.log

2. Aktifkan mode stabilisasi

Jika error memengaruhi operasi tulis data, pertimbangkan maintenance mode operasional. Tujuannya bukan sekadar menampilkan halaman maintenance, tetapi membatasi kerusakan data saat diagnosis berjalan.

Bentuk stabilisasi yang umum:

  • nonaktifkan sementara endpoint write jika memungkinkan,
  • pause worker/cron yang menulis ke database,
  • batasi trafik ke admin atau endpoint batch,
  • jika perlu, tampilkan halaman maintenance sementara.

Implementasinya bergantung pada lingkungan deployment Anda. Yang penting, tim punya prosedur baku untuk menghentikan sumber write agar rollback tidak memperparah inkonsistensi data.

3. Verifikasi dampak: aplikasi, skema, atau data?

Langkah ini sangat penting untuk menentukan jenis rollback.

Tanyakan hal-hal berikut:

  • Apakah migrasi gagal total, gagal sebagian, atau sukses penuh?
  • Apakah error terjadi di semua request atau hanya fitur tertentu?
  • Apakah sudah ada data baru yang ditulis setelah migrasi?
  • Apakah aplikasi lama masih bisa berjalan dengan skema baru?
  • Apakah metode down() aman dijalankan?

4. Ambil keputusan: rollback aplikasi atau rollback skema?

Gunakan panduan keputusan berikut.

Kasus A: rollback aplikasi saja

Pilih ini jika:

  • migrasi hanya menambah kolom/tabel/indeks,
  • aplikasi lama tidak rusak dengan skema baru,
  • tidak ada perubahan destruktif pada database.

Ini biasanya opsi paling aman dan paling cepat.

Kasus B: rollback aplikasi dan rollback skema

Pilih ini jika:

  • aplikasi lama tidak kompatibel dengan skema baru,
  • migrasi menyebabkan kegagalan baca/tulis yang tidak bisa ditoleransi,
  • rollback skema benar-benar aman dan sudah diuji.

Perlu kehati-hatian tinggi jika ada data yang sudah terlanjur ditulis oleh versi baru.

Kasus C: jangan rollback skema, lakukan hotfix forward

Pilih ini jika:

  • rollback skema berisiko kehilangan data,
  • migrasi tidak mudah dibalik,
  • perubahan bisa diperbaiki dengan patch kecil pada aplikasi.

Dalam praktiknya, hotfix forward sering lebih aman daripada memaksa down() pada migrasi destruktif.

5. Eksekusi rollback aplikasi

Jika keputusan adalah rollback aplikasi, pastikan proses tulis yang sensitif sudah dihentikan atau dibatasi. Setelah itu, kembalikan rilis aktif ke versi sebelumnya.

# contoh konseptual, sesuaikan dengan mekanisme deployment Anda
ln -sfn /var/www/myapp/releases/20260615-094000 /var/www/myapp/current

Setelah perpindahan rilis:

  • reload proses PHP/web server bila diperlukan,
  • pastikan cache konfigurasi atau opcode tidak menahan kode lama,
  • jalankan health check dasar.

Rollback aplikasi tidak cukup jika versi lama menggunakan query yang sudah tidak valid terhadap skema baru. Karena itu health check harus dilakukan segera, bukan diasumsikan aman.

6. Eksekusi rollback migrasi CodeIgniter 4 bila benar-benar diperlukan

Jika Anda memutuskan rollback skema, pastikan dulu migrasi memiliki metode down() yang aman dan Anda memahami efeknya. Di CodeIgniter 4, rollback migrasi dilakukan lewat command line framework.

php spark migrate:rollback

Jika Anda mengelompokkan migrasi berdasarkan namespace atau modul, sesuaikan eksekusinya dengan struktur proyek Anda. Hindari menjalankan rollback berlapis tanpa tahu migrasi mana yang sedang dibatalkan.

Sebelum menjalankan rollback skema:

  • cek urutan migrasi terakhir yang diterapkan,
  • verifikasi tabel migrasi untuk memastikan status riwayat,
  • pastikan tidak ada proses aplikasi yang masih menulis ke struktur baru,
  • siapkan rencana recovery jika rollback berhenti di tengah jalan.

Contoh migrasi yang reversible

<?php

namespace App\Database\Migrations;

use CodeIgniter\Database\Migration;

class AddStatusCodeToOrders extends Migration
{
    public function up()
    {
        $this->forge->addColumn('orders', [
            'status_code' => [
                'type'       => 'VARCHAR',
                'constraint' => 32,
                'null'       => true,
            ],
        ]);
    }

    public function down()
    {
        $this->forge->dropColumn('orders', 'status_code');
    }
}

Migrasi seperti ini relatif aman untuk rollback karena hanya menambah kolom. Sebaliknya, migrasi yang menghapus kolom lama sering tidak aman dibalik jika data sudah berubah.

7. Jalankan pemeriksaan health check setelah rollback

Setelah rollback aplikasi atau skema, lakukan verifikasi minimum yang konsisten. Jangan langsung membuka trafik penuh tanpa validasi.

  • Health check aplikasi: endpoint utama merespons normal.
  • Koneksi database: query baca sederhana berhasil.
  • Flow tulis kritis: create/update pada fitur utama berjalan.
  • Worker/cron: tidak lagi menghasilkan exception berulang.
  • Error rate: menurun dibanding saat insiden.

Jika Anda memiliki endpoint health internal, pastikan health check mencakup lebih dari sekadar respons HTTP 200. Idealnya endpoint juga memverifikasi koneksi database dan dependency penting secara ringan.

Logging dan observability dasar yang wajib dipantau

Saat insiden rollback migrasi, observability yang cukup sering lebih penting daripada dashboard yang rumit. Tiga sinyal dasar sudah sangat membantu:

1. Log aplikasi

  • exception stack trace,
  • query error,
  • warning pada model atau service yang gagal memetakan field.

2. Metrik operasional minimum

  • jumlah request per menit,
  • rasio HTTP 5xx,
  • latensi endpoint kritis,
  • jumlah job gagal,
  • jumlah error database per menit.

3. Event deployment

Catat kapan deploy dimulai, kapan migrasi dijalankan, kapan rollback dilakukan, dan oleh siapa. Timeline ini sangat membantu untuk postmortem.

Tip debugging: jika error hanya muncul pada sebagian node atau proses, periksa apakah semua instance aplikasi sudah memakai rilis yang sama dan apakah worker lama masih berjalan dengan kode yang berbeda.

Contoh checklist insiden singkat

Checklist berikut bisa dipakai tim on-call atau engineer yang menangani rilis bermasalah.

  1. Konfirmasi waktu mulai error dan korelasi dengan deployment.
  2. Periksa log di writable/logs dan error database.
  3. Identifikasi apakah fitur baca, tulis, atau keduanya terdampak.
  4. Pause worker/cron atau endpoint write yang berisiko.
  5. Tentukan apakah aplikasi lama kompatibel dengan skema baru.
  6. Jika ya, rollback aplikasi.
  7. Jika tidak, evaluasi rollback migrasi atau hotfix forward.
  8. Jalankan health check dan smoke test setelah tindakan.
  9. Buka trafik bertahap setelah indikator stabil.
  10. Dokumentasikan timeline dan keputusan.

Stabilisasi setelah rollback

Rollback yang berhasil belum berarti insiden selesai. Masih ada fase stabilisasi agar masalah tidak berulang beberapa menit kemudian.

Langkah stabilisasi yang disarankan

  • Pastikan semua instance aplikasi sudah berada pada versi yang sama.
  • Aktifkan kembali worker/cron secara bertahap.
  • Pantau error rate, log database, dan health check setidaknya selama beberapa siklus trafik normal.
  • Periksa data yang ditulis saat jendela insiden untuk mendeteksi inkonsistensi.
  • Jika ada retry otomatis, pastikan tidak memicu gelombang error baru.

Pemeriksaan data pasca-insiden

Beberapa insiden migrasi tidak hanya menyebabkan aplikasi error, tetapi juga meninggalkan data setengah jadi. Contohnya:

  • record tercipta tanpa field turunan yang diharapkan,
  • foreign key gagal sehingga relasi tidak lengkap,
  • kolom baru kosong pada sebagian data hasil write saat deployment.

Karena itu, siapkan query audit sederhana atau skrip verifikasi data untuk memeriksa integritas dasar setelah rollback.

Strategi migrasi backward-compatible untuk mencegah rollback sulit

Kalau tujuan Anda adalah membuat runbook rollback CodeIgniter 4 lebih aman, pencegahan terbaik ada di desain migrasinya.

Pola expand and contract

Gunakan pendekatan bertahap:

  1. Expand: tambahkan struktur baru tanpa memutus yang lama.
  2. Migrate: ubah aplikasi agar mendukung dua bentuk data sementara.
  3. Backfill: pindahkan atau salin data lama ke struktur baru.
  4. Contract: hapus struktur lama hanya setelah semua konsumen aman.

Kelebihannya adalah rollback aplikasi lama tetap mungkin selama fase transisi. Kekurangannya, kode menjadi sedikit lebih kompleks untuk sementara waktu karena harus menangani dua jalur kompatibilitas.

Hindari perubahan destruktif dalam satu rilis yang sama

Perubahan berikut sebaiknya tidak digabung sekaligus jika sistem Anda sensitif terhadap downtime:

  • rename kolom dan ubah semua query di rilis yang sama,
  • drop kolom lama segera setelah kolom baru dibuat,
  • ubah tipe data yang memengaruhi parsing atau validasi aplikasi,
  • tambahkan constraint ketat tanpa membersihkan data lama lebih dulu.

Contoh postmortem ringan setelah rollback

Postmortem tidak harus panjang. Yang penting cukup untuk mencegah kejadian berulang.

Format sederhana

  • Apa yang berubah: migrasi menambah kolom baru dan menghapus kolom lama pada tabel transaksi.
  • Dampak: endpoint create transaksi gagal selama 12 menit.
  • Akar masalah: aplikasi lama tidak kompatibel saat rollback kode karena kolom lama sudah dihapus.
  • Kenapa lolos: tidak ada uji kompatibilitas rollback, health check hanya memeriksa HTTP 200.
  • Pemulihan: worker dihentikan, aplikasi dikembalikan, lalu hotfix forward diterapkan.
  • Tindakan pencegahan: adopsi migrasi bertahap, tambahkan smoke test write path, dokumentasikan keputusan rollback.

Tindakan pencegahan yang paling efektif

Untuk menutup runbook ini, berikut langkah pencegahan yang paling bernilai:

  1. Desain migrasi agar backward-compatible bila memungkinkan.
  2. Jangan gabungkan perubahan skema destruktif dan perubahan kode besar dalam satu langkah.
  3. Uji skenario rollback aplikasi terhadap skema hasil migrasi.
  4. Pastikan metode down() hanya dipakai jika benar-benar aman dan tervalidasi.
  5. Siapkan maintenance mode operasional, bukan hanya halaman maintenance.
  6. Tambahkan health check yang memverifikasi database dan flow kritis.
  7. Catat event deployment, migrasi, rollback, dan error utama dalam satu timeline.

Intinya, saat deployment CodeIgniter 4 gagal karena migrasi database, fokuslah pada menghentikan dampak, memilih rollback yang paling aman, dan memverifikasi sistem secara menyeluruh setelah pemulihan. Rollback yang baik bukan sekadar perintah CLI, tetapi kombinasi desain migrasi yang hati-hati, observability yang cukup, dan prosedur operasional yang jelas.