Panduan Penyelesaian Masalah PostgreSQL pada Persekitaran Pembangunan Tempatan macOS ServBay

PostgreSQL ialah sistem pangkalan data relasi objek sumber terbuka yang berkuasa dan kaya dengan ciri, digunakan secara meluas dalam pelbagai aplikasi web dan senario penyimpanan data. Sebagai salah satu pakej perisian teras persekitaran pembangunan tempatan ServBay, PostgreSQL biasanya beroperasi dengan stabil. Namun, dalam situasi tertentu, anda mungkin akan menemui masalah seperti pakej PostgreSQL gagal bermula, tidak dapat disambung, prestasi menurun, atau keganjilan akses data.

Dokumen ini bertujuan memberikan panduan terperinci kepada pembangun ServBay dalam menyelesaikan pelbagai masalah berkaitan PostgreSQL. Kami akan membentangkan masalah lazim pakej PostgreSQL dalam persekitaran ServBay, langkah diagnosis serta penyelesaian bersesuaian. Sila maklum, ServBay beroperasi pada sistem operasi macOS dan mengintegrasikan pelbagai versi pakej PostgreSQL. Oleh itu, untuk sesetengah langkah diagnosis atau pembaikan, anda mungkin perlu menetapkan versi, fail konfigurasi, atau laluan direktori data tertentu.

Gambaran Keseluruhan

Panduan ini memfokuskan kepada isu-isu teknikal yang mungkin timbul semasa anda menguruskan dan menggunakan pakej PostgreSQL dalam persekitaran ServBay. Bermula dari isu permulaan dan sambungan yang paling biasa, kita akan menyelami masalah prestasi, keruntuhan mengejut, serta sandaran dan pemulihan pangkalan data. Dengan mengikuti langkah-langkah yang disediakan, anda dapat mendiagnosis dan menyelesaikan majoriti masalah berkaitan PostgreSQL secara sistematik.

Prasyarat

Sebelum memulakan penyelesaian masalah, pastikan anda telah memenuhi syarat berikut:

1. ServBay telah dipasang dan dijalankan dengan berjaya.
2. Versi pakej PostgreSQL berkaitan telah dipasang melalui ServBay.
3. Anda mempunyai pengetahuan asas menggunakan perintah baris (command line) macOS.
4. Anda tahu laluan konfigurasi dan direktori data bagi pakej PostgreSQL anda (kebiasaannya di /Applications/ServBay/db/postgresql/<version>).
5. Anda tahu nama pangkalan data, nama pengguna, dan kata laluan yang ingin disambung.

Masalah Lazim dan Solusi

1. Pakej PostgreSQL Gagal Dimulakan

Apabila anda cuba memulakan pakej PostgreSQL melalui ServBay tetapi statusnya kekal di "berhenti" atau gagal bermula, ia mungkin disebabkan perkara berikut.

Punca Berkaitan

• Terdapat ralat sintaks atau konflik dalam fail konfigurasi.
• Port (lalai 5432) telah digunakan oleh proses lain dalam sistem.
• Direktori data, fail konfigurasi, atau servis lain kekurangan keizinan baca/tulis.
• Direktori data PostgreSQL rosak.
• Masalah dalaman pengurusan ServBay.

Solusi

1. Semak status & log GUI ServBay: Buka antara muka aplikasi ServBay dan perhatikan status pakej PostgreSQL. Jika ia kelihatan tidak normal, cuba mulakan semula secara manual melalui GUI. Seterusnya, semak log utama ServBay atau log khusus PostgreSQL sekiranya tersedia (kebiasaannya di /Applications/ServBay/logs/). Fail log postgresql/<versi>/postgresql-<versi>.log biasanya merekodkan maklumat ralat permulaan secara terperinci.

2. Periksa fail konfigurasi: Fail konfigurasi utama PostgreSQL ialah postgresql.conf. Pastikan tiada kesilapan ejaan atau konfigurasi tidak sah. Sebagai contoh, untuk PostgreSQL 13 yang diintegrasi dalam ServBay:

   /Applications/ServBay/db/postgresql/13/postgresql.conf

   Fail konfigurasi penting lain ialah pg_hba.conf yang mengawal pengesahan klien. Set konfigurasi yang salah boleh menyebabkan kegagalan sambungan malah turut mempengaruhi proses permulaan (misalnya semasa semakan sambungan dalaman). Lokasinya biasanya bersama postgresql.conf.

   PostgreSQL tiada alat khusus untuk “mengesah” seluruh fail konfigurasi, tapi anda boleh menyemak log untuk ralat sewaktu konfigurasi dimuat naik. Anda juga boleh menggunakan psql untuk menyemak konfigurasi pada instans yang sudah dijalankan.

   Untuk pg_hba.conf, setelah berjaya sambung, anda boleh semak aturan dengan SQL:

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

   Untuk semak jika terdapat ralat sewaktu memuat konfigurasi:

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

   Nota: Perintah SQL di atas hanya sesuai jika PostgreSQL telah berjaya dimulakan. Jika gagal dimulakan, semakan log fail adalah langkah utama.

