Troubleshooting

Bagian dari hidup database yang tidak bisa dijadwalkan: suatu pagi aplikasi menolak koneksi, atau query yang biasanya selesai dalam 50 milidetik tiba-tiba menggantung 30 detik. Pada momen seperti itu yang dibutuhkan bukan teori, tetapi indeks: gejala → langkah diagnosis pertama → penyebab paling mungkin → tempat membaca penjelasan utuhnya. Chapter Troubleshooting PostgreSQL di Section Pengujian dan Debugging sudah melatih pola pikirnya — ukur dulu, baru bertindak — beserta query diagnosisnya yang dijalankan nyata. Chapter ini melengkapi latihan itu sebagai indeks rujukan yang lebih luas: tabel gejala mencakup enam kategori masalah, lima gejala paling sering diberi narasi langkah pertamanya, dan bagian penutupnya mengajarkan cara bertanya ke komunitas dengan laporan yang layak dijawab.

Cara Membaca Indeks Ini #

Setiap baris tabel di bawah memuat empat hal: gejala sebagaimana adanya dilaporkan pengguna, perintah atau query pertama yang paling murah dijalankan, penyebab yang paling sering terbukti, dan chapter course tempat penjelasannya berada. Urutan pemakainya: temukan baris yang gejalanya paling mirip, jalankan langkah pertamanya, baca hasilnya, baru kejar chapter-nya. Langkah pertama sengaja dipilih yang aman — pg_isready, EXPLAIN, query ke view monitoring — karena semuanya hanya membaca keadaan, tidak mengubah apa pun.

Indeks Gejala → Diagnosis #

Lima Gejala yang Paling Sering Datang #

Tidak bisa koneksi. Jalankan pg_isready dengan host dan port yang dipakai aplikasi: jawaban accepting connections berarti server hidup dan masalah ada di lapisan berikutnya; no response berarti server mati atau port salah. Bila server hidup tetapi klien tetap ditolak, baca pesan FATAL-nya — password authentication failed menunjuk ke pg_hba.conf dan kredensial, too many clients already menunjuk ke sesi menganggur di pg_stat_activity. Tiga jawaban itu memisahkan masalah jaringan, kebijakan, dan kapasitas dalam waktu kurang dari satu menit.

Query mendadak lambat. Buka pg_stat_activity, filter state = 'active', dan lihat kolom wait_event_type: Lock berarti antre kunci, IO dan DataFileRead berarti sedang bergumul dengan disk. Bila tidak ada sesi lain, jalankan EXPLAIN (ANALYZE, BUFFERS) pada query tersangka dan bandingkan perkiraan baris planner (rows=) dengan baris nyata — selisih besar berarti statistik usang, dan ANALYZE pada tabel terkait adalah perbaikan pertama yang layak dicoba sebelum menyentuh index.

Deadlock terdeteksi. PostgreSQL tidak membiarkan deadlock berlama-lama: ia mendeteksinya, membatalkan salah satu transaksi dengan SQLSTATE 40P01, dan mencatat keduanya di log. Langkah pertama membaca log itu — dua STATEMENT yang saling menunggu memperlihatkan tabel mana diakses dengan urutan berbeda. Perbaikannya ada dua lapis: samakan urutan akses tabel di seluruh kode, dan pendekkan transaksi agar jendela saling menahan menyempit. Aplikasi juga sebaiknya menangkap 40P01 sebagai sinyal untuk mencoba ulang sekali, karena transaksi yang dibatalkan bisa diulang dengan aman.

Disk mengisi. Ukur dulu arah pertumbuhannya: pg_database_size() untuk data, ukuran direktori pg_wal untuk log transaksi, dan umur file log server di log_directory. Tiga penyumbang klasik: log yang tidak dirotasi, WAL yang ditahan slot replikasi terbengkalai (periksa kolom active — slot f yang lama adalah tersangka utama), dan ruang mati MVCC yang hanya kembali lewat VACUUM. Tindakan daruratnya berjenjang: putar/hapus log lama, jatuhkan slot mati, lalu VACUUM (FULL) pada tabel terbesar dengan sadar bahwa operasi ini mengunci tabelnya.

