Panduan Troubleshooting PostgreSQL di ServBay

PostgreSQL adalah sistem database objek-relasi open source yang sangat andal dan kaya fitur, digunakan secara luas pada aplikasi web dan penyimpanan data. Sebagai salah satu paket inti di lingkungan pengembangan lokal ServBay, PostgreSQL umumnya berjalan stabil. Namun, dalam beberapa situasi, Anda mungkin menemui masalah seperti paket PostgreSQL gagal start, koneksi gagal, performa menurun, atau error saat mengakses data.

Dokumen ini ditujukan bagi developer yang menggunakan ServBay, menyediakan panduan detail untuk troubleshooting PostgreSQL. Kami akan membahas masalah umum pada paket PostgreSQL di ServBay, langkah diagnosis, dan solusi yang relevan. ServBay mendukung macOS dan Windows, serta mengintegrasikan berbagai versi PostgreSQL, sehingga dalam beberapa langkah diagnosis atau perbaikan Anda mungkin perlu menentukan versi, file konfigurasi, atau path data tertentu.

Ringkasan

Panduan ini memfokuskan pada masalah teknis yang mungkin dihadapi saat mengelola dan menggunakan paket PostgreSQL di ServBay. Mulai dari masalah startup dan koneksi paling umum, hingga performa, crash mendadak, serta backup dan pemulihan. Dengan mengikuti langkah-langkah yang tersedia, Anda dapat mendiagnosis dan menyelesaikan sebagian besar masalah terkait PostgreSQL secara sistematis.

Prasyarat

Sebelum memulai troubleshooting, pastikan Anda memenuhi hal-hal berikut:

1. ServBay telah berhasil diinstal dan dijalankan.
2. Paket PostgreSQL yang ingin Anda troubleshooting sudah diinstal melalui ServBay.
3. Mampu menggunakan perintah di terminal/command line dasar.
4. Mengetahui path konfigurasi dan data paket PostgreSQL yang Anda pakai.
   • macOS: /Applications/ServBay/db/postgresql/<version>
   • Windows: C:\ServBay\db\postgresql\<version>
5. Mengetahui nama database, username, dan password yang Anda pakai.

Masalah Umum dan Solusinya

1. Paket PostgreSQL Gagal Start

Jika Anda mencoba menjalankan paket PostgreSQL melalui ServBay, tetapi statusnya tetap berhenti atau gagal start, kemungkinan disebabkan oleh hal berikut.

Penyebab yang Mungkin

• Kesalahan sintaks atau konflik konfigurasi pada file konfigurasi.
• Port yang digunakan PostgreSQL (default 5432) sudah dipakai proses lain.
• Tidak cukup permission baca/tulis pada direktori data, file konfigurasi, atau ServBay.
• Direktori data PostgreSQL rusak.
• Masalah manajemen internal ServBay.

Solusi

1. Periksa Status GUI ServBay dan Log: Buka antarmuka aplikasi ServBay, cek status paket PostgreSQL. Jika status abnormal, coba start manual melalui GUI. Cek log utama ServBay atau log spesifik dari paket PostgreSQL.

Lokasi file log:

• macOS: /Applications/ServBay/logs/postgresql/<version>/postgresql-<version>.log
• Windows: C:\ServBay\logs\postgresql\<version>\postgresql-<version>.log

2. Periksa File Konfigurasi: Konfigurasi utama PostgreSQL adalah postgresql.conf. Pastikan sintaks valid, tidak ada kesalahan ketik atau item konfigurasi yang tidak sah.

Lokasi file konfigurasi (misal PostgreSQL 13):

• macOS: /Applications/ServBay/db/postgresql/13/postgresql.conf
• Windows: C:\ServBay\db\postgresql\13\postgresql.conf

File penting lain adalah pg_hba.conf, yang mengatur autentikasi client. Konfigurasi yang salah dapat membuat koneksi dan start terganggu. Path biasanya sama dengan postgresql.conf.

PostgreSQL tidak menyediakan tools command line langsung untuk "validasi" seluruh file konfigurasi, namun Anda dapat mengecek error lewat log saat konfigurasi dimuat. Atau, gunakan `psql` untuk connect ke database yang RUNNING (versi lain/instance sementara) untuk cek konfigurasi. Cara paling efektif tetap lewat log untuk detail kesalahan saat start.

