Cara mendeteksi, memperbaiki, dan mencegah N+1 query: dari with() dasar sampai eager loading bersyarat, agregat relasi, dan test yang menjaga jumlah query tetap stabil.
Overview
Halaman daftar pesanan berjalan cepat di lokal dengan 10 data. Setelah production berisi 5.000 pesanan, halaman yang sama butuh 4 detik. Penyebab yang paling umum: N+1 query.
Contoh kode yang terlihat wajar:
$orders = Order::latest()->take(50)->get(); // 1 query
foreach ($orders as $order) {
echo $order->customer->name; // +1 query per pesanan
echo $order->items->count(); // +1 query per pesanan
}
Untuk 50 pesanan, kode ini menjalankan 1 + 50 + 50 = 101 query. Setiap query mungkin hanya 1–2 ms, tetapi totalnya menumpuk, ditambah overhead jaringan ke server database.
Hasil akhir artikel ini:
tahu cara mendeteksi N+1 secara otomatis selama development,
memperbaiki dengan
with(), eager loading bertingkat, bersyarat, dan agregat (withCount,withSum),menangani kasus yang sering terlewat: API Resource, accessor, dan relasi "terakhir",
memiliki test yang gagal bila N+1 muncul kembali.
Prerequisites
Komponen | Versi |
|---|---|
PHP | 8.3+ (disarankan 8.4) |
Laravel | 13.x (sebagian besar teknik berlaku sejak Laravel 8) |
Database | MySQL 8.0+ / PostgreSQL 15+ |
Alat bantu (opsional) |
|
Relasi yang dipakai: Order belongsTo Customer, Order hasMany OrderItem, OrderItem belongsTo Product, Product belongsToMany Category. Lihat artikel Memahami Eloquent Relationships.
Step-by-step Tutorial
Langkah 1: Buat Masalahnya Terlihat
Cara 1: Log query sementara
// routes/web.php (sementara, untuk diagnosis)
use Illuminate\Support\Facades\DB;
Route::get('/debug/orders', function () {
DB::enableQueryLog();
$orders = \App\Models\Order::latest()->take(50)->get();
foreach ($orders as $order) {
$order->customer->name;
$order->items->count();
}
return [
'total_query' => count(DB::getQueryLog()),
'contoh' => array_slice(DB::getQueryLog(), 0, 3),
];
});
{
"total_query": 101,
"contoh": [
{ "query": "select * from `orders` order by `created_at` desc limit 50" },
{ "query": "select * from `customers` where `customers`.`id` = ? limit 1" },
{ "query": "select * from `order_items` where `order_items`.`order_id` = ? ..." }
]
}
Pola query yang sama berulang dengan ID berbeda adalah tanda pasti N+1.
Cara 2: Debugbar (hanya development):
composer require fruitcake/laravel-debugbar --dev
Tab Queries menampilkan jumlah query dan menandai query duplikat.
Cara 3 (disarankan): Paksa error saat lazy loading
// app/Providers/AppServiceProvider.php
use Illuminate\Database\Eloquent\Model;
public function boot(): void
{
Model::preventLazyLoading(! $this->app->isProduction());
}
Sekarang, setiap kali relasi dimuat secara lazy di lokal atau saat test, Laravel melempar exception:
Illuminate\Database\LazyLoadingViolationException
Attempted to lazy load [customer] on model [App\Models\Order] but lazy loading is disabled.
Di production, jangan melempar error ke pengguna. Cukup catat ke log:
Model::preventLazyLoading();
Model::handleLazyLoadingViolationUsing(function (Model $model, string $relation) {
if (app()->isProduction()) {
logger()->warning('N+1 terdeteksi', ['model' => $model::class, 'relation' => $relation]);
return;
}
throw new \Illuminate\Database\LazyLoadingViolationException($model, $relation);
});
Atau aktifkan sekaligus beberapa pengaman lain (lazy loading, atribut yang tidak ada, mass assignment yang dibuang):
Model::shouldBeStrict(! $this->app->isProduction());
Langkah 2: Perbaikan Dasar dengan with()
$orders = Order::with(['customer', 'items'])
->latest()
->take(50)
->get();
select * from `orders` order by `created_at` desc limit 50
select * from `customers` where `customers`.`id` in (3, 7, 12, ...)
select * from `order_items` where `order_items`.`order_id` in (101, 102, ...)
Dari 101 query menjadi 3 query, berapa pun jumlah pesanannya.
Langkah 3: Eager Loading Bertingkat (Nested)
Halaman detail pesanan menampilkan nama produk dan kategorinya:
$orders = Order::with([
'customer',
'items.product.categories',
])->latest()->paginate(20);
Notasi titik memuat rantai relasi. Setiap level hanya menambah satu query.
Langkah 4: Ambil Kolom Seperlunya
$orders = Order::query()
->select(['id', 'code', 'customer_id', 'total', 'status', 'placed_at'])
->with('customer:id,name,email')
->latest('placed_at')
->paginate(20);
Aturan penting: kolom kunci relasi harus ikut dipilih. customer_id wajib ada di select orders, dan id wajib ada di kolom customer. Tanpa itu, Laravel tidak bisa mencocokkan hasil dan relasi akan kosong tanpa error.
Langkah 5: Eager Loading Bersyarat
Hanya muat pembayaran yang berhasil, diurutkan:
$orders = Order::with([
'payments' => fn ($q) => $q->where('status', 'success')->latest('paid_at'),
])->get();
Saring induk berdasarkan relasi dan muat relasi yang sama dengan syarat yang sama:
// Pesanan yang punya pembayaran sukses, beserta HANYA pembayaran sukses tersebut
$orders = Order::withWhereHas('payments', fn ($q) => $q->where('status', 'success'))
->get();
withWhereHas() menggabungkan whereHas() dan with() dengan kondisi yang sama, sehingga tidak perlu menulis closure dua kali.
Langkah 6: Hitung Tanpa Memuat Seluruh Relasi
Kesalahan umum: memuat semua item hanya untuk menghitung jumlahnya.
// Kurang efisien: memuat semua baris order_items ke memori
$orders = Order::with('items')->get();
$order->items->count();
$order->items->sum('quantity');
// Efisien: agregasi dikerjakan oleh database
$orders = Order::query()
->withCount('items')
->withSum('items as total_qty', 'quantity')
->withExists(['payments as is_paid' => fn ($q) => $q->where('status', 'success')])
->get();
$order->items_count; // 3
$order->total_qty; // 7
$order->is_paid; // true
Tersedia juga withAvg, withMin, withMax, dan withAggregate.
Langkah 7: Relasi "Satu Terakhir"
Daftar pelanggan beserta tanggal pesanan terakhirnya sering ditulis seperti ini:
// N+1: satu query per pelanggan
foreach (Customer::all() as $customer) {
$customer->orders()->latest()->first();
}
Gunakan relasi one of many:
// app/Models/Customer.php
public function latestOrder(): HasOne
{
return $this->hasOne(Order::class)->latestOfMany('placed_at');
}
$customers = Customer::with('latestOrder:id,customer_id,code,placed_at,total')->paginate(25);
Laravel membuat satu query dengan subquery MAX(placed_at) per pelanggan, bukan satu query per pelanggan.
Langkah 8: Lazy Eager Loading (load dan loadMissing)
Kadang model sudah diambil sebelum Anda tahu relasi apa yang dibutuhkan, misalnya di controller yang memakai route model binding:
public function show(Order $order)
{
$order->load(['customer', 'items.product']);
return new OrderResource($order);
}
Gunakan loadMissing() bila relasi mungkin sudah dimuat sebelumnya, agar tidak di-query ulang:
$order->loadMissing('customer');
Juga berlaku untuk collection dan paginator:
$orders = Order::paginate(20);
$orders->loadCount('items');
$orders->load('customer');
Langkah 9: N+1 Tersembunyi di API Resource
API Resource adalah tempat N+1 paling sering bersembunyi, karena relasinya diakses jauh dari query.
// Rawan N+1: customer diakses tanpa tahu apakah sudah dimuat
'customer' => new CustomerResource($this->customer),
Gunakan whenLoaded, whenCounted, dan whenAggregated agar Resource hanya menampilkan data yang memang sudah dimuat:
// app/Http/Resources/OrderResource.php
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'code' => $this->code,
'status' => $this->status,
'total' => $this->total,
'placed_at' => $this->placed_at?->toIso8601String(),
'customer' => new CustomerResource($this->whenLoaded('customer')),
'items' => OrderItemResource::collection($this->whenLoaded('items')),
'items_count' => $this->whenCounted('items'),
'total_qty' => $this->whenAggregated('items', 'quantity', 'sum'),
];
}
Controller menjadi satu-satunya tempat yang menentukan relasi apa yang dimuat:
public function index()
{
$orders = Order::with('customer:id,name')
->withCount('items')
->latest('placed_at')
->paginate(20);
return OrderResource::collection($orders);
}
Langkah 10: N+1 di Accessor dan View
Accessor yang mengakses relasi juga memicu N+1 saat dipanggil dalam loop:
// app/Models/Order.php
protected function customerName(): Attribute
{
return Attribute::get(fn () => $this->customer->name); // memicu query bila belum dimuat
}
Solusinya tetap sama: pastikan relasi di-eager load di query, atau ganti dengan subquery:
$orders = Order::query()
->addSelect(['customer_name' => Customer::select('name')
->whereColumn('customers.id', 'orders.customer_id')
->limit(1)])
->get();
Di Blade, perlakukan view sebagai "hanya membaca". Jangan menulis $order->payments()->where(...)->first() di dalam @foreach.
Langkah 11: Relasi Dua Arah dengan chaperone()
Saat memuat $customer->orders, lalu di dalam loop mengakses $order->customer, Laravel akan meng-query ulang pelanggan yang sama. chaperone() mengisi relasi balik secara otomatis:
// app/Models/Customer.php
public function orders(): HasMany
{
return $this->hasMany(Order::class)->chaperone();
}
$customer = Customer::with('orders')->find(1);
foreach ($customer->orders as $order) {
$order->customer->name; // tidak ada query tambahan
}
Langkah 12: Kunci dengan Test
Agar N+1 tidak kembali saat ada developer menambah field baru di Resource, uji jumlah query endpoint:
// tests/Feature/OrderIndexQueryTest.php
use App\Models\Order;
use Illuminate\Support\Facades\DB;
it('jumlah query daftar pesanan tidak bertambah seiring jumlah data', function () {
$user = \App\Models\User::factory()->admin()->create();
Order::factory()->count(5)->hasItems(2)->create();
DB::enableQueryLog();
$this->actingAs($user)->getJson('/api/v1/orders')->assertOk();
$querySedikit = count(DB::getQueryLog());
Order::factory()->count(30)->hasItems(2)->create();
DB::flushQueryLog();
$this->actingAs($user)->getJson('/api/v1/orders')->assertOk();
$queryBanyak = count(DB::getQueryLog());
expect($queryBanyak)->toBe($querySedikit);
});
Test ini tidak bergantung pada angka pasti, melainkan memastikan jumlah query konstan walaupun data bertambah. Karena preventLazyLoading juga aktif saat testing, lazy load yang terlewat akan langsung menggagalkan test.
Troubleshooting
Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Relasi diakses tanpa eager load (pengaman bekerja) | Tambahkan relasi ke |
Relasi kembali | Kolom FK atau PK tidak ikut dipilih | Sertakan |
| Salah nama relasi di | Samakan dengan nama method relasi ( |
Jumlah query tetap tinggi setelah | N+1 berasal dari tempat lain (accessor, Resource, view, | Lihat tab Queries di Debugbar, telusuri query yang berulang |
| Alias otomatis | Beri alias: |
Memori habis saat eager load | Relasi berisi sangat banyak baris (misalnya ribuan item per induk) | Batasi dengan closure, gunakan agregat, atau paginasi relasi secara terpisah |
Query | Eager load untuk puluhan ribu induk sekaligus | Proses dengan |
| Atribut yang di-append mengakses relasi | Hapus dari |
Best Practices
Keamanan
Jangan izinkan klien menentukan relasi bebas lewat parameter seperti
?include=. Jika dibutuhkan, gunakan daftar putih (misalnya viaspatie/laravel-query-builderdenganallowedIncludes), karena include yang tidak dibatasi bisa membocorkan data dan membebani database.Saat memilih kolom relasi, jangan sertakan kolom sensitif (
password, token) bila tidak diperlukan.
Performa
Aktifkan
Model::preventLazyLoading()(ataushouldBeStrict()) di development dan testing sejak hari pertama.Gunakan
withCount/withSum/withExistsuntuk angka, bukan memuat koleksi penuh.Gunakan
latestOfMany/oldestOfManyuntuk relasi "satu terakhir".Untuk pekerjaan batch, kombinasikan
chunkById()dengan eager loading di dalam setiap potongan.Pantau query lambat di production dengan Telescope, Laravel Nightwatch, atau slow query log database.
Maintainability
Tentukan relasi yang dimuat di satu tempat: controller, query object, atau scope seperti
scopeWithListRelations(). Resource dan view hanya membaca.Gunakan
whenLoaded,whenCounted,whenAggregateddi semua API Resource.Pertahankan test "jumlah query konstan" untuk endpoint daftar yang penting.
Hindari accessor dan
$appendsyang menyentuh relasi.
Related Articles
Memahami Eloquent Relationships: One-to-One, One-to-Many, dan Many-to-Many dengan Studi Kasus
Laravel Query Builder vs Eloquent ORM: Kapan Menggunakan Masing-Masing?
Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource
Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration
Last Tested
Komponen | Versi |
|---|---|
Laravel | 13.x |
PHP | 8.4 |
MySQL | 8.4 LTS |
Laravel Debugbar | fruitcake/laravel-debugbar 4.x |
Pest | 4.x |
Tanggal | 19 Oktober 2026 |