3. Semak penggunaan port: Secara lalai PostgreSQL mendengar di port 5432. Jika port ini telah digunakan proses lain, PostgreSQL tidak dapat bermula. Semak status port menggunakan:

   lsof -i :5432

   Jika ada output, proses lain sedang menggunakan port tersebut. Tentukan proses yang terlibat via PID dan pertimbang untuk hentikan proses itu atau tukar port pendengaran PostgreSQL (ubah parameter port dalam postgresql.conf dan muat semula/restart pakej PostgreSQL dengan UI ServBay atau servbayctl).

4. Semak keizinan fail & direktori: ServBay memerlukan keizinan baca/tulis yang betul kepada direktori pemasangan serta kandungannya. Pastikan pengguna anda mempunyai keizinan sewajarnya terhadap /Applications/ServBay/ serta subdirektori. Semak keizinan dengan:

   ls -ld /Applications/ServBay/db/postgresql/13
   ls -l /Applications/ServBay/db/postgresql/13/postgresql.conf
   ls -l /Applications/ServBay/db/postgresql/13/pg_hba.conf

   Jika keizinan tidak betul, anda boleh baiki dengan chmod atau chown tetapi ini jarang perlu dilakukan secara manual kerana ServBay telah menetapkan keizinan semasa pemasangan. Jika tetap berlaku, kemungkinan ada pengubahsuaian fail atau masalah pemasangan.

5. Semak kerosakan direktori data: Direktori data PostgreSQL menyimpan semua fail pangkalan data. Jika ia rosak akibat kegagalan kuasa atau ralat cakera, PostgreSQL boleh gagal dimulakan. Log biasanya menunjukkan petunjuk kerosakan. Proses pemulihan adalah rumit dan kadang memerlukan alat lanjutan (seperti pg_resetwal). Sila buat sandaran penuh direktori sedia ada sebelum sebarang cubaan pemulihan, walaupun ia sudah rosak.

6. Cuba mulakan semula melaui perintah arahan ServBay: Selepas menyemak dan membetulkan semua faktor di atas, cuba muat semula pakej PostgreSQL dengan perintah:

   servbayctl restart postgresql 13

   atau melalui GUI ServBay.

2. Tidak Dapat Menyambung ke PostgreSQL

Walaupun status pakej PostgreSQL ialah "aktif", anda masih boleh mengalami kegagalan untuk menyambung melalui alat klien seperti psql, pgAdmin, atau kod aplikasi anda.

Punca Berkaitan

• Pakej PostgreSQL sebenar masih belum bermula sepenuhnya.
• Konfigurasi pg_hba.conf tidak membenarkan sambungan anda.
• Firewall menghalang sambungan ke pangkalan data.
• Parameter sambungan (host, port, nama pangkalan data, pengguna, kata laluan) tidak tepat.
• Pengguna tidak mempunyai keizinan mencukupi kepada pangkalan data.

Solusi

1. Semak status pakej melalui GUI ServBay atau servbayctl: Pastikan status pakej dalam GUI adalah "Sedang Berjalan". Jika tidak, rujuk seksyen masalah permulaan di atas. Semak status pakej secara baris perintah:

   servbayctl status postgresql 13

   Pastikan output menunjukkan "running".

2. Periksa konfigurasi pengesahan pg_hba.conf: Fail pg_hba.conf menentukan host, pengguna, dan pangkalan data mana yang dibenarkan serta kaedah pengesahan. Untuk pembangunan tempatan, benarkan sambungan dari localhost atau 127.0.0.1.

   Lokasi fail contoh: /Applications/ServBay/db/postgresql/13/pg_hba.conf. Pastikan ada aturan sesuai:

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

   Selepas suntingan, muat semula konfigurasi tanpa perlu restart:

   servbayctl reload postgresql 13

3. Semak tetapan firewall: Firewall dalaman macOS atau aplikasi pihak ketiga mungkin menghalang sambungan ke port 5432. Benarkan binari postgres ServBay melalui firewall:

   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/postgres
   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/postgres

   Masukkan kata laluan admin jika diperlukan.

4. Periksa parameter sambungan & keizinan pengguna: Pastikan host (localhost atau 127.0.0.1), port (5432), nama pengguna dan pangkalan data tepat. Uji sambungan dengan:

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

   Gantikan your_username dan your_database mengikut maklumat sebenar anda.

   Untuk isu keizinan, setelah masuk menggunakan pengguna yang mempunyai hak sewajarnya (seperti postgres), semak peranan dengan:

   \du

   Berikan keizinan yang diperlukan kepada pengguna anda menggunakan perintah GRANT.