Untuk `pg_hba.conf`, rincian aturannya dapat dicek dengan SQL:
```sql
-- Perlu koneksi ke database untuk eksekusi perintah ini
SELECT * FROM pg_hba_file_rules();
```
Untuk error saat load konfigurasi, gunakan:
```sql
-- Perlu koneksi ke database untuk eksekusi perintah ini
SELECT sourcefile, name, sourceline, error FROM pg_file_settings WHERE error IS NOT null;
```
**Catatan:** Perintah SQL di atas hanya bisa dijalankan jika PostgreSQL sudah running dan bisa terhubung, jadi untuk kasus gagal start tidak terlalu berguna. **Cek file log** adalah langkah paling penting.

3. Periksa Port yang Digunakan: Secara default, PostgreSQL mendengarkan port 5432. Jika sudah digunakan proses lain, PostgreSQL tidak bisa start.

Cara cek penggunaan port:

macOS:

lsof -i :5432

Windows:

netstat -an | findstr :5432
# Atau menggunakan PowerShell
Get-NetTCPConnection -LocalPort 5432

Jika ada hasil, berarti port 5432 sedang digunakan proses lain. Identifikasi PID (ID proses), pertimbangkan untuk hentikan proses tersebut atau ubah port PostgreSQL di postgresql.conf (parameter port), lalu reload/restart PostgreSQL lewat GUI ServBay atau servbayctl.

4. Periksa Permission File dan Direktori: ServBay butuh permission baca/tulis ke install directory dan subdirektori. Direktori data dan file konfigurasi PostgreSQL harus diberi izin pada user yang menjalankan ServBay. Cek permission:

macOS:

ls -ld /Applications/ServBay/db/postgresql/13 # Cek permission data directory
ls -l /Applications/ServBay/db/postgresql/13/postgresql.conf # Cek permission konfigurasi
ls -l /Applications/ServBay/db/postgresql/13/pg_hba.conf # Cek permission file autentikasi

Windows: Via file explorer, klik kanan file/direktori, cek properties, pastikan akun ServBay punya izin baca/tulis. Jika permission salah, bisa diperbaiki lewat chmod atau chown, namun, sebaiknya tidak dilakukan manual pada lingkungan ServBay, karena permission sudah diatur saat instalasi.

5. Periksa Kerusakan Direktori Data: Data directory PostgreSQL berisi semua file database. Jika rusak (misal akibat shut down mendadak atau error disk), bisa mengakibatkan gagal start. Catatan tanda kerusakan biasanya muncul di log. Proses perbaikan bisa kompleks dan berisiko kehilangan data — gunakan tools seperti pg_resetwal dengan kehati-hatian. Selalu backup data directory sebelum percobaan apapun.

6. Coba Restart Melalui Command ServBay: Setelah pengecekan dan perbaikan di atas, coba restart PostgreSQL:

   servbayctl restart postgresql 13

   Atau gunakan operasi dari GUI ServBay.

2. Gagal Koneksi ke PostgreSQL

Walaupun PostgreSQL tampak running, Anda bisa saja gagal terhubung lewat client seperti psql, pgAdmin, atau aplikasi.

Penyebab yang Mungkin

• PostgreSQL sebenarnya tidak fully running.
• Aturan pada pg_hba.conf melarang koneksi Anda.
• Firewall memblokir koneksi.
• Parameter koneksi (host, port, database, username, password) salah.
• User tidak punya akses ke database tujuan.

Solusi

1. Cek Status Paket di ServBay GUI atau servbayctl: Pastikan status PostgreSQL di ServBay GUI benar-benar "Running". Jika tidak, ulangi troubleshooting “Paket gagal start”. Gunakan:

   servbayctl status postgresql 13

   Pastikan output menunjukkan PostgreSQL running.

2. Periksa Konfigurasi pg_hba.conf: File pg_hba.conf mengatur host/user/database mana yang boleh connect, serta metode autentikasi. Untuk pengembangan lokal, biasanya perlu aturan untuk localhost atau 127.0.0.1.

Temukan file pg_hba.conf, pastikan aturan sudah mengizinkan user/database yang sesuai dengan sumber koneksi Anda.

