DEV Community

Cover image for Laravel Scout and Meilisearch: fast search that keeps working when the engine is down
Adil Soukaini | Full-Stack Developer
Adil Soukaini | Full-Stack Developer

Posted on Originally published at shipfastdev.com

Laravel Scout and Meilisearch: fast search that keeps working when the engine is down

Originally published on shipfastdev.com.

To get fast search in Laravel without making the search engine a single point of failure, put Meilisearch behind Laravel Scout, give the client a short timeout, and wrap the search call in a try/catch that falls back to a plain database query returning the same shape. Then make sure the index actually contains every field you filter on, because that is the failure that will not throw. This is how search works on Driveway Morocco, ShipFastDev's car-rental platform, and what we learned wiring it up.

What we built and why

Driveway Morocco is a Laravel application with a React (Inertia) storefront. Customers type a make or model into a search box and get up to five matching vehicles in a dropdown. The endpoint behind it, /search/suggestions, returns a plain JSON array of at most five available vehicles, with each vehicle's main image loaded in a single batched query rather than one query per result.

Search went through three stages:

  1. Scout on the database engine. The first version used Scout's database driver. The Laravel Scout documentation describes it as an engine that "uses MySQL / PostgreSQL full-text indexes and LIKE clauses to search your existing database directly", with no separate indexing step. It needs no extra service and no search credentials, which made it the deliberate local default: the project runs offline and there is no search secret to leak.
  2. Meilisearch added. Meilisearch v1.10 was added to the Docker Compose setup with a persistent volume, and the PHP client meilisearch/meilisearch-php was installed. On the local container the commit that added it recorded results in under a millisecond.
  3. Resilience on top. A database fallback, a request timeout and a health check were added the same day, before any of it went to production. In production, Meilisearch runs on a small virtual machine separate from the app.

Because the code talks to Scout rather than to Meilisearch directly, switching engines is a configuration change (SCOUT_DRIVER), not a rewrite. That matters for a startup: you can launch on the database engine and add a search server only when the catalogue or the traffic justifies it.

Index only public fields

A suggestions endpoint is public and unauthenticated, so treat it as a data-exposure boundary. On Driveway Morocco the model's toSearchableArray() returns only public catalogue fields (id, make, model, category, year) plus status, which exists only so results can be filtered. The endpoint was checked to return vehicle data and nothing about bookings or customers.

Two more protections sit on the endpoint:

  • Rate limiting. It is throttled to 30 requests per minute per client, so a script cannot hammer the search server through it.
  • Safe rendering. The React dropdown renders results as escaped text inside an ARIA listbox/option structure, so a query shaped like an XSS payload is shown as harmless text. The audit probe returned an empty array and no console errors.

The filter that silently returns nothing

This is the bug worth knowing about. Suggestions only show available cars, so the query uses Scout's where('status', 'available'). With Meilisearch, two separate things must both be true for that to work:

  1. The attribute must be declared filterable. Scout's docs say you must configure filterable attributes "before utilizing Scout's 'where' clauses", in the index-settings section of config/scout.php, and then run php artisan scout:sync-index-settings. Meilisearch's filtering guide adds that filterableAttributes is empty by default and that updating it "requires Meilisearch to re-index all your data". If you skip this step, Meilisearch returns an invalid_search_filter error, which at least throws.
  2. The attribute must be in the documents. This is the quiet one. When the production search server was wired up, status was declared filterable but was not in toSearchableArray(), so the indexed documents had no status field. The filter matched zero documents. There was no exception, so the fallback never ran, and the search box simply showed nothing. The fix was to add status to the searchable array as a filter-only field (filterable, but not in searchableAttributes) and re-import.

The lesson: a fallback only protects you from errors. An empty result is a valid answer, so test that a known query returns a known vehicle against the real engine after every index or schema change.

The database fallback

The suggestions controller tries Scout and Meilisearch first. If anything throws (the container is down, the connection is refused, the index is missing), it runs a raw database LIKE query instead. The fallback returns the same response shape, keeps the same five-result cap and batch-loads images the same way, so the frontend cannot tell which path served it. In outline:

try {
    $hits = Vehicle::search($q)->where('status', 'available')->take(5)->get();
} catch (\Throwable $e) {
    report($e);
    $hits = Vehicle::where('status', 'available')
        ->where(fn ($w) => $w->where('make', 'like', "%{$q}%")
                              ->orWhere('model', 'like', "%{$q}%"))
        ->limit(5)->get();
}
Enter fullscreen mode Exit fullscreen mode

Two details keep this honest. First, call report() in the catch block so the failure still reaches your logs; a fallback that hides every outage means nobody fixes the engine. Second, keep the fallback simple. It does not need typo tolerance or ranking; it needs to return something reasonable while the real engine is away.

This became a project-wide rule: every external dependency (search, payments, email) gets a graceful fallback. On the Stripe side, for example, a failed card hold is caught and shown as a booking failure instead of crashing the page.

