Weave Code
Eloquent Driver Laravel Package
statamic/eloquent-driver
The Statamic Eloquent Driver lets you store Statamic content—entries, terms, assets, and more—in Laravel Eloquent models instead of flat files, making content queryable in your database while keeping Statamic’s familiar APIs and workflows.
Allows you to store Statamic data in a database.
Frequently asked questions about Eloquent Driver
- How do I install the Statamic Eloquent Driver?
- Install the package with composer require statamic/eloquent-driver, then publish its config and migrations and run php artisan migrate. Import your existing content per repository using the bundled importer commands, such as statamic:eloquent:import-entries, and clear the stache afterwards. Finally flip the relevant repositories entry in the package config to eloquent and verify the Control Panel and front end. Doing one repository at a time keeps the change small and easy to debug.
- Which Statamic and Laravel versions does the Eloquent Driver support?
- The package is versioned alongside Statamic major releases, so match its Composer constraint to your Statamic version and check the requirements in composer.json before upgrading. It runs on the Laravel version your Statamic install already supports, with MySQL, PostgreSQL, or SQLite as the backing database. Because behaviour fixes such as the 5.12.3 entry ordering and timestamp handling ship in patch releases, stay on a recent 5.12.x or newer rather than an early release. Upgrade in staging first, since some fixes require data backfills.
- Can I keep some collections as flat files and move only entries to the database?
- Yes. The driver is configured per repository, so entries, terms, assets, globals, navigations, and users can each use either the file or eloquent driver. The common first milestone is moving entries only and leaving assets and globals on disk. Watch mixed-driver seams first when something renders empty, since asset references and navigation-to-entry relations resolve by ID across repositories.
- How do I migrate existing file-based content into the database?
- Each repository has its own import command, for example statamic:eloquent:import-entries, which reads your existing YAML and Markdown files and writes them into the configured Eloquent models. Run imports in staging against a copy of production content, back up the database first, and verify entry counts, ordering, and publish timestamps after the import. Only then repeat against production and clear the stache. Keep the original content files until you have validated everything.
- Which databases does the Statamic Eloquent Driver support?
- Because content is stored through Laravel's Eloquent ORM, the driver works with MySQL, PostgreSQL, and SQLite, which are the databases Statamic documents for content storage. Anything Laravel handles well in your environment generally works, but stick to a well-supported database for a production content store. Add indexes on frequently queried columns to get the scalability benefit the driver is meant to provide.
- Should I move the Statamic users repository to the database?
- Treat the users repository as the highest-risk migration in the whole project. A bad import can lock operators out of the Control Panel, so migrate it last, test it in staging with a real login flow, and rehearse a one-line config rollback back to the file driver. Many teams leave users on flat files entirely if they have no strong reason to move them.
- Why are my entries in the wrong order after upgrading the Eloquent Driver?
- Since version 5.12.3, entry order is read from the order column instead of being inferred. Rows written by earlier versions, or inserted manually without an order value, will sort arbitrarily after the upgrade. Backfill the order column or re-run the importer before trusting any dated or ordered listings. The same patch series also fixed a timezone shift on save, so audit publish timestamps written on earlier 5.12.x releases for scheduled content.
- How do I roll back from the Eloquent Driver to flat files?
- Rollback is a config change: set the affected repositories back to the file driver and clear the stache. Your database tables remain intact, so export or retain them before removing migrations, and make sure any content created while the driver was active is written back to files if you intend to keep it. Rehearse the rollback in staging and record how long the window stays open after go-live.
- Does the Eloquent Driver change blueprints, template tags, or the Control Panel?
- No. Blueprints, the Control Panel, template tags, and Statamic's public APIs are unchanged; only persistence moves from files to Eloquent models. Assets are a partial exception: their metadata goes into the database while the files themselves stay on disk. Audit addons and custom code that read or write content files directly, because those are the pieces most likely to break after a partial migration.
- What are the alternatives to the Statamic Eloquent Driver?
- You can keep Statamic's default flat-file repositories and accept the file-based workflow, or keep files as the source of truth and sync content into a search index or read replica for heavy querying. Building a custom repository driver is possible but rarely worth the maintenance. Weigh the driver against your editorial process too: once content leaves git, you need a deliberate content promotion model across local, staging, and production.
Weaver
How can I help you explore Laravel packages today?