Server Solusi – Error database connection failed bisa muncul ketika website atau aplikasi yang dikelola melalui CyberPanel tidak dapat terhubung ke database. Pada website WordPress, pesan yang sering terlihat adalah Error establishing a database connection. Sementara itu, aplikasi lain mungkin menampilkan pesan seperti Connection refused, Access denied for user, atau SQLSTATE[HY000].

Meskipun gejalanya terlihat serupa, penyebabnya bisa berbeda. MariaDB mungkin berhenti, kredensial database tidak sesuai, database tidak tersedia, atau aplikasi mencoba menghubungi server database melalui alamat maupun socket yang salah.

Karena belum ada log error atau detail server yang diberikan, penyebab spesifiknya belum bisa dipastikan. Panduan ini menggunakan skenario troubleshooting umum untuk CyberPanel pada Linux dengan MariaDB atau MySQL, bukan mengklaim bahwa satu perbaikan berlaku untuk semua instalasi.

Apa yang perlu diperiksa terlebih dahulu?

Jika CyberPanel menampilkan error koneksi database, lakukan pemeriksaan berikut secara berurutan:

1. Pastikan layanan database berjalan.

2. Periksa log MariaDB atau MySQL untuk menemukan penyebab kegagalan.

3. Pastikan nama database, username, password, dan host pada konfigurasi aplikasi benar.

4. Uji koneksi menggunakan kredensial aplikasi.

5. Periksa kapasitas disk, memori, socket, dan port database jika masalah belum teratasi.

Jangan langsung me-restart server atau mengganti password database sebelum memeriksa log. Jika masalah berasal dari disk penuh atau database yang gagal melakukan recovery, perubahan kredensial tidak akan menyelesaikannya.

Gejala dan Kemungkinan Penyebab Database Connection Failed

Sebelum mengubah konfigurasi, perhatikan pesan error yang muncul. Pesan tersebut sering memberikan petunjuk awal tentang bagian yang bermasalah.

Perbedaan antara kegagalan koneksi dan kegagalan autentikasi sangat penting. Pesan Access denied biasanya menunjukkan server database sudah menerima koneksi, tetapi menolak autentikasi atau akses yang diminta. Sebaliknya, Connection refused mengarah pada masalah koneksi atau listener.

Baca JugaCara Mengatasi CyberPanel DNS Tidak Berfungsi

Langkah Diagnosis Database di CyberPanel

1. Periksa status MariaDB

CyberPanel umumnya menggunakan MariaDB untuk pengelolaan database website, tetapi nama service dan implementasi dapat berbeda sesuai instalasi.

Jalankan perintah berikut melalui SSH:

sudo systemctl status mariadb

Perhatikan bagian Active pada hasilnya.

• Jika statusnya active (running), service sedang berjalan. Lanjutkan dengan menguji koneksi dan membaca log.

• Jika statusnya failed, periksa alasan kegagalan sebelum mencoba menjalankan ulang service.

• Jika service tidak ditemukan, pastikan nama service dan paket database yang digunakan pada instalasi tersebut.

Untuk melihat pesan terbaru dari systemd:

sudo journalctl -u mariadb -n 100 --no-pager

Perintah ini menampilkan 100 baris log terakhir milik service MariaDB. Cari pesan yang menunjukkan kegagalan startup, masalah konfigurasi, kesalahan akses file, atau kegagalan membaca data.

Dokumentasi MariaDB merekomendasikan pemeriksaan journal untuk menelusuri kegagalan service.

2. Periksa kapasitas disk dan memori

Database bisa gagal beroperasi ketika ruang disk tidak mencukupi. Kondisi tersebut juga dapat menghambat penulisan log, temporary file, dan perubahan data.

Periksa kapasitas filesystem:

df -h

Perhatikan partisi yang menampung direktori data database, log, dan file sementara.

Kemudian periksa penggunaan memori:

free -h

Jika disk hampir penuh, identifikasi file atau direktori yang menggunakan ruang terbesar sebelum menghapus apa pun. Jangan menghapus file database, binary log, atau file InnoDB secara manual untuk mengosongkan ruang.