Lokasi file pg_hba.conf:

• macOS: /Applications/ServBay/db/postgresql/13/pg_hba.conf

• Windows: C:\ServBay\db\postgresql\13\pg_hba.conf

  Contoh aturan untuk demo ServBay user agar bisa konek via md5 password:

  # TYPE  DATABASE        USER            ADDRESS                 METHOD
  host    all             servbay-demo    127.0.0.1/32            md5
  host    all             servbay-demo    ::1/128                 md5

  Setelah edit, reload konfigurasi PostgreSQL:

  servbayctl reload postgresql 13

  Atau reload lewat GUI ServBay.

3. Periksa Aturan Firewall:macOS:

# Tambahkan aplikasi ke daftar izin
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/postgres
# Pastikan aplikasi tidak diblokir
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/postgres

Windows: Cek pengaturan Windows Defender atau firewall pihak ketiga:

# Izinkan program lewat firewall
netsh advfirewall firewall add rule name="ServBay PostgreSQL" dir=in action=allow program="C:\ServBay\bin\postgresql\<version>\bin\postgres.exe"

4. Periksa Parameter Koneksi dan Hak Akses User: Pastikan parameter koneksi (host, port, nama database, username, password) benar. Tes koneksi dengan psql:

   psql -U your_username -d your_database -h localhost -p 5432

   Ganti your_username dan your_database sesuai. Jika sukses, akan muncul prompt psql; jika gagal, perhatikan pesan error.

   Jika bisa terkoneksi tapi tak bisa akses database/tabel, bisa jadi masalah hak akses. Dalam psql, lihat role/permission:

   -- Di prompt psql
   \du

   Gunakan user superuser atau owner database, kemudian grant permission sesuai kebutuhan.

3. Masalah Performa

Paket PostgreSQL running dan bisa dikoneksi, tapi query lambat adalah tanda performa bermasalah.

Penyebab yang Mungkin

• Query SQL belum optimal.
• Desain skema database bermasalah.
• Pengaturan param memori, cache, dsb belum pas.
• Index kurang memadai.
• Sumber daya hardware terbatas (CPU, RAM, disk I/O).
• Statistik database tidak up-to-date.

Solusi

1. Analisis dan Optimasi Query: Gunakan EXPLAIN atau EXPLAIN ANALYZE untuk analisis execution plan query lambat. Output memberi info detail cara database mengeksekusi query, penggunaan index, urutan join/tabel, dsb.

   -- Di psql atau client lain
   EXPLAIN ANALYZE SELECT * FROM your_table_name WHERE column_name = 'value';

   Berdasarkan output, rewrite query, tambahkan index, atau ubah skema database jika perlu.

2. Tuning Parameter Konfigurasi PostgreSQL: Banyak param konfigurasi di postgresql.conf memengaruhi performa, terutama memori dan I/O. Yang paling penting:

   • shared_buffers: menentukan memori untuk cache data. Set lebih besar, biasanya meningkatkan performa, tapi jangan melebihi 25% total RAM.
   • work_mem: untuk operasi sort dan hash. Jika query butuh banyak sort/hash, perbesar param ini.

   Sesuaikan param di postgresql.conf, lalu reload/restart PostgreSQL.

   # Contoh penyesuaian sesuai RAM Anda
   shared_buffers = 1GB # Misal, jika RAM 4GB
   work_mem = 64MB # Sesuaikan sesuai query Anda

3. Buat Index yang Tepat: Buat index di kolom yang sering dipakai WHERE/JOIN/ORDER BY untuk percepat query.

   -- Contoh buat index di kolom tertentu
   CREATE INDEX idx_column_name ON your_table_name(column_name);

   Perlu diingat, terlalu banyak index memperberat write dan memperbesar disk usage, buat index secukupnya saja.

4. Update Statistik Database: Optimizer PostgreSQL mengandalkan statistik tabel dan index untuk eksekusi plan optimal. Jika data berubah banyak (insert, update, delete), statistik bisa outdated. Jalankan ANALYZE untuk update:

   -- Analisis seluruh database
   ANALYZE;
   -- Analisis tabel tertentu
   ANALYZE your_table_name;

   Biasanya mode autovacuum otomatis update statistik, tapi kadang manual ANALYZE berguna untuk troubleshooting.

