Eloquent vs Query Builder for Lumen Database Access

Decision: Eloquent ORM or Query Builder in Lumen

When you add database access to a new Lumen API service, you must choose between Eloquent models and the query builder. The useful takeaway: start with the query builder for read-heavy, performance-sensitive endpoints, and add Eloquent only when relationship traversal or model lifecycle events simplify the domain logic.

Supported Options

Lumen includes the query builder by default through its database container binding. Eloquent is not active unless you install illuminate/database and register the Eloquent service provider. Both approaches use the same underlying PDO connection and respect the same .env database configuration.

Comparison Table

Aspect	Eloquent ORM	Query Builder
Pattern	Active record (object-row mapping, automatic mutators)	Explicit SQL construction
Relationships	Built-in definitions and auto-joins	Manual joins via raw SQL
Validation	Model-level rules and hooks	Application-level or separate layer
Bundle impact	Requires illuminate/database, increases size	Included by default, minimal overhead
SQL injection safety	Protected when using guarded attribute filling	Safe only when using bound parameters

Trade-offs

• Eloquent improves developer productivity when you need rich object interactions, automatic mutators, and relationship traversal. It pulls in the full database service provider and can increase runtime size, which conflicts with Lumen's lightweight philosophy.
• Query builder keeps the request path short and SQL explicit. It is the default in Lumen and ideal for performance-critical endpoints or ad-hoc reporting. You must manually bind parameters to avoid injection risks, and you lose automatic relationship handling.
• Mixing both styles in the same codebase is possible but can reduce consistency. Pick one approach per domain or establish a team convention.

Concrete Implementation: Query Builder Route

Lumen resolves db from the service container. The following route closure runs a parameterized SELECT against the users table:

// routes/api.php
use Illuminate\Support\Facades\Route;

Route::get('/users', function () {
    $db = app('db');
    $users = $db->table('users')
        ->where('status', 'active')
        ->where('created_at', '>', now())
        ->pluck('id', 'name');

    return response()->json($users);
});

Where to run: inside routes/api.php or a controller method in a Lumen application. Required permissions: the database user configured in .env needs SELECT access to the target table. Meaningful placeholders: replace users, status, and created_at with your actual table and column names. Expected check: the response returns an array of user IDs keyed by name. Risk: interpolating variables directly into the SQL string instead of using bound parameters exposes the endpoint to SQL injection.

Validation Checklist

1. Run composer show illuminate/database from the project root. If the package is absent, Eloquent is not installed.
2. Open bootstrap/app.php and confirm whether Illuminate\Database\Eloquent\ServiceProvider::class is registered.
3. Enable query logging in config/database.php or check the log channel to confirm bound parameters appear as placeholders rather than interpolated values.
4. Run a micro-benchmark with microtime(true) around a typical SELECT to compare query builder overhead against Eloquent in your workload.

Limitations and Practical Verification

Eloquent adds lifecycle events, soft deletes, and relationship magic that simple CRUD APIs may not need. The extra package can increase cold-start time in containerized or serverless deployments. The query builder has no extra dependency but requires disciplined parameter binding. Verify your choice by checking composer.lock for illuminate/database and confirming the service provider registration matches your intended stack.