Panduan Penyelesaian Masalah PostgreSQL ServBay

PostgreSQL ialah sistem pangkalan data objek-relasi sumber terbuka yang sangat berkuasa dan kaya dengan fungsi, digunakan secara meluas dalam pelbagai aplikasi web dan senario penyimpanan data. Sebagai salah satu pakej utama dalam persekitaran pembangunan tempatan ServBay, PostgreSQL lazimnya berjalan stabil. Namun, anda mungkin mengalami masalah seperti pakej PostgreSQL gagal memulakan, sambungan bermasalah, prestasi menurun, atau isu capaian data dalam keadaan tertentu.

Dokumen ini bertujuan memberikan panduan penyelesaian masalah PostgreSQL yang terperinci kepada pembangun yang menggunakan ServBay. Kami akan membentangkan masalah lazim, langkah diagnosis serta penyelesaiannya dalam pakej PostgreSQL di ServBay. ServBay menyokong sistem operasi macOS dan Windows serta menggabungkan pelbagai versi pakej PostgreSQL—oleh itu, anda mungkin perlu menentukan versi spesifik, fail konfigurasi, atau laluan direktori data semasa menjalankan diagnosis atau pembaikan.

Ringkasan

Panduan ini menekankan isu teknikal yang mungkin anda temui semasa mengurus dan menggunakan pakej PostgreSQL dalam persekitaran ServBay. Kami mulakan dengan isu permulaan dan sambungan yang biasa, kemudian menjurus kepada masalah prestasi, runtuhan tak dijangka, serta sandaran dan pemulihan bagi senario yang lebih kompleks. Dengan mengikuti langkah-langkah yang disediakan, anda akan dapat mendiagnos dan menyelesaikan kebanyakan isu berkaitan PostgreSQL.

Prasyarat

Sebelum memulakan proses penyelesaian masalah, pastikan anda memenuhi syarat-syarat berikut:

1. ServBay telah berjaya dipasang dan dijalankan.
2. Anda telah memasang versi pakej PostgreSQL yang bermasalah melalui ServBay.
3. Memiliki pengetahuan asas mengenai operasi baris perintah.
4. Tahu lokasi fail konfigurasi dan laluan direktori data bagi pakej PostgreSQL anda.
   • macOS: /Applications/ServBay/db/postgresql/<version>
   • Windows: C:\ServBay\db\postgresql\<version>
5. Tahu nama pangkalan data, nama pengguna dan kata laluan yang digunakan untuk sambungan.

Isu Biasa & Penyelesaian

1. Pakej PostgreSQL Gagal Memulakan

Jika anda cuba memulakan pakej PostgreSQL melalui ServBay tetapi statusnya kekal berhenti atau gagal, beberapa faktor berikut mungkin menjadi punca:

Punca Mungkin

• Kesalahan sintaks atau konflik dalam fail konfigurasi.
• Port yang digunakan PostgreSQL (lalai 5432) telah digunakan oleh proses lain dalam sistem.
• Kebenaran baca/tulis yang tidak mencukupi pada direktori data, fail konfigurasi, atau katalog ServBay/PostgreSQL.
• Direktori data PostgreSQL rosak.
• Masalah pengurusan dalaman ServBay.

Penyelesaian

1. Semak Status dan Log GUI ServBay:
   Buka aplikasi ServBay dan semak status pakej PostgreSQL. Jika tidak normal, cuba mulakan secara manual melalui GUI. Periksa log utama ServBay ataupun log spesifik PostgreSQL.

Lokasi fail log:

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

2. Semak Fail Konfigurasi:
   Fail konfigurasi utama PostgreSQL ialah postgresql.conf. Pastikan tiada kesalahan sintaks, salah eja, atau entri tidak sah.

Lokasi fail konfigurasi (contoh PostgreSQL 13):

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

Fail penting lain ialah pg_hba.conf yang mengawal pengesahan klien. Konfigurasi yang salah boleh menyebabkan masalah sambungan, dan kadang kala menghalang permulaan. Jalur biasanya sama dengan postgresql.conf.

Walaupun tiada alat baris perintah PostgreSQL untuk "mengesahkan" sintaks fail konfigurasi sepenuhnya, anda boleh mengesan kesilapan dengan melihat log. Alternatifnya, gunakan psql untuk menyambung ke pangkalan data yang sedang berjalan (mungkin versi lain atau instans sementara) untuk semak konfigurasi. Cara paling langsung adalah menyemak error dalam log.

Untuk pg_hba.conf, anda boleh semak peraturan dengan arahan SQL selepas berjaya menyambung:

