Panduan Pemecahan Masalah ServBay MariaDB/MySQL

Ringkasan

MariaDB dan MySQL adalah sistem manajemen database relasional open-source paling populer, banyak digunakan di berbagai aplikasi web dan skenario bisnis. ServBay mengintegrasikan berbagai versi MariaDB/MySQL dalam lingkungan macOS, menyediakan kemudahan lingkungan database lokal bagi pengembang. Meski terkenal stabil, tetap saja masalah seperti paket tidak bisa dijalankan, gagal terhubung, atau penurunan performa dapat terjadi saat pengembangan.

Panduan ini membantu pengguna ServBay mendiagnosis dan memecahkan masalah umum yang terjadi pada paket MariaDB/MySQL. Kami akan membahas permasalahan umum, langkah diagnosis, solusi spesifik, serta jalur dan perintah khusus di lingkungan ServBay.

Catatan penting:

• Pastikan selalu melakukan backup database Anda sebelum melakukan perubahan apapun pada data atau konfigurasi! ServBay menyediakan fitur backup bawaan yang sangat disarankan digunakan secara berkala.
• Contoh perintah dan jalur di dalam panduan ini menggunakan nomor versi khusus (misal 11.3 atau 11.5), silakan sesuaikan dengan versi MariaDB/MySQL yang Anda aktifkan di ServBay. Anda dapat melihat versi di antarmuka aplikasi ServBay.
• Placeholder seperti <username>, <database>, <your_backup.sql> dll di contoh perintah harus diganti dengan data Anda sendiri.
• Panduan ini berbasis pada sistem operasi macOS.

Langkah Diagnosis Dasar

Sebelum menangani masalah secara spesifik, lakukan pemeriksaan dasar berikut:

1. Periksa status paket ServBay: Buka aplikasi ServBay dan pastikan MariaDB/MySQL versi yang Anda gunakan sudah aktif dan berstatus “Berjalan”. Anda juga bisa cek via command line:

   servbayctl status mariadb <version>
   # Contoh, cek status MariaDB 11.3:
   servbayctl status mariadb 11.3

2. Periksa log aplikasi ServBay: Kadang, ServBay otomatis mencatat error saat mencoba menjalankan/mengelola paket. Cek pada area log di aplikasi ServBay atau lihat file log utama ServBay.
3. Periksa error log MariaDB/MySQL: Ini langkah terpenting untuk melacak kegagalan start dan error runtime. Lokasi file log biasanya:

   /Applications/ServBay/logs/mariadb/<version>/<version>.err
   # Contoh, lihat 50 baris terakhir error log MariaDB 11.3:
   tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err

   Perhatikan pesan error di bagian akhir log—umumnya ini mengindikasikan sumber masalah.

Masalah Umum & Solusi

1. Error Koneksi: SQLSTATE[HY000] [2002] No such file or directory

Error ini biasanya berarti client tidak dapat terkoneksi ke server MariaDB/MySQL via Unix socket. Di macOS, unix socket adalah sarana komunikasi antar-proses lokal yang umum, biasanya lebih efisien daripada TCP/IP. Jika aplikasi/command line mencoba konek lewat socket tapi file socket tidak ditemukan, error ini akan muncul.

Kemungkinan penyebab dan solusinya:

• Paket MariaDB/MySQL tidak berjalan:
  • Cek status di aplikasi ServBay atau via servbayctl status mariadb <version>.
  • Jika belum berjalan, start dengan: servbayctl start mariadb <version> dan cek error log (.err) jika gagal.
• Jalur file socket salah:
  • Jalur socket pada client berbeda dengan setelan server di file konfigurasi (my.cnf).
  • Cek parameter socket di /Applications/ServBay/etc/mariadb/<version>/my.cnf.
  • Pastikan aplikasi/client memakai jalur socket yang sama dengan ServBay. Secara default, socket ServBay ada di /Applications/ServBay/tmp/ atau /tmp/, misal /Applications/ServBay/tmp/mysql.sock atau /tmp/mysql.sock.
• Masalah pengaturan default ServBay:
  • Pada “Pengaturan” → “SQL Server Default” ServBay, pastikan versi MariaDB/MySQL yang benar yang dijadikan default. Beberapa alat klien (seperti command line mysql tanpa flag -S atau -h) akan mencoba konek ke socket versi default.
• Masalah hak akses:
  • User proses MariaDB/MySQL atau user client tidak punya hak yang tepat ke direktori/file socket. ServBay umumnya sudah mengaturnya, tapi mengubah permission manual pada /Applications/ServBay/tmp/ atau /tmp/ bisa menyebabkan error.

Solusi alternatif (paksa gunakan koneksi jaringan):