Give the client a timeout

A fallback only helps if the failing call returns. A refused connection fails fast, but a server that accepts the connection and then hangs can hold your request open. Guzzle's request options document both timeout and connect_timeout with a default of 0, which means "wait indefinitely".

The project set a 5-second ceiling for every external HTTP call, and found that a timeout key in the Scout config does nothing on its own. Scout's service provider builds the Meilisearch client from the host, the key and a client-agent string only; no timeout and no HTTP client are passed. The meilisearch-php README shows the way in: the client accepts any PSR-18 HTTP client, including a Guzzle client created with a timeout. So the binding is replaced in AppServiceProvider::boot():

$this->app->singleton(\Meilisearch\Client::class, fn () => new \Meilisearch\Client(
    config('scout.meilisearch.host'),
    config('scout.meilisearch.key'),
    new \GuzzleHttp\Client(['timeout' => 5]),
));
Enter fullscreen mode Exit fullscreen mode

With this in place, the worst case for a hung search server is a five-second wait followed by database results, not a request that never finishes.

A health check that reports "degraded"

Driveway Morocco exposes a /health endpoint that checks the database, Meilisearch, Stripe and storage. It always returns HTTP 200 with a JSON body whose overall status is healthy or degraded, plus a result per dependency. The Meilisearch check uses the engine's own GET /health route, which returns {"status": "available"} when the instance is fine. The search host is read from configuration, not hard-coded, so the same check works locally and in production.

Returning 200 while degraded is deliberate: search being down should be visible on a dashboard, but it should not make a load balancer pull a site that still works through the fallback.

Why there is no circuit breaker for search

The project documents a circuit-breaker pattern for external APIs with intermittent failures (Stripe, email, a future SMS provider) and explicitly leaves Meilisearch out: the database fallback is immediate, so a breaker adds little. The honest trade-off is the timeout. If the search server ever starts hanging rather than refusing connections, every search would wait up to five seconds before falling back, and that would be the signal to add a breaker or lower the timeout.

Checklist: Scout and Meilisearch with a fallback

  • Add laravel/scout to composer.json explicitly. On this project the Searchable trait was used before the package was declared, which caused a "Trait not found" fatal error on a fresh install.
  • Start on the database engine; add Meilisearch when you need typo tolerance or speed at scale.
  • Index only public fields, and put every field you filter on into toSearchableArray().
  • Declare filterable attributes in config/scout.php and run scout:sync-index-settings on every deploy.
  • Wrap the search in try/catch, report the exception, and fall back to a database query with the same response shape.
  • Bind the Meilisearch client with an HTTP timeout; the default is to wait forever.
  • Throttle the public endpoint and render results as escaped text.
  • Use a search-only API key in the application. Meilisearch's security guide says: "Never use the master key to perform searches or other common operations."
  • Remember that Meilisearch indexes asynchronously; Scout's docs recommend a queue worker for syncing, so run one.
  • Check a known query against the real engine after every deploy, ideally in an end-to-end test (see Playwright end-to-end tests in CI).

If you are hosting the app on containers, the related setup is covered in deploying Laravel on Google Cloud Run. For more on why skipping steps like these turns into cost later, see technical debt for founders.

Frequently asked questions

Do I need Meilisearch, or is Scout's database engine enough?

For many apps the database engine is enough. Laravel's docs call it "the simplest and most practical way to add search" for many applications, using MySQL or PostgreSQL full-text indexes and LIKE. Add Meilisearch when you need typo tolerance, relevance ranking or fast results on a large catalogue.

Why does my Scout where clause return no results with Meilisearch?

Check two things: the attribute is listed in filterableAttributes (and you ran scout:sync-index-settings), and the attribute is actually present in the indexed documents via toSearchableArray(). The first mistake raises an error; the second just returns zero hits.

How do I set a timeout for Meilisearch in Laravel?

Scout builds the client without a timeout, so bind your own Meilisearch\Client in a service provider and pass a Guzzle client created with a timeout option. Guzzle's default of 0 means it waits indefinitely.

Will search still work if Meilisearch goes down?

Only if you build for it. Catch exceptions around the Scout search call and run a database query with the same output, and log the failure so someone fixes the engine.

Sources

  1. Laravel Scout (Laravel 13.x documentation), Laravel, accessed October 2026
  2. ScoutServiceProvider.php (laravel/scout 11.x), Laravel on GitHub, accessed October 2026
  3. Filter search results, Meilisearch, accessed October 2026
  4. Error codes, Meilisearch, accessed October 2026
  5. Health, Meilisearch, accessed October 2026
  6. Basic security, Meilisearch, accessed October 2026
  7. Request Options, Guzzle documentation, accessed October 2026
  8. meilisearch-php (README), Meilisearch on GitHub, accessed October 2026

Top comments (0)