Cara Mengatasi Database Connection Refused pada Laravel

Apa Itu Database Connection Refused?

Error ini muncul ketika Laravel mencoba terhubung ke database, tetapi koneksi ditolak oleh server database.

Contohnya:

SQLSTATE[HY000] [2002] Connection refused

Artinya Laravel sudah mencoba melakukan koneksi, tetapi database tidak menerima koneksi tersebut.

1. Periksa File .env

Hal pertama yang perlu diperiksa adalah konfigurasi database:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nama_database
DB_USERNAME=nama_user
DB_PASSWORD=password

Untuk PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=nama_database
DB_USERNAME=nama_user
DB_PASSWORD=password

Pastikan:

• Nama database benar.

• Username benar.

• Password benar.

• Port sesuai.

• Host sesuai dengan lokasi database.

2. Pastikan Database Berjalan

Pada Ubuntu, cek MySQL:

sudo systemctl status mysql

Jika belum berjalan:

sudo systemctl start mysql

Untuk PostgreSQL:

sudo systemctl status postgresql

Kemudian:

sudo systemctl start postgresql

Jika database berhenti, Laravel tentu tidak dapat membuat koneksi.

3. Periksa Port Database

MySQL biasanya menggunakan:

3306

PostgreSQL biasanya menggunakan:

5432

Cek port yang sedang digunakan:

sudo ss -lntp | grep 3306

Untuk PostgreSQL:

sudo ss -lntp | grep 5432

Jika tidak ada hasil, kemungkinan database belum listening pada port tersebut.

4. Jangan Selalu Menggunakan localhost

Pada beberapa lingkungan server, perbedaan antara:

DB_HOST=localhost

dan:

DB_HOST=127.0.0.1

dapat berpengaruh terhadap cara koneksi dibuat.

Untuk koneksi TCP lokal, coba:

DB_HOST=127.0.0.1

Jika database menggunakan Unix socket, konfigurasi dapat berbeda.

5. Bersihkan Cache Konfigurasi Laravel

Laravel dapat menggunakan konfigurasi yang sudah dicache.

Setelah mengubah .env, jalankan:

php artisan optimize:clear

Kemudian coba:

php artisan migrate:status

Jika koneksi berhasil, Laravel sudah dapat berkomunikasi dengan database.

6. Pastikan Database Bisa Diakses Manual

Untuk MySQL:

mysql \
-h 127.0.0.1 \
-P 3306 \
-u nama_user \
-p

Untuk PostgreSQL:

psql \
-h 127.0.0.1 \
-p 5432 \
-U nama_user \
-d nama_database

Jika koneksi manual juga gagal, masalah kemungkinan berada pada database atau konfigurasi server, bukan Laravel.

7. Periksa Docker

Jika Laravel dan database berjalan di Docker, jangan gunakan:

DB_HOST=127.0.0.1

untuk mengakses container database dari container Laravel.

Gunakan nama service Docker.

Contoh:

services:
  app:
    ...
  
  mysql:
    image: mysql:8

Maka:

DB_HOST=mysql
DB_PORT=3306

Karena Laravel harus mengakses service database melalui network Docker.

Contoh:

Laravel Container
       ↓
    mysql:3306
       ↓
MySQL Container

8. Periksa Docker Container

Jalankan:

docker ps

Pastikan container database sedang berjalan.

Jika tidak:

docker compose up -d

Kemudian periksa log:

docker compose logs mysql

Nama service dapat berbeda sesuai konfigurasi docker-compose.yml.

9. Periksa Konfigurasi MySQL

Jika database berada pada server lain, MySQL harus menerima koneksi dari server Laravel.

Periksa konfigurasi:

/etc/mysql/mysql.conf.d/mysqld.cnf

Cari:

bind-address

Konfigurasi seperti:

bind-address = 127.0.0.1

hanya menerima koneksi lokal.

Jika database memang harus menerima koneksi dari server aplikasi lain, konfigurasi network perlu disesuaikan dengan kebutuhan keamanan.

Jangan membuka database ke seluruh internet tanpa firewall dan pembatasan akses.

10. Periksa Firewall

Jika database berada di server berbeda, periksa firewall.

Contohnya menggunakan UFW:

sudo ufw status

Jika diperlukan, akses port database sebaiknya dibatasi hanya dari IP server aplikasi.

Hindari membuka:

3306

atau:

5432

ke seluruh internet tanpa alasan yang jelas.

11. Periksa Username dan Permission

Jika database sudah berjalan tetapi Laravel masih tidak dapat login, periksa user database.

MySQL:

SHOW GRANTS FOR 'nama_user'@'localhost';

Jika Laravel berada pada server berbeda, host database user dapat berbeda dari localhost.

Pastikan user memiliki permission yang sesuai terhadap database aplikasi.