Jika service gagal setelah penggunaan memori meningkat, periksa juga log kernel untuk kemungkinan proses yang dihentikan karena kehabisan memori:

sudo journalctl -k -n 100 --no-pager

Cari pesan seperti Out of memory atau Killed process. Jika tidak ada indikasi tersebut, lanjutkan pemeriksaan ke konfigurasi dan koneksi database.

3. Uji koneksi database secara langsung

Jika MariaDB berjalan, langkah berikutnya adalah memastikan klien database bisa terhubung.

Pada instalasi yang mendukung autentikasi administratif melalui Unix socket, kamu dapat mencoba:

sudo mariadb -e "SELECT VERSION();"

Jika perintah berhasil, database merespons query lokal dengan hak akses yang digunakan oleh perintah tersebut.

Jika gagal, baca pesan error yang ditampilkan. Pesan mengenai socket, autentikasi, atau koneksi dapat membantu menentukan langkah berikutnya.

Baca JugaCara Mengatasi OpenLiteSpeed Failed to Start di CyberPanel

Jika binary mariadb tidak tersedia, instalasi mungkin menggunakan klien mysql. Kamu bisa memeriksa ketersediaannya:

command -v mariadbcommand -v mysql

Jangan menyimpulkan bahwa seluruh koneksi aplikasi berfungsi hanya karena query administratif berhasil. Akun aplikasi mungkin menggunakan username, password, host, dan privilege yang berbeda.

Cara Memperbaiki CyberPanel Database Connection Failed

1. Jalankan kembali MariaDB jika service berhenti

Jika pemeriksaan menunjukkan bahwa MariaDB berhenti dan tidak ada indikasi masalah serius pada data atau konfigurasi, kamu dapat mencoba menjalankannya kembali:

sudo systemctl start mariadb

Setelah itu, periksa statusnya:

sudo systemctl status mariadb

Jika service berhasil berjalan, uji kembali koneksi database dan website.

Namun, jika service langsung berhenti atau gagal startup, jangan mengulang perintah tersebut terus-menerus. Periksa log untuk menemukan penyebabnya terlebih dahulu. Database yang gagal karena disk penuh, file data bermasalah, atau konfigurasi tidak valid membutuhkan penanganan sesuai penyebab.

Perintah di atas hanya memulai service yang berhenti; perintah tersebut bukan solusi untuk semua jenis kegagalan database.

2. Periksa konfigurasi database pada aplikasi

Jika MariaDB aktif tetapi website tetap menampilkan error koneksi, periksa konfigurasi aplikasi.

Untuk WordPress, file yang biasanya perlu diperiksa adalah wp-config.php di direktori instalasi WordPress.

Bagian konfigurasi yang relevan antara lain:

define( 'DB_NAME', 'nama_database' );define( 'DB_USER', 'username_database' );define( 'DB_PASSWORD', 'password_database' );define( 'DB_HOST', 'localhost' );

Nilai di atas hanyalah contoh. Gunakan nilai aktual dari konfigurasi website dan database yang tersedia di server.

Pastikan:

• DB_NAME sesuai dengan nama database yang sebenarnya.

• DB_USER merupakan akun database yang benar.

• DB_PASSWORD sesuai dengan password akun tersebut.

• DB_HOST sesuai dengan alamat koneksi yang digunakan oleh database.

Jangan mengubah DB_HOST menjadi 127.0.0.1 atau localhost secara acak. Pada sejumlah instalasi, kedua nilai tersebut dapat menggunakan mekanisme koneksi berbeda, seperti TCP/IP dan Unix socket. Perubahan yang tidak sesuai justru dapat menyebabkan error baru.

Jika konfigurasi terlihat benar, lanjutkan dengan menguji kredensial aplikasi secara langsung.

Baca JugaCara Mengatasi CyberPanel Website Error 503 Service Unavailable

3. Pastikan akun database dan hak aksesnya sesuai

Pesan Access denied for user perlu ditangani secara berbeda dari service yang berhenti.

