Overview
Masalah yang diselesaikan. Koneksi database adalah langkah pertama yang sering gagal: pesan SQLSTATE[HY000] yang tidak jelas, Access denied, Unknown database, atau migrasi yang berhenti dengan Specified key was too long. Pemula juga bingung memilih antara MySQL dan MariaDB, dan apakah Laravel memperlakukannya berbeda.
Hasil akhir:
Database dan user khusus aplikasi sudah dibuat dengan hak akses yang tepat.
Laravel terhubung ke MySQL atau MariaDB, dan koneksi bisa diverifikasi.
Migrasi, seeder, dan factory berjalan.
Anda tahu cara mendiagnosis error koneksi yang paling umum.
Prerequisites
Komponen | Kebutuhan |
|---|---|
PHP | 8.3+ (Laravel 13) atau 8.2+ (Laravel 12) |
Ekstensi PHP |
|
Laravel | 12.x atau 13.x |
MySQL | 8.0 atau lebih baru (disarankan) |
MariaDB | 10.6 atau lebih baru (disarankan) |
Klien | Terminal |
Batas versi minimum resmi database yang didukung dapat lebih rendah dari rekomendasi di atas, dan bisa berubah antar versi Laravel. Cek halaman Database di dokumentasi versi Anda.
Pastikan ekstensi aktif:
php -m | Select-String pdo_mysql
pdo_mysql
Step-by-Step Tutorial
1. MySQL atau MariaDB?
Keduanya kompatibel untuk sebagian besar kebutuhan aplikasi Laravel, dan keduanya memakai pdo_mysql.
Aspek | MySQL | MariaDB |
|---|---|---|
Pengembang | Oracle | MariaDB Foundation / komunitas |
Driver Laravel |
|
|
Hosting Indonesia | Umum | Sangat umum |
Catatan | Standar de facto | Beberapa fitur (seperti tipe JSON, window function) berbeda detail implementasi |
Sejak Laravel 11, tersedia driver mariadb tersendiri di config/database.php. Disarankan memakainya bila server Anda benar-benar MariaDB, agar fitur khusus MariaDB ditangani dengan tepat.
Cara mengetahui server Anda:
mysql -u root -e "SELECT VERSION();"
+-----------------+
| VERSION() |
+-----------------+
| 10.11.8-MariaDB | ← MariaDB
+-----------------+
| 8.4.3 | ← MySQL
2. Pastikan Server Database Berjalan
Laragon: klik Start All dan pastikan MySQL aktif.
Ubuntu:
sudo systemctl status mysql # atau: mariadb
sudo systemctl start mysql
Uji koneksi:
mysql -u root -e "SELECT 1;"
3. Buat Database dan User Khusus Aplikasi
Jangan memakai root untuk aplikasi. Buat database dan user terpisah dengan hak seperlunya.
mysql -u root
CREATE DATABASE toko
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'toko_user'@'localhost' IDENTIFIED BY 'GantiDenganPasswordKuat!2026';
GRANT ALL PRIVILEGES ON toko.* TO 'toko_user'@'localhost';
FLUSH PRIVILEGES;
Pada server terpisah (database bukan di mesin yang sama), ganti 'localhost' dengan IP aplikasi atau '%' dengan pembatasan firewall.
Verifikasi:
SHOW DATABASES;
SHOW GRANTS FOR 'toko_user'@'localhost';
mysql -u toko_user -p toko -e "SELECT DATABASE();"
Catatan karakter set. utf8mb4 mendukung emoji dan seluruh karakter Unicode. Jangan memakai utf8 (alias utf8mb3) karena hanya mendukung sebagian karakter.
4. Konfigurasi .env
Untuk MySQL:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=toko
DB_USERNAME=toko_user
DB_PASSWORD="GantiDenganPasswordKuat!2026"
Untuk MariaDB:
DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=toko
DB_USERNAME=toko_user
DB_PASSWORD="GantiDenganPasswordKuat!2026"
Gunakan 127.0.0.1, bukan localhost, untuk menghindari masalah soket Unix pada sebagian konfigurasi (terutama di Linux). Apit password yang mengandung #, $, atau spasi dengan tanda kutip.
Setelah mengubah .env, bersihkan cache konfigurasi:
php artisan config:clear
5. Pahami config/database.php
'default' => env('DB_CONNECTION', 'sqlite'),
'connections' => [
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'laravel'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8mb4'),
'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
'strict' => true,
'engine' => null,
],
// 'mariadb' => [ ... struktur serupa ... ],
],
Nilai bawaan strict => true menjaga data tetap bersih (misalnya menolak string yang terlalu panjang alih-alih memotongnya diam-diam). Pertahankan.
6. Verifikasi Koneksi dari Laravel
php artisan db:show
MariaDB 10.11.8 ..................................... toko
Host .......................................... 127.0.0.1
Port ............................................... 3306
Username ................................... toko_user
Tables ..................................................... 0
Atau lewat Tinker:
php artisan tinker
> DB::connection()->getPdo();
> DB::select('select version() as v');
= [ { +"v": "10.11.8-MariaDB" } ]
Jika berhasil, Laravel sudah terhubung.
7. Jalankan Migrasi
php artisan migrate
INFO Preparing database.
Creating migration table ........................... 22.14ms DONE
INFO Running migrations.
0001_01_01_000000_create_users_table ............... 61.33ms DONE
0001_01_01_000001_create_cache_table ............... 20.08ms DONE
0001_01_01_000002_create_jobs_table ................ 41.52ms DONE
Perintah migrasi yang sering dipakai:
Perintah | Fungsi |
|---|---|
| Jalankan migrasi yang belum dijalankan |
| Lihat status tiap migrasi |
| Batalkan batch terakhir |
| Hapus semua tabel, migrasi ulang, dan seed (hanya lokal) |
| Ringkasan database |
| Detail satu tabel |
8. Buat Tabel Sendiri
php artisan make:model Product -mf
// database/migrations/xxxx_create_products_table.php
public function up(): void
{
Schema::create('products', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->string('sku', 50)->unique();
$table->unsignedBigInteger('price');
$table->unsignedInteger('stock')->default(0);
$table->foreignId('category_id')->nullable()->constrained()->nullOnDelete();
$table->timestamps();
$table->index('name');
});
}
public function down(): void
{
Schema::dropIfExists('products');
}
php artisan migrate
php artisan db:table products
9. Isi Data Uji dengan Factory dan Seeder
// database/factories/ProductFactory.php
public function definition(): array
{
return [
'name' => fake()->words(3, true),
'sku' => strtoupper(fake()->unique()->bothify('SKU-####??')),
'price' => fake()->numberBetween(10, 500) * 1000,
'stock' => fake()->numberBetween(0, 100),
];
}
// database/seeders/DatabaseSeeder.php
public function run(): void
{
\App\Models\Product::factory()->count(50)->create();
}
php artisan db:seed
10. Uji Pembacaan dan Penulisan
> App\Models\Product::count();
= 50
> App\Models\Product::where('stock', '>', 50)->orderBy('price')->first();
> App\Models\Product::create(['name' => 'Uji', 'sku' => 'UJI-1', 'price' => 10000, 'stock' => 1]);
Lihat query yang dijalankan:
> DB::enableQueryLog();
> App\Models\Product::where('stock', '>', 50)->get();
> DB::getQueryLog();
11. Koneksi ke Database Lain (Opsional)
Tambahkan koneksi baru di config/database.php, misalnya untuk database laporan:
'report' => [
'driver' => 'mysql',
'host' => env('REPORT_DB_HOST', '127.0.0.1'),
'database' => env('REPORT_DB_DATABASE'),
'username' => env('REPORT_DB_USERNAME'),
'password' => env('REPORT_DB_PASSWORD'),
'charset' => 'utf8mb4',
'collation'=> 'utf8mb4_unicode_ci',
],
DB::connection('report')->table('sales')->count();
// pada model:
protected $connection = 'report';
12. Backup dan Pemulihan Sederhana
mysqldump -u toko_user -p toko > backup-toko.sql
mysql -u toko_user -p toko < backup-toko.sql
Di PowerShell, operator < untuk impor tidak berfungsi seperti di CMD. Gunakan CMD, atau:
Get-Content backup-toko.sql | mysql -u toko_user -p toko
Troubleshooting
Gejala | Penyebab | Solusi |
|---|---|---|
| Server database belum berjalan, atau port salah | Start MySQL/MariaDB, cek |
| Memakai | Pakai |
| Username atau password salah; atau tanda khusus di password | Periksa kredensial, beri kutip password, uji manual dengan |
| Database belum dibuat atau salah nama |
|
| User belum diberi hak pada database |
|
| Ekstensi | Aktifkan di |
| Server lama (MySQL < 5.7 / MariaDB < 10.2) dengan | Upgrade database; atau (tidak disarankan) kurangi panjang string indeks |
Perubahan | Cache konfigurasi |
|
| Migrasi diulang pada tabel yang sudah ada | Cek |
| Pelanggaran foreign key (hapus induk atau anak tanpa induk) | Urutkan operasi, atau gunakan |
| Mode strict menolak data panjang | Perbesar kolom lewat migrasi, atau validasi panjang input |
| Kolom atau tabel bukan | Ubah charset database dan tabel ke |
| Koneksi tidak dilepas, atau limit rendah | Periksa proses panjang/worker, naikkan |
Koneksi lambat saat awal | DNS reverse lookup MySQL | Tambahkan |
Memeriksa server dari terminal:
mysql -u toko_user -p -e "SHOW VARIABLES LIKE 'character_set%';"
mysql -u toko_user -p -e "SHOW PROCESSLIST;"
Best Practices
Keamanan
Gunakan user database khusus dengan hak terbatas pada satu database. Hindari
rootdi aplikasi.Password kuat, disimpan di
.env, dan tidak pernah di-commit.Batasi akses jaringan: MySQL/MariaDB hanya mendengarkan
127.0.0.1bila satu server, atau izinkan hanya IP aplikasi lewat firewall.Selalu gunakan Eloquent atau Query Builder dengan parameter terikat (binding). Jangan menyambung string SQL dari input pengguna.
Backup rutin, dan uji pemulihannya.
Performa
Tambahkan index pada kolom yang sering dipakai di
WHERE,ORDER BY, dan foreign key.Hindari N+1 dengan eager loading dan aktifkan
Model::preventLazyLoading()saat pengembangan.Gunakan paginasi, dan jangan memakai
->get()untuk tabel besar.Simpan uang sebagai integer (
unsignedBigInteger), bukanfloat.Aktifkan slow query log di server untuk menemukan query lambat.
Maintainability
Semua perubahan skema lewat migrasi. Jangan mengubah tabel manual di production.
Jangan mengedit migrasi yang sudah berjalan di production. Buat migrasi baru.
Tulis method
down()agar rollback memungkinkan.Gunakan
utf8mb4dan collation yang konsisten di seluruh tabel.Dokumentasikan versi database yang dipakai di
README.md, dan samakan antara lokal dan production.Bila memakai MariaDB, gunakan driver
mariadb. Bila MySQL,mysql.
Related Articles
Panduan Lengkap Instalasi Laravel di Windows Menggunakan Laragon
Deploy Laravel ke Ubuntu VPS dengan Nginx, PHP-FPM, dan MySQL
Last Tested
Catatan jujur: disusun dari dokumentasi resmi Laravel, MySQL, dan MariaDB, tetapi belum dijalankan ulang terhadap server database nyata oleh penulis. Terutama verifikasi nama driver
mariadbdan keluarandb:showpada versi Laravel Anda.
Komponen | Versi acuan penulisan | Versi saat Anda menguji |
|---|---|---|
PHP | 8.3.x ( | |
Laravel | 13.x (kompatibel dengan 12.x) | |
MySQL | 8.x | |
MariaDB | 10.11.x | |
Tanggal uji |