• Coba koneksi menggunakan IP 127.0.0.1 bukan localhost. Ini akan memaksa koneksi TCP/IP, bukan Unix socket. Jika hal ini berhasil, kemungkinan masalah ada di file socket.

  mysql -u <username> -p -h 127.0.0.1 -P 3306

2. Error Koneksi: Masalah pada koneksi jaringan (Connection refused, Can't connect to MySQL server)

Jenis error ini berarti client gagal konek ke server MariaDB/MySQL via TCP/IP.

Kemungkinan penyebab dan solusinya:

• Paket MariaDB/MySQL tidak berjalan: (Cek status paket dan .err log seperti poin di atas)
• Port digunakan aplikasi lain:
  • Pastikan port default (3306) tidak dipakai proses lain.
  • Cek port:

    lsof -i :3306
    # Atau
    netstat -anv | grep LISTEN | grep 3306

  • Jika port digunakan, hentikan proses aktif atau ubah port di my.cnf, restart paket.
• Firewall memblokir koneksi:
  • Firewall default macOS atau aplikasi firewall bisa memblokir port 3306.
  • Periksa (System Preferences → Network → Firewall).
  • Izinkan sementara proses mysqld pada firewall (cek jalur sesuai versi ServBay):

    # Contoh, sesuaikan path
    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/mariadb/<version>/bin/mysqld
    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/mariadb/<version>/bin/mysqld

• Masalah konfigurasi (bind-address):
  • Cek bind-address di my.cnf. 127.0.0.1 atau localhost hanya izinkan koneksi di mesin yang sama. Untuk akses dari lain host, gunakan 0.0.0.0 atau IP tertentu, dan cek firewall.
• Masalah konfigurasi jaringan (localhost resolve):
  • Pastikan localhost resolve ke 127.0.0.1 (IPv4) dan ::1 (IPv6).
  • Coba ping localhost.
  • Periksa /etc/hosts untuk baris entry localhost yang benar.
  • Nonaktifkan proxy network yang dapat mengganggu lalu lintas lokal.

3. Paket MariaDB/MySQL Tidak Bisa Start

Kemungkinan penyebab dan solusinya:

1. Cek error log (paling penting!): Baca /Applications/ServBay/logs/mariadb/<version>/<version>.err untuk pesan error startup. Inilah kunci identifikasi masalah.
2. File konfigurasi error:
   • File /Applications/ServBay/etc/mariadb/<version>/my.cnf keliru, parameternya tidak valid, atau jalur salah.
   • Validasi file config (jalur mysqld sesuaikan dengan versi ServBay):

     # Contoh
     /Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config

3. Port digunakan aplikasi lain: (Cek pakai lsof -i :<port> atau netstat)
4. Ruang disk tidak cukup: Pastikan partisi untuk /Applications/ServBay/db/mariadb/<version>/ dan /Applications/ServBay/logs/mariadb/<version>/ masih ada space.
5. Masalah hak akses:
   • User yang menjalankan MariaDB/MySQL (umumnya user sistem ServBay seperti _mysql) tidak punya hak ke file config, data, atau log. Jika pernah mengubah hak akses di /Applications/ServBay, check kembali:

     ls -ld /Applications/ServBay/db/mariadb/<version>
     ls -l /Applications/ServBay/etc/mariadb/<version>/my.cnf
     ls -ld /Applications/ServBay/logs/mariadb/<version>

     Pastikan user database punya hak baca/tulis/eksekusi.
6. File data corrupt: (Lihat bagian “Crash Database/Kerusakan Data”). Jika shutdown tidak normal, file data bisa rusak sehingga gagal start.

Setelah diperbaiki:

• Coba restart paket: servbayctl restart mariadb <version>

4. Masalah Hak Akses/Pengguna

Setelah berhasil terhubung ke server database, error bisa muncul akibat kesalahan username, password atau hak akses (misal Access denied).

Kemungkinan penyebab dan solusi:

• Username atau password salah: Pastikan data login benar. ServBay menyediakan fitur reset password root.
• Batasan host user: User bisa dibatasi hanya koneksi dari host tertentu seperti '<username>'@'localhost'. Koneksi dari '127.0.0.1' bisa gagal, dan sebaliknya. '%' berarti akses dari semua host.
• Hak akses kurang: User bisa jadi belum di-grant akses ke database atau operasi tertentu (SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, dll.).
• Cek hak akses user:
  • Login sebagai root atau user dengan hak cukup:

    mysql -u root -p

  • Di prompt SQL, cek grant user:

    SHOW GRANTS FOR '<username>'@'<hostname>';
    -- Contoh, cek permission user 'webapp' untuk 'localhost':
    SHOW GRANTS FOR 'webapp'@'localhost';
    -- Cek permission user 'admin' untuk semua host:
    SHOW GRANTS FOR 'admin'@'%';

  • Jika perlu, modifikasi hak dengan perintah GRANT/REVOKE atau buat user baru lalu beri hak yang sesuai.

5. Masalah Performa

Performa database turun bisa memperlambat respon aplikasi.

Kemungkinan penyebab dan solusi:

1. Query lambat: Kode query tidak efisien, kekurangan index, atau execution plan buruk.
   • Aktifkan slow query log: Di my.cnf, aktifkan slow_query_log=1, long_query_time=1, dan set file log. Restart paket lalu analisa query lambat-nya.
   • Pakai EXPLAIN: Taruh keyword EXPLAIN sebelum query lambat untuk analisa penggunaan index, jumlah row, dsb.

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

   • Optimasi query: Berdasarkan EXPLAIN, perbaiki query agar memanfaatkan index dan hindari operasi berat/kurang efisien.
2. Kurang/tidak tepat index: Kolom yang sering dipakai untuk WHERE, ORDER BY, atau GROUP BY tidak ada index.
   • Analisa struktur tabel & query utama: Cari kolom yang perlu diberi index.
   • Buat index:

     CREATE INDEX idx_column_name ON your_table_name(column_name);

     Catatan: Index mempercepat baca tapi bisa memperlambat tulis dan makan ruang disk.
3. Setting cache tidak optimal: Parameter cache seperti innodb_buffer_pool_size, key_buffer_size (MyISAM) terlalu kecil/besar di my.cnf.
   • Atur parameter di my.cnf: Sesuaikan dengan RAM dan penggunaan database Anda. innodb_buffer_pool_size sebaiknya 50-70% dari RAM jika server khusus database.

     [mysqld]
     # Contoh, sesuaikan ukuran sesuai kebutuhan
     innodb_buffer_pool_size = 2G
     # Jika banyak MyISAM:
     # key_buffer_size = 256M

4. Batasan hardware: CPU penuh, RAM kurang, atau disk I/O bottleneck. Monitor pakai Activity Monitor macOS atau command line top/htop.

6. Crash Database atau Kerusakan Data

Database gagal start, sering crash, atau error akses data, bisa disebabkan file data yang rusak.

Kemungkinan penyebab dan solusi:

1. Cek error log: Selalu baca /Applications/ServBay/logs/mariadb/<version>/<version>.err untuk penyebab crash atau corrupt, misal error InnoDB, file system, atau hardware.
2. Kerusakan hardware: Disk atau RAM bermasalah, cek log sistem (Console.app) atau gunakan tool diagnosis hardware.
3. Bug/konflik software: Versi MariaDB/MySQL tertentu bisa bug atau konflik dengan software lain.
4. Konfigurasi error: Setting my.cnf keliru bisa menyebabkan crash.
5. Shutdown paksa: Menutup MariaDB/MySQL tanpa shutdown normal (misal matikan aplikasi ServBay atau kill proses) bisa membuat file data tidak konsisten.

Solusi:

• Coba restart dengan aman: Mulai ulang paket dari aplikasi ServBay atau via CLI: servbayctl restart mariadb <version>. Kadang server dapat self-recover.
• Pakai mysqlcheck untuk cek & repair tabel: Tools ini mengecek integritas tabel dan mereparasi masalah (khususnya MyISAM).

  # Gunakan my.cnf ServBay dan user root untuk cek semua database
  mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases
  # Untuk MyISAM, bisa repair otomatis
  # mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases

  Catatan: --auto-repair hanya untuk MyISAM. Untuk InnoDB, --check hanya untuk deteksi, repair butuh tindakan ekstra (lihat recovery InnoDB di bawah).
• Paksakan InnoDB recovery (innodb_force_recovery): Jika InnoDB gagal start, bisa dicoba recovery paksa. Risiko data hilang tinggi! Gunakan hanya untuk ekspor darurat data!
  1. Backup dulu directory data! Copy /Applications/ServBay/db/mariadb/<version>/ ke tempat lain.
  2. Edit file config /Applications/ServBay/etc/mariadb/<version>/my.cnf.
  3. Di bagian [mysqld] tambahkan: innodb_force_recovery = N (N mulai dari 1, naik bertahap hingga 6 jika gagal. Uji tiap level secara bertahap).
  4. Start MariaDB/MySQL: servbayctl start mariadb <version>.
  5. Jika bisa start (meski mode read-only), SEGERA mysqldump semua data!

     mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --all-databases --routines --triggers --events > /path/to/your_emergency_backup.sql

     Pastikan file backup wajar dan berhasil.
  6. Hentikan MariaDB/MySQL: servbayctl stop mariadb <version>.
  7. Edit my.cnf, hapus/comment baris innodb_force_recovery = N.
  8. Recovery dari backup: Biasanya berarti inisialisasi data directory baru (rename/delete directory lama), kemudian import file backup ke database baru.
• Restore dari backup: Jika repair fail atau data tidak konsisten, restore dari backup terbaru yang andal. File backup ServBay biasanya ada di: /Applications/ServBay/backup/mariadb/<version>/.
  • Contoh restore (ke database <target_database_name>):

    # Pastikan database tujuan sudah ada lebih dulu
    # mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
    
    # Import backup
    mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

    Perhatian: Ganti <version> dengan versi MariaDB/MySQL yang benar.

7. Masalah Backup & Restore

Menggunakan fitur backup ServBay atau mysqldump manual kadang menimbulkan masalah:

Kemungkinan penyebab dan solusi:

• File backup tidak lengkap/rusak:
  • Cek ukuran file backup (ls -lh /path/to/your_backup.sql), apakah sesuai volume data.
  • Gunakan teks editor / less untuk cek isi file (less /path/to/your_backup.sql), pastikan berisi SQL valid.
  • Jika backup manual lewat mysqldump, cek ada error saat backup. Jika backup ServBay, periksa log aplikasi.
• Salah perintah restore:
  • Username/password/database tujuan salah.
  • Hak akses user kurang.
  • Error SQL jika import dari versi berbeda (MySQL ke MariaDB atau sebaliknya), mungkin ada syntax/fitur tidak kompatibel.
• Masalah foreign key: Urutan import bisa menyebabkan gagal foreign key, karena tabel referensi belum ada. Solusi: matikan sementara cek foreign key sebelum import, hidupkan lagi setelahnya:

  -- Sebelum import
  SET foreign_key_checks = 0;
  -- Import file seperti:
  source /path/to/your_backup.sql; -- Untuk client mysql
  -- Atau pakai command line: mysql ... < /path/to/your_backup.sql
  
  -- Setelah import
  SET foreign_key_checks = 1;

  Perhatian: Mematikan ini bisa membuat data tidak konsisten, hanya untuk fase import.
• Masalah karakter set/collation: Data/definisi dalam file backup pakai charset/collation berbeda bisa menyebabkan error atau data acak. Pastikan basis data/kolom sesuai (utf8mb4, dsb.).

Contoh restore database yang benar:

# Misal file backup untuk database tertentu
# Pastikan database tujuan (<target_database_name>) sudah ada
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# Import dengan config, username, password, dan nama database yang benar
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

# Jika backup untuk semua database (--all-databases), tidak perlu nama database
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Catatan: Ganti <version> sesuai paket MariaDB/MySQL yang digunakan. Fitur backup bawaan ServBay biasanya menghasilkan file yang siap restore.

8. Bug Khusus: Gagal Start MariaDB 11.5.1 InnoDB (ib_logfile0 was not found / Missing FILE_CHECKPOINT)

Ini adalah bug serius pada MariaDB 11.5.1 yang bisa memblokir full inisialisasi InnoDB atau pemulihan log sehingga database gagal start.

Ciri error log:

Pada /Applications/ServBay/logs/mariadb/11.5/11.5.err, Anda mungkin menemukan:

[ERROR] InnoDB: File /Applications/ServBay/db/mariadb/11.5/ib_logfile0 was not found
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

atau:

[ERROR] InnoDB: Missing FILE_CHECKPOINT(xxxxx) at xxxxx
[ERROR] InnoDB: Log scan aborted at LSN xxxxx
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

Artinya InnoDB gagal menemukan/melakukan proses pada file log, membuat engine gagal inisialisasi.

Solusi (melibatkan migrasi data - backup dulu!):

Ini bug kritis yang sulit diperbaiki langsung. Cara terbaik adalah startup paksa untuk ekspor data lalu migrasi ke MariaDB versi stabil.

1. Coba recovery agar bisa backup data (berisiko!):
   • Edit file config MariaDB 11.5: /Applications/ServBay/etc/mariadb/11.5/my.cnf.
   • Di bagian [mysqld] tambah: innodb_force_recovery = 6
   • Mulai MariaDB 11.5 via ServBay/CLI: servbayctl start mariadb 11.5
   • Jika berhasil start (walau fitur terbatas), SEGERA backup seluruh database dengan mysqldump!

     mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/11.5/my.cnf -u root -p --all-databases --routines --triggers --events > /Applications/ServBay/backup/mariadb/11.5/mariadb_11.5_emergency_backup.sql

     Pastikan backup berhasil dan ukurannya masuk akal!
2. Stop dan proses data directory versi bermasalah:
   • Stop MariaDB 11.5: servbayctl stop mariadb 11.5
   • Edit file my.cnf, hapus atau comment baris innodb_force_recovery ...