Akun database MariaDB dapat dibatasi berdasarkan kombinasi username dan host. Karena itu, akun user@localhost tidak selalu setara dengan akun bernama sama yang diizinkan terhubung dari host lain.

Untuk memeriksa database dan akun yang tersedia, masuk ke MariaDB menggunakan akun administratif yang memang berwenang:

sudo mariadb

Kemudian jalankan query pemeriksaan yang sesuai, misalnya:

SHOW DATABASES;SELECT User, Host FROM mysql.user;

Query pertama menampilkan database yang dapat dilihat oleh akun tersebut. Query kedua memeriksa daftar akun dan host yang tercatat di tabel sistem pada versi MariaDB yang mendukung struktur tersebut.

Jangan menampilkan atau membagikan hash password akun database. Setelah menemukan akun yang sesuai, periksa hak aksesnya sebelum melakukan perubahan.

Jika hak akses memang tidak sesuai, berikan hanya privilege yang dibutuhkan aplikasi terhadap database yang benar. Hindari memberikan akses global tanpa alasan yang jelas.

4. Periksa socket dan alamat koneksi

Jika pesan error menyebut socket seperti /var/run/mysqld/mysqld.sock, periksa apakah MariaDB berjalan dan socket tersebut tersedia.

Kamu dapat memeriksa socket yang sedang digunakan dengan:

sudo ss -lxnp | grep -i mysql

Perintah ini mencari Unix socket yang berkaitan dengan MySQL atau MariaDB. Hasilnya dapat berbeda sesuai konfigurasi dan nama socket.

Jika aplikasi menggunakan TCP/IP, periksa listener database:

sudo ss -lntp | grep ':3306'

Port 3306 merupakan port TCP yang umum digunakan MariaDB, tetapi instalasi tertentu bisa menggunakan port lain.

Jika aplikasi dan database berada pada server yang sama, periksa dahulu apakah keduanya menggunakan metode koneksi yang cocok. Jika database berada di server terpisah, periksa alamat host, rute jaringan, firewall, dan konfigurasi akses jarak jauh.

Jangan membuka port database ke seluruh internet hanya untuk mengatasi error koneksi. Jika akses remote memang diperlukan, batasi sumber koneksi dan gunakan akun dengan hak akses minimum.

Baca JugaCara Memperbaiki SSL Error di CyberPanel: Diagnosis dan Solusi

5. Periksa log error database dan CyberPanel

Jika masalah belum teratasi, gabungkan informasi dari log database dengan log aplikasi.

Pada sistem yang menggunakan systemd, kamu bisa melihat log MariaDB melalui:

sudo journalctl -u mariadb -n 100 --no-pager

CyberPanel juga memiliki log panel tersendiri. Salah satu lokasi yang digunakan adalah:

/home/cyberpanel/error-logs.txt

Lokasi ini relevan untuk masalah yang terjadi pada panel CyberPanel. Untuk kegagalan koneksi website, periksa pula log aplikasi dan log web server sesuai konfigurasi yang digunakan.

Cocokkan waktu munculnya error dengan pesan di log. Misalnya, jika website gagal setelah MariaDB berhenti, log database dapat memberikan petunjuk yang lebih langsung daripada pesan error di browser.

Jangan mengaktifkan debug secara permanen pada server produksi tanpa memahami dampaknya. Log debug dapat memuat detail internal aplikasi, sehingga akses dan penyimpanannya perlu dijaga.

Verifikasi Setelah Perbaikan

Setelah melakukan perubahan, pastikan koneksi database benar-benar pulih.

1. Periksa service database

sudo systemctl is-active mariadb

Hasil active menunjukkan service sedang aktif. Namun, status tersebut belum memastikan bahwa akun aplikasi bisa melakukan query.

2. Uji koneksi menggunakan akun aplikasi

Gunakan kredensial aplikasi yang benar dan masukkan password saat diminta, bukan dengan menuliskannya langsung pada command line:

mariadb -u username_database -p -h localhost nama_database