5. Cek Sumber Daya Hardware: Meski ServBay adalah lingkungan dev lokal, database besar atau query kompleks bisa bottleneck di hardware (CPU, RAM, disk). Pakai Activity Monitor di macOS untuk cek resource usage.

4. Crash Database

Jika PostgreSQL tiba-tiba berhenti atau tidak responsif saat running, terjadi crash.

Penyebab yang Mungkin

• Masalah hardware (err memori, disk bad).
• Problem OS atau resource terbatas.
• Bug pada PostgreSQL (jarang, kecuali versi khusus/skenario kompleks).
• Direktori data rusak.
• Setting konfigurasi yang menyebabkan habis resource (misal connection terlalu banyak).

Solusi

1. Cek Error Log PostgreSQL: Saat crash, log akan mencatat error detail. Lokasi file log:

• macOS: /Applications/ServBay/logs/postgresql/<version>/postgresql-<version>.log
• Windows: C:\ServBay\logs\postgresql\<version>\postgresql-<version>.log

Cari pesan bertingkat FATAL atau ERROR di waktu crash. Biasanya log akan menunjukkan penyebab spesifik seperti error disk, memori, assertion error, dsb.

2. Cek Log Sistem: Selain log PostgreSQL, sistem macOS juga bisa mengandung info tambahan terkait hardware atau error OS yang berhubungan dengan crash. Gunakan aplikasi Console di macOS untuk cek.

3. Diagnosa Hardware: Jalankan tool diagnostik bawaan macOS atau software third-party untuk cek RAM, disk, dsb. Error disk adalah penyebab crash dan korupsi database yang sangat umum.

4. Perbaiki/Build Ulang Direktori Data (hati-hati): Jika log menunjukkan data directory rusak, bisa pakai tools low-level seperti pg_resetwal untuk recovery log. Namun risiko hilang data sangat besar—backup dulu sebelum percobaan apapun.

   Prosedur aman: a. Backup seluruh data directory: Bahkan jika sudah rusak, copy dulu seluruh folder data. b. Inisialisasi data directory baru: Stop PostgreSQL, singkirkan data lama, kemudian inisialisasi data baru dengan initdb (ServBay biasanya menghandle otomatis saat install ulang, atau hapus/install ulang paket PostgreSQL). c. Restore dari backup lengkap: Gunakan pg_restore atau psql dari backup Anda.

5. Restore dari Backup: Jika data directory tidak bisa diperbaiki, atau Anda perlu rollback sebelum crash, lakukan restore dari backup, baik yang dibuat manual, atau otomatis oleh ServBay.

   Lokasi file backup:

   • macOS: /Applications/ServBay/backup/postgresql/<version>/
   • Windows: C:\ServBay\backup\postgresql\<version>\

5. Masalah Backup dan Restore

ServBay mendukung backup manual dan otomatis untuk PostgreSQL. Jika mengalami kesulitan saat backup atau restore, gunakan solusi berikut.

Penyebab yang Mungkin

• File backup rusak atau tidak lengkap.
• Salah perintah/parameter restore.
• Database target belum ada, atau user tidak cukup permission.
• Ruang disk tidak cukup.
• Backup/restore terputus/terganggu.

Solusi

1. Cek Integritas File Backup: Pastikan file backup (hasil pg_dump atau fitur ServBay) punya ukuran yang sesuai dan tidak rusak. Untuk file backup teks, cek bagian awal dan akhir file. Untuk custom atau directory format, masalah biasanya muncul saat pg_restore.

Lokasi file backup:

• macOS: /Applications/ServBay/backup/postgresql/13/your_backup_file.dump
• Windows: C:\ServBay\backup\postgresql\13\your_backup_file.dump

Cek ukuran file:

• macOS: ls -lh /Applications/ServBay/backup/postgresql/13/your_backup_file.dump
• Windows: dir C:\ServBay\backup\postgresql\13\your_backup_file.dump