-- Perlu sambungan aktif ke pangkalan data
SELECT * FROM pg_hba_file_rules();

Untuk semak error ketika memuat konfigurasi, guna:

-- Perlu sambungan aktif ke pangkalan data
SELECT sourcefile, name, sourceline, error FROM pg_file_settings WHERE error IS NOT null;

Nota: SQL di atas hanya berkesan jika PostgreSQL sedang berjalan dan boleh disambung. Untuk situasi gagal mula, semak fail log adalah paling kritikal.

3. Semak Penggunaan Port:
   PostgreSQL lazimnya menggunakan port 5432. Jika port ini telah digunakan oleh proses lain, pakej PostgreSQL tidak akan dapat dimulakan.

Periksa penggunaan port:

macOS:

lsof -i :5432

Windows:

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

Jika arahan ini menghasilkan output, itu bermakna proses lain sedang menggunakan port 5432. Tentukan PID proses dan pertimbang berhenti proses itu atau ubah port pendengaran PostgreSQL (ubah parameter port dalam postgresql.conf, kemudian muat semula/mula semula pakej melalui GUI ServBay atau baris perintah servbayctl).

4. Periksa Kebenaran Fail dan Direktori:
   ServBay memerlukan kebenaran baca/tulis yang betul pada direktori pemasangan dan sub-direktori. Pastikan proses ServBay (biasanya atas nama pengguna anda) mempunyai hak yang mencukupi ke atas /Applications/ServBay/ dan isi kandungannya.

Periksa kebenaran:

macOS:

ls -ld /Applications/ServBay/db/postgresql/13 # Semak kebenaran direktori data
ls -l /Applications/ServBay/db/postgresql/13/postgresql.conf # Semak kebenaran fail konfigurasi
ls -l /Applications/ServBay/db/postgresql/13/pg_hba.conf # Semak kebenaran fail pengesahan

Windows:
Melalui Windows Explorer, semak atribut fail dan direktori. Pastikan akaun perkhidmatan ServBay mempunyai kebenaran baca/tulis yang mencukupi.
Jika kebenaran tidak betul, anda mungkin perlu menggunakan chmod atau chown (untuk macOS), namun lazimnya tidak perlu dibuat secara manual kerana pengesetan dilakukan sewaktu pemasangan ServBay. Jika terdapat isu kebenaran, ia mungkin berpunca dari pemasangan tidak lengkap atau fail telah diubah secara tidak sengaja.

5. Periksa Kerosakan Direktori Data:
   Direktori data PostgreSQL menyimpan semua fail pangkalan data. Sekiranya rosak (misalnya akibat gangguan kuasa atau ralat cakera), PostgreSQL mungkin gagal bermula. Log biasanya akan menunjukkan tanda kerosakan. Proses pembaikan agak kompleks dan boleh melibatkan kehilangan data. PostgreSQL menyediakan alat seperti pg_resetwal, namun hanya gunakan selepas membuat sandaran direktori data semasa (walaupun telah rosak).

6. Cuba Restart dengan Perintah ServBay:
   Selepas menyemak dan menolak punca di atas, cuba mulakan semula pakej PostgreSQL melalui baris perintah ServBay dengan menentukan versi:

   servbayctl restart postgresql 13

   Atau mulakan semula melalui GUI ServBay.

2. Gagal Bersambung ke PostgreSQL

Walaupun pakej PostgreSQL kelihatan berjalan, anda masih mungkin gagal bersambung menggunakan alat klien seperti psql, pgAdmin, atau kod aplikasi.

Punca Mungkin

• Pakej PostgreSQL sebenarnya belum sepenuhnya berfungsi.
• Konfigurasi dalam pg_hba.conf tidak membenarkan sambungan anda.
• Sambungan dihalang oleh firewall.
• Parameter sambungan (hos, port, nama pangkalan data, pengguna, kata laluan) salah.
• Pengguna tiada hak akses ke pangkalan data.

Penyelesaian

1. Semak Status Melalui GUI ServBay atau servbayctl:
   Pastikan status pakej PostgreSQL dalam GUI ServBay adalah “Berjalan”. Jika tidak, rujuk kepada seksyen "Gagal Memulakan Pakej PostgreSQL". Dengan servbayctl:

   servbayctl status postgresql 13

   Pastikan output menunjukkan pakej sedang berjalan.

2. Semak Konfigurasi Pengesahan pg_hba.conf:
   Fail pg_hba.conf mengawal sumber hos, pengguna dan pangkalan data mana yang dibenarkan menyambung dan dengan cara apa. Untuk pembangunan tempatan, anda biasanya mahu membenarkan sambungan dari localhost atau 127.0.0.1.

