Belajar pgBackRest - Troubleshooting & Debug

#Pendahuluan

Di episode 14 kita memasang alarm — sekarang saatnya mempelajari apa yang terjadi saat alarm berbunyi. pgBackRest adalah tool yang sangat komunikatif: ia menulis log detail ke file dan bisa menampilkan debug lengkap di console. Masalah sebenarnya bukan "error muncul", melainkan membaca error dengan cara yang benar — dan di episode 15 kita melatih itu dengan empat kasus paling umum di lapangan.

Pola pikir yang perlu dipegang: setiap error pgBackRest menyebutkan file dan proses yang terlibat. Debugging yang baik adalah mengikuti jejak itu, bukan menebak.

#Menaikkan Log Level

#Log di Console vs File

pgBackRest memiliki dua jalur log: console (stdout/stderr saat perintah dijalankan) dan file (di /var/log/pgbackrest/). Keduanya bisa diatur levelnya secara independen:

sudo -u postgres pgbackrest --stanza=main --log-level-console=debug backup --type=diff

sudo -u postgres pgbackrest --stanza=main --log-level-file=debug backup --type=diff

Level yang tersedia: off, error, warn, info, detail, debug, trace. Untuk troubleshooting, debug biasanya cukup; trace sangat verbose dan hanya untuk kasus ekstrem.

#Membaca Log di /var/log/pgbackrest/

Log file disimpan per proses dengan nama berisi timestamp dan PID:

ls -lt /var/log/pgbackrest/
sudo tail -50 /var/log/pgbackrest/pgbackrest-20260813-120000.log

Format baris log: level, process (P00 = master, P01+ = worker), dan pesan. Perhatikan pola berikut saat error:

• P00 ... ERROR: [046]: ... — error dengan kode; [046] dst. adalah kategori yang didokumentasikan di pgbackrest.org.
• P01 ... ERROR: ... while processing file ... — menunjukkan file spesifik yang gagal.
• Baris DETAIL dan HINT — penjelasan dan saran perbaikan.

#Kasus Umum 1: archive-push Gagal

#Gejala

WAL tidak pernah masuk repository; pg_stat_archiver.failed_count naik; check gagal di bagian archive-push.

#Diagnosa Terstruktur

sudo -u postgres pgbackrest --stanza=main --log-level-console=debug check
tail -30 /var/log/postgresql/*.log | grep -i archive

Error paling umum dan solusinya:

• archive_command salah path binary: pastikan pgbackrest ada di PATH user postgres, atau tulis path absolut.
• archive_command belum diaktifkan: archive_mode=on butuh restart (episode 6).
• Stanza belum dibuat: jalankan stanza-create dulu.

Jika error menyebutkan kode dan file WAL, tes archive-push manual dengan file uji:

sudo -u postgres pgbackrest --stanza=main archive-push /var/lib/postgresql/16/main/pg_wal/0000000100000000000000FF

#Kasus Umum 2: Permission Denied

#Gejala

permission denied muncul di log — biasanya saat backup pertama kali dijalankan sebagai user yang salah, atau setelah direktori dibuat ulang.

#Diagnosa

ls -ld /var/lib/pgbackrest /var/lib/pgbackrest/backup /var/log/pgbackrest
ls -ld /var/lib/postgresql/16/main

Perbaikan:

sudo chown -R postgres:postgres /var/lib/pgbackrest
sudo chown -R postgres:postgres /var/log/pgbackrest

#Kesalahan Klasik

Menjalankan pgbackrest sebagai root untuk backup lokal. Saat archive-push dijalankan oleh server (user postgres), akses ke repository yang dibuat root justru gagal. Selalu konsisten: backup lokal = user postgres, atau user khusus dengan akses repository yang sama.

#Kasus Umum 3: Repository Penuh

#Gejala

archive-push mulai gagal; df -h menunjukkan repository 100%. Backup gagal di tengah jalan karena tidak ada ruang.

#Penanganan Berurutan

1. Beri ruang cepat: hapus file temp/backup lama, atau tambah kapasitas storage.
2. Periksa retention: jika WAL menumpuk, repo1-retention-archive tidak diterapkan (episode 10).
3. Periksa kebocoran: file .tmp dari backup yang terputus bisa menyumbat ruang:

sudo find /var/lib/pgbackrest -name "*.tmp" -size +100M

4. Setelah ruang aman, archive-push yang tertunda otomatis berjalan ulang oleh PostgreSQL — WAL yang gagal tidak hilang, hanya menunggu.

#Kasus Umum 4: Version Mismatch

#Gejala

Error seperti db version ... does not match ... atau stanza already exists. Ini muncul saat versi pgBackRest atau PostgreSQL tidak cocok dengan yang tercatat di stanza.

#Penyebab dan Solusi

• PostgreSQL di-upgrade: jalankan stanza-upgrade untuk memperbarui metadata stanza:

sudo -u postgres pgbackrest --stanza=main stanza-upgrade

• pgBackRest di-upgrade: umumnya aman, tetapi check dulu dengan check setelah upgrade.
• Cluster berbeda dengan nama stanza sama: stanza sudah di-lock oleh identitas cluster lain. Jangan hapus paksa; buat stanza baru dengan nama berbeda.

#Workflow Debugging Ringkas

Ketika error datang, ikuti urutan ini tanpa lompat:

1. Baca pesan error lengkap — jangan hanya baris pertama.
2. Jalankan ulang dengan --log-level-console=debug.
3. Cek /var/log/pgbackrest/ untuk konteks yang tidak terlihat di console.
4. Verifikasi hal paling mendasar dulu: user, permission, ruang disk, dan versi.
5. Tes komponen terkecil (archive-push manual) sebelum menyalahkan yang besar.

#Penutup

Inti yang harus dibawa pulang:

• --log-level-console=debug untuk insiden interaktif; --log-level-file=debug untuk investigasi panjang.
• Log file di /var/log/pgbackrest/ berisi kode error, DETAIL, dan HINT.
• archive-push gagal: periksa path binary, archive_mode, dan stanza.
• Permission denied: pastikan user konsisten dan ownership benar.
• Repository penuh: beri ruang, cek retention, bersihkan .tmp.
• Version mismatch: stanza-upgrade untuk upgrade PostgreSQL, jangan hapus stanza paksa.

Di episode 16 selanjutnya kita akan membuktikan backup kalian benar-benar bisa dipulihkan: testing restore (drill) — melakukan restore test berkala ke instance terpisah, memvalidasi data (checksum, row count), mengotomatiskan drill dengan script + report, dan mendokumentasikan runbook. Backup yang tidak pernah diuji adalah harapan yang disamarkan sebagai rencana!