2. Gunakan Perintah Restore yang Benar (pg_restore atau psql): Pilih metode restore sesuai format backup:

   • Backup format teks (hasil pg_dump -Fp atau default): Restore dengan psql.

     psql -U your_username -d your_database -h localhost -p 5432 -f /path/to/your_backup_file.sql

     Database target your_database harus sudah ada sebelum restore.
   • Backup custom (-Fc) atau directory (-Fd): Restore dengan pg_restore.

     pg_restore -U your_username -d your_database -h localhost -p 5432 /path/to/your_backup_file.dump

     Sama, database target harus sudah ada lebih dulu. pg_restore memiliki banyak opsi untuk restore spesifik objek.

   Pastikan user your_username punya permission yang cukup untuk create objek. Biasanya gunakan owner database atau superuser (default postgres).

3. Pastikan Database Target Sudah Ada: Sebelum restore, buat dulu database target:

   createdb -U your_username -h localhost -p 5432 your_database

   Bisa juga via GUI ServBay atau tools database lain.

4. Cek Ruang Disk: Restore database besar butuh ruang yang cukup. Pastikan disk macOS Anda cukup luas.

5. Cek Konfigurasi dan Log Backup ServBay: Untuk backup otomatis ServBay yang gagal, cek pengaturan backup dan log, pastikan jadwal, tujuan, dan strategi retention sesuai.

Tanya Jawab (FAQ)

• Tanya: Di mana data directory PostgreSQL pada ServBay? Jawab: Lokasi data directory sebagai berikut:

  • macOS: /Applications/ServBay/db/postgresql/<version>/data
  • Windows: C:\ServBay\db\postgresql\<version>\data

  Lokasi file konfigurasi:

  • macOS: /Applications/ServBay/db/postgresql/<version>/
  • Windows: C:\ServBay\db\postgresql\<version>\

• Tanya: Bagaimana cara reset password user postgres di ServBay? Jawab: Jika lupa password superuser postgres atau mau reset user lain, lakukan langkah berikut (asumsi Anda bisa connect tanpa password/trust atau ada superuser lain):

  1. Stop paket PostgreSQL di ServBay.

  2. Edit file pg_hba.conf, ganti metode autentikasi lokal ke trust temporer.

     • macOS: /Applications/ServBay/db/postgresql/13/pg_hba.conf
     • Windows: C:\ServBay\db\postgresql\13\pg_hba.conf

     Temukan baris seperti:

     # TYPE  DATABASE        USER            ADDRESS                 METHOD
     local   all             all                                     peer  # atau md5
     host    all             all             127.0.0.1/32            md5   # atau scram-sha-256, dsb

     Ganti jadi (untuk lokal saja):

     # TYPE  DATABASE        USER            ADDRESS                 METHOD
     local   all             all                                     trust
     host    all             all             127.0.0.1/32            trust
     host    all             all             ::1/128                 trust

  3. Start PostgreSQL via ServBay.

  4. Koneksi psql pakai user postgres, tanpa password:

     psql -U postgres -h localhost -p 5432

  5. Di prompt psql, ubah password:

     ALTER USER postgres PASSWORD 'new_secure_password';

     Ganti 'new_secure_password' sesuai keinginan Anda. Untuk user lain, ganti postgres ke nama user terkait.

  6. Keluar dari psql dengan \q.

  7. Penting: Stop PostgreSQL, kembalikan setting trust di pg_hba.conf ke metode yang aman (misal, md5, scram-sha-256), lalu restart/reload.

• Tanya: Apakah ServBay mendukung fitur high availability atau replika PostgreSQL? Jawab: ServBay dirancang untuk pengembangan lokal, dengan fitur manajemen paket mudah. Tidak menyediakan GUI khusus untuk HA atau replika production-grade. Anda tetap bisa setup streaming replication secara manual di ServBay, namun butuh pengetahuan konfigurasi dan command line PostgreSQL.

• Tanya: Bagaimana upgrade versi paket PostgreSQL di ServBay? Jawab: Anda bisa install dan kelola banyak versi PostgreSQL lewat ServBay. Untuk upgrade, install versi baru, lalu migrasi data directory lama ke yang baru dengan tool resmi pg_upgrade. Proses ini perlu stop kedua versi, jalankan pg_upgrade, lalu start versi baru. Ikuti dokumentasi resmi PostgreSQL terkait langkah detail. ServBay menyimpan data directory terpisah antara versi yang berbeda, memudahkan proses upgrade/migrasi.