Lokasi fail:

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

Contoh peraturan untuk membenarkan pengguna demo ServBay menyambung dengan pengesahan md5:

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

Ubah suai pg_hba.conf dan muat semula konfigurasi (tanpa restart penuh):

servbayctl reload postgresql 13

Atau gunakan GUI ServBay.

3. Semak Tetapan Firewall:macOS:

# Tambahkan aplikasi ke senarai dibenarkan
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/postgres
# Pastikan aplikasi tidak disekat
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/postgres

Windows:
Semak Tetapan Windows Defender Firewall atau firewall pihak ketiga. Tambahkan aplikasi atau aturan port dibenarkan:

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

4. Semak Parameter Sambungan dan Hak Pengguna:
   Pastikan nama hos (biasanya localhost atau 127.0.0.1), port (5432 lalai), nama pangkalan data, nama pengguna dan kata laluan adalah betul dalam rentetan sambungan atau alat klien. Uji dengan psql:

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

   Gantikan your_username dan your_database dengan nilai sebenar. Jika sambungan berjaya, anda akan dapat psql prompt. Jika gagal, error akan menunjukkan sebab (mis. kata laluan salah, pangkalan data tiada, hak tidak cukup dsb).

   Jika boleh bersambung tetapi tidak boleh akses pangkalan data atau jadual tertentu, kemungkinan isu hak pengguna. Dalam psql, semak peranan dan hak guna arahan berikut:

   -- Jalankan dalam psql
   \du

   Jika perlu, gunakan akaun dengan hak lebih tinggi (mis. postgres) untuk memberikan hak dengan arahan GRANT.

3. Masalah Prestasi

Pakej PostgreSQL boleh dimulakan dan disambung, tetapi respons kueri perlahan membawa kepada isu prestasi.

Punca Mungkin

• Kueri SQL yang tidak dioptimumkan.
• Reka bentuk skema pangkalan data yang tidak efisien.
• Parameter konfigurasi memori, cache dan I/O tidak sesuai.
• Kurang indeks yang diperlukan.
• Sumber perkakasan tidak mencukupi (CPU, memori, I/O cakera).
• Statistik pangkalan data sudah usang.

Penyelesaian

1. Analisis dan Optimumkan Kueri:
   Gunakan EXPLAIN atau EXPLAIN ANALYZE untuk menganalisis pelaksanaan kueri perlahan. Ini menunjukkan sama ada indeks digunakan, urutan gabungan jadual, jenis imbasan dan bottleneck prestasi.

   -- Jalankan dalam psql atau klien SQL lain
   EXPLAIN ANALYZE SELECT * FROM your_table_name WHERE column_name = 'value';

   Berdasarkan hasil, pertimbang penulisan semula kueri, menambah indeks atau ubah suai struktur pangkalan data.

2. Laraskan Parameter Konfigurasi PostgreSQL:
   postgresql.conf mengandungi banyak parameter yang sangat mempengaruhi prestasi, terutamanya berkaitan memori dan storan.

   • shared_buffers: Menetapkan jumlah memori cache untuk data pangkalan data PostgreSQL. Nilai lebih tinggi boleh meningkatkan prestasi tetapi disyorkan tidak melebihi ~25% memori sistem.
   • work_mem: Memori untuk operasi dalaman seperti pengisihan dan hash. Kueri melibatkan pengisihan/operasi hash banyak, tingkatkan nilai ini untuk elak tulis data ke cakera sementara.

   Ubah mengikut sumber sistem dan beban kerja anda. Selepas ubah suai dalam postgresql.conf, muat semula atau restart pakej PostgreSQL untuk berkuat kuasa.

   # Contoh: Laras ikut memori sistem anda
   shared_buffers = 1GB # Sebagai contoh, jika sistem ada 4GB RAM
   work_mem = 64MB # Laras ikut keperluan kueri

3. Cipta Indeks Yang Sesuai:
   Membina indeks untuk kolum yang sering digunakan dalam WHERE, JOIN, atau ORDER BY sangat mempercepatkan kueri. Gunakan EXPLAIN untuk tentukan kolum yang patut diindeks.

   -- Contoh: Cipta indeks untuk kolum column_name dalam your_table_name
   CREATE INDEX idx_column_name ON your_table_name(column_name);

   Terlalu banyak indeks boleh melambatkan operasi tulis dan meningkatkan penggunaan ruang cakera, jadi hanya buat indeks yang benar-benar diperlukan.