3. Masalah Prestasi

PostgreSQL berjalan, boleh disambung, tetapi kueri atau operasi terasa perlahan.

Punca Berkaitan

• Kueri SQL tidak dioptimumkan.
• Reka bentuk skema pangkalan data tidak efisien.
• Parameter konfigurasi berkait memori/caching kurang sesuai.
• Kekurangan indeks yang perlu.
• Sumber perkakasan tidak mencukupi (CPU, RAM, I/O cakera).
• Statistik pangkalan data lapuk.

Solusi

1. Analisis & optimumkan kueri: Jalankan EXPLAIN atau EXPLAIN ANALYZE untuk analisis pelan pelaksanaan kueri:

   EXPLAIN ANALYZE SELECT * FROM your_table_name WHERE column_name = 'value';

   Berdasarkan output, pertimbang penulisan semula kueri, menambah indeks atau menyesuaikan struktur data.

2. Sesuaikan parameter konfigurasi PostgreSQL: Dua parameter kritikal di postgresql.conf ialah:

   • shared_buffers: Saiz memori cache. Nilai yang lebih besar membantu, tapi lazimnya tidak melebihi 25% daripada RAM keseluruhan.
   • work_mem: Memori untuk operasi perantaraan seperti sort/hash. Boleh dinaikkan mengikut keperluan. Contoh konfigurasi:

   shared_buffers = 1GB
   work_mem = 64MB

3. Bina indeks yang relevan: Indeks pada lajur yang selalu digunakan di WHERE, JOIN, atau ORDER BY dapat memecutkan kueri:

   CREATE INDEX idx_column_name ON your_table_name(column_name);

   Jangan buat terlalu banyak indeks kerana ia menjejaskan operasi tulis dan penggunaan ruang.

4. Kemas kini statistik: Optimumkan pelan kueri menggunakan statistik yang tepat. Jalankan:

   ANALYZE;
   -- atau untuk jadual tertentu
   ANALYZE your_table_name;

   ServBay biasanya mengaktifkan autovacuum (termasuk auto-analyze), tapi analisis manual berguna untuk diagnosis.

5. Semak sumber perkakasan: Gunakan Activity Monitor macOS untuk melihat penggunaan CPU, RAM, cakera dan rangkaian. Kekurangan sumber akan mempengaruhi prestasi terutama untuk dataset besar atau kueri berat.

4. Keruntuhan Pangkalan Data

Proses PostgreSQL tiba-tiba berhenti atau tidak responsif.

Punca Berkaitan

• Kerosakan hardware (RAM, cakera).
• Masalah OS atau had sumber sistem.
• Bug dalam versi PostgreSQL (jarang melainkan kes khusus).
• Direktori data rosak.
• Konfigurasi salah hingga sumber habis (contoh, terlalu banyak sambungan).

Solusi

1. Semak log ralat PostgreSQL: Log /Applications/ServBay/logs/postgresql/<versi>/postgresql-<versi>.log adalah rujukan utama diagnosis. Cari mesej FATAL atau ERROR, khususnya di masa kejadian.

2. Periksa log sistem: Log sistem macOS (boleh dibuka dengan Console) mungkin menunjukkan isu perkakasan atau OS berkaitan.

3. Semak kesihatan hardware: Jalankan alat diagnosis macOS atau pihak ketiga untuk menguji memori dan cakera. Ralat cakera antara punca utama keruntuhan atau kerosakan.

4. Pembaikan atau bina semula direktori data (berhati-hati): Jika log menunjukkan direktori data rosak, guna alat seperti pg_resetwal untuk pembetulan (berisiko tinggi kehilangan data!). Sandarkan direktori sedia ada dahulu.

   Saranan lebih selamat: a. Buat salinan direktori data: Untuk backup, walau yang rosak. b. Inisialisasi direktori baru: Hentikan PostgreSQL, alihkan sementara data lama, jalankan initdb untuk cipta data direktori baru (ServBay selalunya automasi proses ini—anda boleh reinstall pakej PostgreSQL untuk tujuan ini). c. Pulihkan dari sandaran terbaru: Guna pg_restore atau psql pada data bersih.

5. Pemulihan dari sandaran: Jika pembetulan data gagal, atau mahu kembali ke keadaan sebelum crash, pulihkan data dari fail backup ServBay (biasanya dalam /Applications/ServBay/backup/postgresql/<versi>/).

5. Masalah Sandaran dan Pemulihan

ServBay menyokong sandaran manual dan automatik untuk PostgreSQL. Jika isu berlaku sewaktu melakukan sandaran/pemulihan, cuba langkah berikut.

Punca Berkaitan

• Fail sandaran rosak atau tidak lengkap.
• Ralat perintah atau parameter sewaktu pemulihan.
• Pangkalan data sasaran belum wujud atau kekurangan keizinan pengguna.
• Ruang cakera tidak mencukupi.
• Proses sandaran/pemulihan terganggu.