12. Periksa Database Host pada Production

Konfigurasi development:

DB_HOST=127.0.0.1

belum tentu sama dengan production.

Contohnya:

Laravel Server
    ↓
Database Server
192.168.1.20

Maka:

DB_HOST=192.168.1.20

Jika menggunakan cloud database, gunakan hostname atau endpoint yang diberikan oleh provider.

13. Periksa Port Custom

Database tidak selalu menggunakan port default.

Misalnya MySQL menggunakan:

3307

Maka:

DB_PORT=3307

Pastikan port pada .env sama dengan port yang digunakan database.

14. Jalankan Tes dari Laravel

Setelah konfigurasi diperbaiki:

php artisan migrate:status

atau:

php artisan tinker

Kemudian:

DB::connection()->getPdo();

Jika tidak menghasilkan error, Laravel sudah berhasil membuat koneksi database.

15. Periksa Log Laravel

Jika masih gagal, periksa:

storage/logs/laravel.log

Contoh:

tail -f storage/logs/laravel.log

Log dapat membantu mengetahui apakah masalah berasal dari:

• Host.

• Port.

• Username.

• Password.

• Database.

• Network.

• Permission.

Perbedaan Connection Refused dan Access Denied

Keduanya sering dianggap sama, padahal berbeda.

Connection Refused

Contohnya:

SQLSTATE[HY000] [2002] Connection refused

Biasanya berkaitan dengan:

• Database tidak berjalan.

• Port salah.

• Host salah.

• Firewall.

• Docker network.

• Database tidak listening.

Access Denied

Contohnya:

Access denied for user

Biasanya berkaitan dengan:

• Username salah.

• Password salah.

• Permission database.

• Host user database tidak sesuai.

Jadi, jangan langsung mengganti password ketika error yang muncul adalah “Connection refused”.

Checklist Troubleshooting

Urutan pemeriksaan yang praktis:

1. Periksa .env
       ↓
2. Periksa database berjalan
       ↓
3. Periksa DB_HOST
       ↓
4. Periksa DB_PORT
       ↓
5. Tes koneksi manual
       ↓
6. Clear Laravel config
       ↓
7. Periksa Docker
       ↓
8. Periksa firewall
       ↓
9. Periksa database permission
       ↓
10. Periksa laravel.log

Contoh Konfigurasi Laravel Production

Contoh MySQL:

APP_ENV=production
APP_DEBUG=false

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=production_db
DB_USERNAME=production_user
DB_PASSWORD=********

Setelah mengubah konfigurasi:

php artisan optimize:clear
php artisan config:cache

Jangan menyimpan password database langsung di repository Git.

Jika Menggunakan Laravel + Nginx + MySQL

Arsitektur sederhananya:

Internet
   ↓
Nginx
   ↓
PHP-FPM
   ↓
Laravel
   ↓
MySQL

Jika Laravel menghasilkan Connection refused, periksa MySQL terlebih dahulu sebelum mengubah konfigurasi Nginx.

Nginx dan PHP-FPM biasanya bukan penyebab langsung dari koneksi database yang ditolak.

Jika Menggunakan Laravel + Docker

Arsitekturnya:

Browser
   ↓
Nginx
   ↓
Laravel Container
   ↓
MySQL Container

Pastikan:

DB_HOST=mysql
DB_PORT=3306

sesuai dengan nama service database pada Docker Compose.

Pengembangan dan Troubleshooting Laravel Bersama Ovla Media

Ovla Media dapat membantu pengembangan dan maintenance aplikasi Laravel, termasuk:

1. Konfigurasi Laravel production.

2. Setup MySQL dan PostgreSQL.

3. Docker Laravel.

4. Nginx dan PHP-FPM.

5. Optimasi database.

6. Redis.

7. Laravel Queue.

8. Backup database.

9. Monitoring server.

10. Deployment aplikasi.

Dengan konfigurasi server yang tepat, masalah koneksi database dapat ditemukan lebih cepat dan aplikasi menjadi lebih stabil.

Kesimpulan

Error Database Connection Refused pada Laravel umumnya bukan disebabkan oleh kode aplikasi, tetapi karena Laravel tidak dapat terhubung ke server database.

Periksa secara berurutan:

1. .env.

2. Status database.

3. Host.

4. Port.

5. Docker.

6. Firewall.

7. Permission.

8. Network.

9. Cache konfigurasi Laravel.

10. Log aplikasi.

Perintah yang paling berguna untuk memulai pemeriksaan adalah:

php artisan optimize:clear
php artisan migrate:status

Jika database dapat diakses secara manual tetapi Laravel masih gagal, fokus pemeriksaan berikutnya adalah konfigurasi .env, cache konfigurasi, dan environment tempat aplikasi Laravel berjalan.