4. Kemas Kini Statistik:
   Pengoptimum kueri PostgreSQL bergantung pada statistik kandungan jadual & indeks. Jika data banyak berubah, statistik boleh jadi usang dan mempengaruhi prestasi. Jalankan ANALYZE secara berkala:

   -- Kemas kini seluruh pangkalan data
   ANALYZE;
   -- Atau jadual tertentu
   ANALYZE your_table_name;

   ServBay lazimnya telah mengaktifkan pembersihan automatik (autovacuum), tetapi analisis manual berguna untuk diagnosis isu prestasi.

5. Semak Sumber Perkakasan:
   Walaupun ServBay ialah persekitaran pembangunan tempatan, projek pangkalan data besar atau kueri kompleks boleh membebankan CPU, RAM, dan cakera (terutamanya jika cakera mekanikal bukan SSD). Gunakan Activity Monitor di macOS untuk semak penggunaan sumber (CPU, RAM, cakera, rangkaian).

4. Runtuhan Pangkalan Data

Pakej PostgreSQL tiba-tiba berhenti atau tidak responsif—menunjukkan kemungkinan berlakunya runtuhan.

Punca Mungkin

• Masalah perkakasan seperti kesilapan memori atau cakera.
• Isu sistem operasi atau keterbatasan sumber.
• Bug pada PostgreSQL (jarang, biasanya versi spesifik atau senario kompleks).
• Direktori data rosak.
• Konfigurasi yang menyebabkan habis sumber (misalnya sambungan terlalu banyak).

Penyelesaian

1. Semak Log Error PostgreSQL:
   Semasa runtuhan, PostgreSQL akan merekodkan maklumat error terperinci ke fail log. Ini langkah diagnostik paling awal.

Lokasi fail log:

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

Cari mesej “FATAL” atau “ERROR”, terutama di sekitar masa runtuhan. Log biasanya akan menunjukkan sebab khusus seperti error memori, kegagalan assertion, error fail data, dan sebagainya.

2. Semak Log Sistem:
   Selain log PostgreSQL, log sistem macOS (boleh dilihat melalui aplikasi Console) mungkin mengandungi maklumat berkaitan masalah perkakasan atau sistem operasi yang berkaitan dengan runtuhan.

3. Semak Keadaan Perkakasan:
   Jalankan alat diagnostik terbina macOS atau perisian pengesanan pihak ketiga untuk kesan masalah RAM dan cakera keras. Kerana ralat cakera adalah penyebab biasa kerosakan pangkalan data dan runtuhan.

4. Baiki atau Bina Semula Direktori Data (Lakukan Dengan Cermat):
   Jika log menunjuk kepada kerosakan direktori data, cuba guna alat rendah seperti pg_resetwal (reset status Write Ahead Log). RISIKO PENGGUNAAN TINGGI, MUNGKIN KEHILANGAN DATA! Guna alat ini hanya jika kehilangan sebahagian data boleh diterima demi pemulihan servis.

   Cara paling selamat: a. Sandarkan direktori data semasa: Walaupun rosak, buat salinan penuh sebagai backup. b. Inisialisasi direktori data baru: Hentikan pakej PostgreSQL, alih keluar direktori lama, inisialisasi baharu dengan initdb (biasanya melalui pemasangan ServBay; mungkin perlu delete dan reinstall pakej PostgreSQL). c. Pulihkan data dari backup terkini: Gunakan pg_restore atau psql untuk memulihkan data ke direktori baharu dari fail backup yang dipercayai.

5. Pulih Dari Arkhib Sandaran:
   Jika direktori data tidak boleh dibaiki atau perlu rollback ke sebelum runtuhan, pulihkan data dari backup automatik atau manual ServBay.

Lokasi fail sandaran:

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

5. Masalah Sandaran dan Pemulihan

ServBay menyokong sandaran manual dan automatik untuk pakej PostgreSQL. Jika anda bermasalah semasa proses sandaran atau pemulihan, rujuk penyelesaian berikut.

Punca Mungkin

• Fail sandaran rosak atau tidak lengkap.
• Arahan atau parameter pemulihan salah.
• Pangkalan data sasaran tiada atau hak pengguna tidak mencukupi.
• Kekurangan ruang cakera.
• Gangguan semasa proses sandaran/pemulihan.

Penyelesaian

1. Semak Integriti Fail Sandaran:
   Pastikan fail sandaran (melalui pg_dump atau fungsi sandaran ServBay) bersaiz seperti dijangka dan tiada kerosakan semasa storan/pemindahan. Untuk fail teks, semak header dan ekor fail. Untuk format custom/direktori, kemungkinan perlu bergantung kepada error daripada pg_restore.