Solusi

1. Semak integriti fail sandaran: Pastikan saiz dan kandungan fail sandaran (dihasilkan oleh pg_dump atau fungsi sandaran automatik ServBay) adalah logik. Untuk fail teks, baca kepala atau akhirannya untuk pastikan tiada data hilang. Untuk format custom atau directory, gunakan pg_restore (ia akan melapor jika terdapat masalah). Lokasi contoh:

   /Applications/ServBay/backup/postgresql/13/your_backup_file.dump

   Gunakan ls -lh untuk semak saiz fail.

2. Perintah pemulihan betul (pg_restore atau psql): Format fail sandaran akan tentukan perintah yang sesuai.

   • Fail teks biasa (pg_dump -Fp): Pulihkan dengan psql.

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

     Pangkalan data your_database mesti wujud dahulu.
   • Format custom (-Fc) atau directory (-Fd): Gunakan pg_restore.

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

     Pastikan pengguna anda ada hak secukupnya untuk lakukan restore (biasanya menggunakan user pemilik database atau superuser postgres).

3. Pastikan pangkalan data wujud: Apapun perintah (psql -f atau pg_restore), anda perlu cipta pangkalan data terlebih dahulu:

   createdb -U your_username -h localhost -p 5432 your_database

   Boleh juga gunakan GUI ServBay atau sebarang alat pengurusan database lain.

4. Pastikan ruang cakera cukup: Sandaran atau pemulihan database besar perlukan ruang penyimpanan yang besar juga. Pastikan storan macOS anda cukup.

5. Semak konfigurasi sandaran & log ServBay: Jika anda guna fungsi sandaran automatik ServBay, semak tetapan serta log berkaitan bagi mengenal pasti sebab kegagalan sandaran. ServBay membolehkan penjadualan, penentuan lokasi dan dasar simpanan sandaran.

Soalan Lazim (FAQ)

• S: Bagaimana mencari direktori data PostgreSQL dalam ServBay? J: Lazimnya di /Applications/ServBay/db/postgresql/<version>/data, di mana <version> ialah versi yang dipasang (cth: 13). Fail konfigurasi postgresql.conf dan pg_hba.conf pula berada di /Applications/ServBay/db/postgresql/<version>/.

• S: Bagaimana menetapkan semula kata laluan pengguna postgres untuk pakej PostgreSQL? J: Jika anda terlupa kata laluan superuser lalai atau ingin menetapkan semula user lain, lakukan langkah berikut (asalkan boleh sambung tanpa kata laluan atau ada hak superuser lain):

  1. Hentikan pakej PostgreSQL daripada ServBay.
  2. Sunting fail pg_hba.conf (misal /Applications/ServBay/db/postgresql/13/pg_hba.conf) dan tukar kaedah sambungan tempatan kepada trust:

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

     Tukar seperti berikut (khusus untuk sambungan lokal):

     # 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 melalui ServBay.
  4. Sambung ke pangkalan data dengan psql sebagai postgres tanpa kata laluan:

     psql -U postgres -h localhost -p 5432

  5. Dalam psql, tukar kata laluan:

     ALTER USER postgres PASSWORD 'new_secure_password';

     Tukarkan 'new_secure_password' dengan kata laluan baharu anda. Untuk pengguna lain, gantikan postgres dengan username sebenar.
  6. Keluar dengan \q.
  7. Penting: Segera hentikan semula PostgreSQL dan pulihkan pg_hba.conf kepada kaedah lebih selamat (seperti md5 atau scram-sha-256), kemudian mula/reload pakej PostgreSQL ServBay.

• S: Adakah ServBay menyokong PostgreSQL High Availability atau replikasi? J: ServBay direka untuk persekitaran pembangunan tempatan, menyediakan pengurusan dan integrasi pakej yang mudah. Ia tidak menawarkan pengurusan HA/replication berasaskan GUI seperti dalam produksi. Anda boleh konfigurasikan replikasi manual seperti streaming replication, tapi perlu pengetahuan lebih lanjut dan kendalian command line.

• S: Bagaimana menaik taraf versi pakej PostgreSQL dalam ServBay? J: Anda boleh memasang dan mengurus pelbagai versi PostgreSQL dalam ServBay. Untuk naik taraf, pasang versi baharu dan gunakan alat rasmi PostgreSQL pg_upgrade untuk memindahkan data dari direktori data versi lama ke yang baharu. Proses ini melibatkan pemberhentian kedua-dua versi, menjalankan pg_upgrade, dan kemudian memulakan versi baharu. Rujuk dokumentasi rasmi pg_upgrade untuk langkah lanjut. Setiap versi pakej ServBay menyimpan direktori data berasingan, memudahkan proses naik taraf.