Ganti username, host, dan nama database sesuai konfigurasi aplikasi. Setelah berhasil masuk, kamu dapat menjalankan:

SELECT 1;

Jika query menghasilkan nilai 1, koneksi dan eksekusi query dasar berhasil menggunakan akun tersebut. Hasil ini belum membuktikan seluruh operasi aplikasi berjalan normal, tetapi membantu memastikan koneksi dasar sudah berfungsi.

3. Uji website dan periksa log terbaru

Buka kembali website yang mengalami masalah. Pastikan halaman yang sebelumnya gagal sudah dapat diakses, lalu periksa log aplikasi dan database untuk memastikan tidak ada error koneksi baru.

Jika error tetap muncul meskipun query manual berhasil, bandingkan konfigurasi aplikasi dengan parameter koneksi yang berhasil digunakan. Perbedaan host, socket, username, atau database sering menjadi petunjuk penting.

Pencegahan Database Connection Failed di CyberPanel

Beberapa langkah berikut membantu mengurangi risiko gangguan koneksi database:

• Pantau service MariaDB. Periksa status dan log ketika website tiba-tiba tidak dapat terhubung.

• Jaga kapasitas disk. Pantau filesystem yang menyimpan data dan log database.

• Simpan konfigurasi dengan aman. Lindungi file konfigurasi aplikasi yang berisi kredensial.

• Cadangkan database secara berkala. Pastikan backup tersedia dan proses pemulihannya dapat diuji.

• Hindari perubahan password tanpa sinkronisasi. Jika kredensial diubah, perbarui konfigurasi aplikasi yang menggunakannya.

• Batasi akses database. Jangan membuka port database ke publik jika aplikasi hanya memerlukan koneksi lokal.

• Catat perubahan konfigurasi. Dokumentasikan perubahan host, port, socket, dan hak akses agar troubleshooting lebih mudah.

FAQ: CyberPanel Database Connection Failed

1. Mengapa website menampilkan Error Establishing a Database Connection?

Penyebabnya bisa berupa MariaDB yang berhenti, kredensial database yang salah, database yang tidak tersedia, atau parameter koneksi yang tidak sesuai. Periksa pesan error dan log sebelum mengubah konfigurasi.

2. Apakah restart MariaDB bisa memperbaiki database connection failed?

Bisa jika masalahnya memang service berhenti atau mengalami gangguan sementara yang dapat dipulihkan. Namun, jika MariaDB gagal akibat disk penuh atau masalah data, restart saja mungkin tidak cukup dan dapat memperumit diagnosis jika dilakukan berulang kali.

3. Mengapa MariaDB aktif tetapi website tetap gagal terhubung?

Service yang aktif tidak menjamin kredensial aplikasi benar. Periksa username, password, nama database, host, socket, dan hak akses akun yang digunakan aplikasi.

4. Apakah password database perlu diganti ketika terjadi connection failed?

Tidak selalu. Ganti password hanya jika ada bukti bahwa kredensial salah atau perlu diperbarui karena alasan keamanan. Jika password diubah, pastikan konfigurasi aplikasi juga diperbarui agar tetap cocok.

5. Di mana menemukan log error CyberPanel?

Untuk log panel, salah satu lokasi yang digunakan adalah /home/cyberpanel/error-logs.txt. Untuk MariaDB, periksa journalctl -u mariadb atau lokasi log yang ditentukan oleh konfigurasi sistem. Lokasi aktual dapat berbeda menurut distribusi Linux dan instalasi.

Penutup

Saat CyberPanel atau website menampilkan database connection failed, jangan langsung mengganti password atau melakukan restart server. Mulailah dengan memeriksa status MariaDB, membaca log, menguji koneksi, dan memastikan konfigurasi aplikasi sesuai.

Jika database sudah aktif tetapi website masih gagal, fokuskan pemeriksaan pada kredensial, hak akses, serta perbedaan metode koneksi. Pendekatan ini membantu mempersempit penyebab tanpa mengubah konfigurasi yang sebenarnya tidak bermasalah.