Eloquent Driver Laravel Package

Technical Evaluation

Architecture fit. The package swaps Statamic's flat-file repositories for Eloquent-backed ones at a per-repository configuration seam (entries, terms, assets, globals, navigations, users). Blueprints, the Control Panel, template tags, and Statamic's public APIs stay intact — only persistence changes. For a TPM this is the rare infrastructure change with a genuinely small blast radius: it is a config-level increment, not a re-platforming, and it is reversible by reverting config and clearing the stache. The payoff is narrow and honest: relational querying, indexing, joins against application/CRM/analytics tables, and reuse of existing database backup, monitoring, and observability tooling.

Integration feasibility. High for teams already on Statamic + Laravel with an operated MySQL/Postgres instance. The path is composer require, publish config and migrations, php artisan migrate, run the per-repository importers (e.g. statamic:eloquent:import-entries), clear the stache, and flip one repositories.*.driver value at a time. Mixed drivers are supported, which means the realistic first milestone is "entries only," shipped to production with assets and globals still on disk. That gives a small blast radius, a clear debug signal, and a cheap rollback. The package adds no new infrastructure — no search cluster, broker, or hosted service — which is the core architectural argument in its favour.

Technical risk.

• Content leaves version control. This is the substantive change, not the driver flip. Content promotion, PR-based content review, environment seeding, and diffability all need new process. Teams relying on git-based editorial workflow lose that property entirely and must decide the replacement deliberately.
• users repository is hazardous. A bad user import can lock operators out of the Control Panel. Migrate last, in staging first, with a one-line config rollback rehearsed.
• Ordering integrity. Since 5.12.3, entry order is read from the order column rather than inferred. Rows written by earlier versions or manual inserts that skipped order will sort arbitrarily after upgrade — backfill or re-import before trusting listings.
• Timestamp correctness. The timezone-shift-on-save fix means rows written on earlier 5.12.x may carry shifted publish timestamps. That is a governance and auditability issue for scheduled content, events, retention, or reporting — not cosmetic — and needs an audit-and-correct step.
• Custom entry class hydration. The 5.12.3 hydration fix implies that subclassing the entry model (the recommended customization path) previously degraded dated-listing performance. Teams that subclass early and lag on patches feel this first.
• Thin ecosystem. 129 stars and zero tracked dependents mean an early-adopter posture: no independent vendor SLA, budget for self-support and your own regression coverage.
• Mixed-driver seams. Asset references and navigation→entry relations resolve by ID and generally work, but they are the first place to inspect when something renders empty after a partial migration. Assets move metadata only; files stay on disk.
• Permanent schema ownership. The driver transfers content-table migration and operations responsibility to your team. It does not remove it.

Key questions to resolve before commitment.

1. What content volume, query complexity, or editorial concurrency threshold are we actually crossing? If we cannot name the number, the case is weak.
2. Which repositories move, in what order, and is users in scope at all?
3. Who owns the content schema and its migrations — platform, backend, or DevOps — and who is on call for it?
4. What is the content promotion model across local/staging/production once content is not in git?
5. What are the backup RPO/RTO for content tables, and does that meet editorial tolerance for lost work?
6. Which addons and custom code touch content files directly? "Most addons work" is not an inventory.
7. What is the rollback window, and how long do we retain the flat-file content directory as a fallback?
8. Does any content carry audit, retention, or legal requirements that the timestamp drift may have compromised?
9. What does a failed deploy look like — is migrate --force in the release script, and is there a tested rollback path?

Integration Approach

Stack fit. Requires a Laravel app with Statamic and a relational database (MySQL, Postgres, or SQLite) the team already operates. It reuses existing migrations, backup policy, monitoring, and connection management. Database driver choice matters at the edges — JSON column behaviour, full-text search, and collation differ between SQLite and Postgres — so standardise on the production engine in staging.

Migration path. Phased, reversible, and validated at each step:

1. Baseline. Install, publish config and migrations, run migrate against a production-shaped copy. Flip no drivers. Confirm migrations apply cleanly and record baseline metrics (listing render latency, import duration, DB size).
2. Entries only. Flip the entries repository, import, clear stache, and validate. Entries are the highest-volume, highest-pain repository and the clearest business value — cheapest win, best learning.
3. Validate before removing anything. Compare file-vs-DB record counts, diff a sample of rendered pages, spot-check order-dependent listings, and audit publish timestamps against known scheduled content.
4. Soak in staging through a full editorial cycle — draft, review, publish, schedule, unpublish — before production.
5. Production with a safety net. Keep the flat-file content directory in the repo for at least the first week. Reverting config plus clearing cache is a complete rollback.
6. Expand deliberately to terms/taxonomies, globals, and navigations; consider users last or never. Each step repeats flip → import → clear stache → validate → soak.

Compatibility. Match the driver major to the Statamic major (v5.x aligns with Statamic 5). Inventory addons and custom code: anything querying through Statamic APIs is generally fine; anything reading Markdown files or filesystem paths will break. Multisite content, search indexes, queued jobs, and cached stache entries all need explicit verification. Extend the package's models rather than forking, so patch upgrades stay trivial.

Sequencing and deploy changes. Content migrations join the deploy script; decide whether content is seeded per environment, restored from production, or authored in place. RefreshDatabase plus factories becomes the content-fixture strategy — a genuine testing win. Rollback rehearsal belongs in the plan, not in the incident.

Exit criteria and rollback triggers (TPM-owned). Define them before the pilot: render latency on listings must not regress beyond an agreed threshold; import must complete within a maintenance window; zero ordering or timestamp defects in the validation sample; any users-repository failure aborts immediately. Track pilot metrics — listing render time, import duration, query latency on augmented pages, editorial incident count — so expansion is a data decision, not an opinion.

Operational Impact

Maintenance. The team permanently owns content schema migrations, model extensions, and upgrade alignment with Statamic majors. Fold driver upgrades into the normal dependency cadence, but read release notes for data-affecting fixes: 5.12.3 changed order handling and corrected timezone-on-save, both of which imply post-upgrade data checks. Pin versions, extend rather than fork, and treat every Statamic upgrade as a paired driver upgrade.

Support. Thin ecosystem, no vendor SLA. Budget internal triage, maintain a regression test suite, and keep staging database-parity with production. Expect to be your own first-line support; upstream fixes exist but you cannot contract for response time.

Scaling. This is the point of the exercise: indexes, cursor pagination, aggregates, joins, and read replicas become available for content. But the database becomes the content hot path, so capacity planning, connection limits, and query review matter. Watch N+1 queries from augmentation, large import batches, and stache invalidation on publish — all are scaling failure modes that flat files did not have in the same form.

Failure modes to plan for.

• Stale stache presenting as data loss. Nearly every "content disappeared" report is cache, not data. Make "clear the stache" an explicit, documented step after any driver flip or import.
• Partial or failed import leaving empty or truncated listings; re-run the importer rather than hand-patching rows.
• users lockout blocking the Control Panel; migrate in staging first with config rollback ready.
• Null order values causing arbitrary sorting after the 5.12.3 upgrade; backfill before trusting listings.
• Timezone-shifted timestamps from pre-fix 5.12.x rows; audit and correct published/scheduled content.
• Mixed-driver relationship resolution rendering empty after partial migration; check IDs and driver config first.
• Assets appearing missing because only metadata moved and files remain on disk; document the distinction for editors.
• Deploy-time migration failure with content tables mid-change; ensure backups and a tested restore path precede every release.

Ramp-up. Engineering effort is modest — the team already knows Eloquent — but new runbooks are required: content import, stache clearing, content backup and restore, environment seeding, and rollback. The larger ramp is editorial and stakeholder-facing: content no longer appears in pull requests, staging refreshes change shape, and review workflows must be redesigned. TPM actions: a timeboxed entries-only pilot with named success metrics and exit criteria, a written rollback procedure tested in staging, a comms plan for editors covering what changes about draft/review/publish, and a decision log entry covering schema ownership and the flat-file retention window. Treat success as measurable — faster listings, reliable ordering, correct timestamps, no content-loss incidents — and let that evidence, not the package's novelty, justify expanding beyond entries.