Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Database / Cara Menghubungkan Laravel den...
Database

Cara Menghubungkan Laravel dengan MySQL dan MariaDB dari Nol

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
8 min read
10 views

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

pdo_mysql (aktif)

Laravel

12.x atau 13.x

MySQL

8.0 atau lebih baru (disarankan)

MariaDB

10.6 atau lebih baru (disarankan)

Klien

Terminal mysql, HeidiSQL, atau phpMyAdmin

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

mysql

mariadb (atau mysql)

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

php artisan migrate

Jalankan migrasi yang belum dijalankan

php artisan migrate:status

Lihat status tiap migrasi

php artisan migrate:rollback

Batalkan batch terakhir

php artisan migrate:fresh --seed

Hapus semua tabel, migrasi ulang, dan seed (hanya lokal)

php artisan db:show

Ringkasan database

php artisan db:table users

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

SQLSTATE[HY000] [2002] No connection could be made because the target machine actively refused it

Server database belum berjalan, atau port salah

Start MySQL/MariaDB, cek DB_PORT

SQLSTATE[HY000] [2002] Connection refused di Linux

Memakai localhost dengan soket yang tidak ada

Pakai DB_HOST=127.0.0.1

SQLSTATE[HY000] [1045] Access denied for user

Username atau password salah; atau tanda khusus di password

Periksa kredensial, beri kutip password, uji manual dengan mysql -u ... -p

SQLSTATE[HY000] [1049] Unknown database 'toko'

Database belum dibuat atau salah nama

CREATE DATABASE toko ...

SQLSTATE[HY000] [1044] Access denied ... to database

User belum diberi hak pada database

GRANT ALL PRIVILEGES ON toko.* TO ...; FLUSH PRIVILEGES;

could not find driver

Ekstensi pdo_mysql belum aktif

Aktifkan di php.ini atau menu ekstensi Laragon, lalu restart

Specified key was too long; max key length is 1000 bytes

Server lama (MySQL < 5.7 / MariaDB < 10.2) dengan utf8mb4

Upgrade database; atau (tidak disarankan) kurangi panjang string indeks

Perubahan .env tidak terbaca

Cache konfigurasi

php artisan config:clear

Base table or view already exists

Migrasi diulang pada tabel yang sudah ada

Cek migrate:status; di lokal gunakan migrate:fresh

Integrity constraint violation: 1451/1452

Pelanggaran foreign key (hapus induk atau anak tanpa induk)

Urutkan operasi, atau gunakan cascadeOnDelete() / nullOnDelete()

Data too long for column

Mode strict menolak data panjang

Perbesar kolom lewat migrasi, atau validasi panjang input

Incorrect string value (emoji gagal tersimpan)

Kolom atau tabel bukan utf8mb4

Ubah charset database dan tabel ke utf8mb4

Too many connections

Koneksi tidak dilepas, atau limit rendah

Periksa proses panjang/worker, naikkan max_connections secara wajar

Koneksi lambat saat awal

DNS reverse lookup MySQL

Tambahkan skip-name-resolve di konfigurasi server database

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 root di aplikasi.

  • Password kuat, disimpan di .env, dan tidak pernah di-commit.

  • Batasi akses jaringan: MySQL/MariaDB hanya mendengarkan 127.0.0.1 bila 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), bukan float.

  • 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 utf8mb4 dan 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

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 mariadb dan keluaran db:show pada versi Laravel Anda.

Komponen

Versi acuan penulisan

Versi saat Anda menguji

PHP

8.3.x (pdo_mysql aktif)

Laravel

13.x (kompatibel dengan 12.x)

MySQL

8.x

MariaDB

10.11.x

Tanggal uji

Bagikan artikel:

Artikel lainnya