Replication lag. Di primary, query pg_stat_replication dan baca tiga kolom lag — write_lag, flush_lag, replay_lag — untuk melihat di tahap mana standby tertinggal. Jarak yang membesar seragam di ketiganya biasanya jaringan atau disk standby; lag yang melonjak setelah query berat di standby menandakan recovery conflict. Selama lag belum terurai, arahkan sementara pembacaan pelapor ke primary agar laporan tidak membaca data basi.

Menambang Log dalam Satu Baris #

Semua gejala di atas meninggalkan jejak tertulis di log server, dan satu baris grep biasanya cukup untuk memulai penggalian:

grep -c ' ERROR: ' /var/log/postgresql/postgresql.log
grep -A2 ' ERROR: ' /var/log/postgresql/postgresql.log

Baris pertama menghitung error harian sebagai baseline — lonjakan angka ini adalah alarm yang berbunyi sebelum pengguna menelepon. Baris kedua mencetak setiap error beserta dua baris konteksnya, yang biasanya berisi DETAIL dan STATEMENT penjelasnya. Cara mengaktifkan duration: untuk query lambat, format log yang rapi untuk grep, serta rotasi lognya dibahas di chapter Server Logs dan Logging Configuration .

Kapan dan Bagaimana Bertanya ke Komunitas #

Waktu bertanya yang tepat: setelah langkah pertama dijalankan, hasilnya dibaca, dan manual serta arsip milis dicari — tetapi sebelum menghabiskan berjam-jam menebak. Kualitas jawaban ditentukan kualitas laporan. Empat bahan wajibnya: versi PostgreSQL dan pengaturan utama server, teks error lengkap dari baris ERROR: sampai HINT:, output EXPLAIN (ANALYZE) dari query bermasalah, serta reproduksi terkecil yang tetap memunculkan masalah. Query berikut merangkum bahan pertama dalam satu salin-tempel:

-- Informasi lingkungan yang layak dicantumkan saat bertanya ke komunitas:
-- versi PostgreSQL dan pengaturan utama server -- satu query, siap disalin.
SELECT current_setting('server_version')  AS versi_server,
       current_setting('max_connections') AS max_connections,
       current_setting('shared_buffers')  AS shared_buffers,
       current_setting('work_mem')        AS work_mem;

Output yang Dihasilkan:

          versi_server          | max_connections | shared_buffers | work_mem 
--------------------------------+-----------------+----------------+----------
 17.11 (Debian 17.11-0+deb13u1) | 100             | 128MB          | 4MB
(1 row)

Kolom-kolomnya dipilih karena paling sering memengaruhi jawaban: shared_buffers dan work_mem menentukan perilaku performa, max_connections menentukan diagnosis masalah koneksi. Tambahkan sistem operasi dan perkiraan ukuran tabel yang tersangkut, dan laporan Anda sudah berada di atas rata-rata.

Dengan indeks gejala dan format laporan di tangan, sisa bekal perjalanan tinggal satu tas: istilah. Ratusan istilah teknis telah lewat di course ini — dari ACID sampai window function — dan chapter penutup, Glosarium, merangkumnya semuanya dalam satu kamus ringkas.

Referensi #

• pg_isready
• Monitoring Statistics (pg_stat_activity, pg_stat_replication)
• Explicit Locking
• PostgreSQL Error Codes (SQLSTATE)

-- Informasi lingkungan yang layak dicantumkan saat bertanya ke komunitas:
-- versi PostgreSQL dan pengaturan utama server -- satu query, siap disalin.
SELECT current_setting('server_version')  AS versi_server,
       current_setting('max_connections') AS max_connections,
       current_setting('shared_buffers')  AS shared_buffers,
       current_setting('work_mem')        AS work_mem;