Lokasi fail sandaran:

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

Semak saiz fail:

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

2. Guna Arahan Pemulihan pg_restore atau psql Dengan Betul:
   Cara pemulihan bergantung pada format fail sandaran.

   • Format teks biasa (pg_dump -Fp atau tiada format khusus):
     Guna psql:

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

     Pastikan pangkalan data your_database telah wujud sebelumnya.

   • Format custom (-Fc) atau direktori (-Fd):
     Guna pg_restore:

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

     Pangkalan data sasaran your_database mesti telah diwujudkan. pg_restore mempunyai pelbagai pilihan pemulihan objek, dan sebagainya.

   Pastikan your_username mempunyai hak yang cukup dalam your_database (disarankan guna pemilik atau superuser seperti postgres).

3. Pastikan Pangkalan Data Sasaran Wujud:
   Sama ada guna psql -f atau pg_restore, pangkalan data sasaran mesti sudah ada sebelum proses bermula:

   createdb -U your_username -h localhost -p 5432 your_database

   Atau cipta melalui GUI ServBay atau alat lain.

4. Semak Ruang Cakera:
   Pemulihan pangkalan data besar perlukan ruang cakera yang secukupnya pada macOS.

5. Semak Konfigurasi dan Log Sandaran ServBay:
   Jika penggunaan sandaran automatik ServBay bermasalah, semak tetapan sandaran serta fail log utama atau berkaitan sandaran bagi punca khusus. ServBay membenarkan penetapan jadual, destinasi, dan polisi sandaran.

Soalan Lazim (FAQ)

• Bagaimana untuk mencari direktori data PostgreSQL dalam ServBay?
  Jawapan: Lokasi direktori data PostgreSQL ialah:

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

  Lokasi fail konfigurasi:

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

• Bagaimana untuk menetapkan semula kata laluan pengguna postgres dalam pakej PostgreSQL ServBay?
  Jawapan: Jika anda terlupa kata laluan superuser lalai postgres atau mahu set semula untuk pengguna lain, langkah berikut boleh diikuti (anda sekurang-kurangnya perlu boleh sambung dengan mod trust atau akaun superuser lain):

  1. Hentikan pakej PostgreSQL dalam ServBay.

  2. Edit fail pg_hba.conf untuk sementara tukar kaedah sambungan tempatan kepada trust (benarkan sambungan tanpa kata laluan).

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

     Cari 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

     Tukar kepada (untuk sambungan tempatan sahaja):

     # 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. Mulakan semula pakej PostgreSQL dalam ServBay.

  4. Sambung ke pangkalan data sebagai postgres tanpa kata laluan:

     psql -U postgres -h localhost -p 5432

  5. Dalam psql, tukar kata laluan dengan:

     ALTER USER postgres PASSWORD 'new_secure_password';

     Gantikan 'new_secure_password' dengan kata laluan baru anda. Untuk pengguna lain, tukar postgres kepada nama pengguna yang berkaitan.

  6. Taip \q untuk keluar dari psql.

  7. Penting: Hentikan pakej PostgreSQL, kembali tukar kaedah sambungan trust dalam pg_hba.conf kepada kaedah lebih selamat seperti md5 atau scram-sha-256, kemudian restart atau reload PostgreSQL melalui ServBay.

• Adakah ServBay menyokong kecekapan tinggi atau replikasi PostgreSQL?
  Jawapan: ServBay direka untuk pembangunan tempatan dan tidak menawarkan GUI pengurusan untuk kecekapan tinggi atau replikasi kelas produksi. Anda boleh mengkonfigurasi replikasi secara manual dalam ServBay, namun ia menuntut pengetahuan mendalam tentang tetapan dan arahan PostgreSQL.

• Bagaimana hendak menaik taraf versi pakej PostgreSQL dalam ServBay?
  Jawapan: ServBay membenarkan pemasangan dan pengurusan pelbagai versi pakej PostgreSQL. Untuk menaik taraf, pasang versi baharu dan lebih tinggi, kemudian gunakan alat rasmi pg_upgrade PostgreSQL untuk migrasi data dari direktori lama ke yang baharu. Proses ini melibatkan menghentikan kedua-dua versi, menjalankan pg_upgrade, dan memulakan versi baru. Ikuti panduan rasmi PostgreSQL untuk maklumat lanjut tentang pg_upgrade. ServBay menyimpan data setiap versi secara berasingan, memudahkan operasi ini.