Laravel Cloudflare D1 Laravel Package

Product Decisions This Supports

• Platform direction: is Cloudflare D1 a sanctioned deployment target? This package converts a strategic question into a concrete, cheap experiment. If the org is consolidating on Cloudflare for edge delivery, DNS, and Workers, a Laravel service that can read from a globally distributed edge database changes what "where does this service live" means. Treat it as a platform-level go/no-go, not a per-service preference.
• Build vs. buy for the driver layer. The adapter already exists, is MIT-licensed, and covers Eloquent, the query builder, schema migrations, and a MySQL migration starting point. That removes "we'd have to write a driver first" from the objection list and lets D1 be evaluated on latency, cost, and operational fit — the criteria that actually matter.
• Roadmap triage for latency- and cost-sensitive work. D1 plausibly earns capacity for read-heavy APIs, edge-cached endpoints, internal dashboards, scheduled aggregation jobs, prototypes, and small multi-tenant workloads. The same assessment flags the counter-case: every statement is an HTTPS round trip, so query-chatty page flows are a bad fit no matter how attractive the pricing looks. That screening rule belongs in intake criteria, not in a post-mortem.
• Migration feasibility and effort sizing. The included tooling produces a candidate schema from an existing MySQL/SQLite dump, which is enough to estimate real effort — types, defaults, indexes, foreign keys, JSON/enum/generated columns, collation, and SQLite's ALTER TABLE limitations. Budget it as a diff generator requiring hand-audit, not as an automated converter; the manual-review line item is the one teams forget.
• Bulk ingestion and backfill scoping. The "20x faster bulk inserts" claim is really about D1's batch endpoint cutting round trips. Relevant for imports, seeding, and backfills — but it is a hypothesis to benchmark against your actual row shape and payload ceilings, not a number to put in a plan.
• Ownership and risk planning. Fourteen stars, zero known dependents, one maintainer, a 1.x line, and a v1.2.1 release that existed solely to work around a Laravel 11-vs-12 grammar constructor change. Adoption is functionally in-house ownership of the driver. This decision forces explicit calls on version pinning, vendoring or forking, upgrade responsibility, and on-call readiness.
• A cheap spike that produces a defensible answer. A time-boxed pilot against a bounded service yields real p95 latency, error rates, and cost per thousand requests from your actual runtime region. That is a far better basis for a roadmap commitment than a vendor benchmark.

When to Consider This Package

Consider it when:

• The team runs Laravel 10–12 on PHP 8.1+ and is already evaluating D1 or a broader Cloudflare-native stack — otherwise you are introducing a database and a cloud provider in one move.
• The scope is genuinely bounded: a read-heavy service, internal tool, prototype, scheduled job, small SaaS tenant, or edge API. Not core transactional OLTP, not the billing ledger, not anything with multi-step workflows that depend on real transactional guarantees.
• Eloquent and query-builder compatibility with a MySQL/SQLite migration starting point materially reduces the cost of finding out — i.e., you'd otherwise fund a custom adapter to run the experiment.
• You can pin the package version and the Laravel minor, vendor or fork the driver, and accept that a future composer update requires a real-D1 integration suite to pass before shipping.
• The workload tolerates no persistent connections and no PDO handle. Anything in the app or dependency tree that expects PDO — profiling tools, custom DB utilities, some test helpers — will break, and that inventory is worth taking before, not after.
• You have, or will build, retry and instrumentation around the HTTP client: 429/5xx backoff with jitter, statement latency logging, and a per-request round-trip counter. Without that, production debugging is guesswork.
• The rollback story is written down and rehearsed: MySQL remains source of truth during the pilot, D1 is exported before every migration, and the cut-back procedure exists before it's needed.

Look elsewhere when:

• The workload is transaction-heavy — row-level locking, SELECT ... FOR UPDATE, long-lived sessions, or cross-service rollback semantics. DB::transaction() here maps to batch atomicity, and partial batch failures can leave ambiguous commit state.
• The data model leans on native DECIMAL, DATETIME, ENUM, JSON, or full-text search. Dates-as-text, money-as-integer-minor-units, and LIKE-with-index are workable but they are real design constraints, not footnotes.
• The team cannot absorb driver ownership. No maintainer-backed support, no dependents to learn from, and a Laravel-internals coupling that will resurface at the next major. If the org needs a vendor to call, this is not it.
• Query volume per request is naturally high. Porting a 40-query page flow will "work" and be unusable; if the architecture can't be thinned first, stop.

How to Pitch It (Stakeholders)

To executives: Cloudflare D1 is a serverless SQLite database that runs at the edge. This package lets our existing Laravel code — models, queries, migrations — talk to it without a rewrite, which means we can test whether D1 belongs in our stack for roughly the cost of a two-week spike instead of a funded adapter project. The upside is regional read latency and consolidating spend on a vendor we may already use. The honest caveats: the driver is a single-maintainer open-source package with effectively no external adoption, so adopting it means we own it — pinning versions, keeping a private fork, and absorbing Laravel upgrade work ourselves. And D1 bills on rows read and written over HTTP, so inefficient query patterns become a latency and an invoice problem. My recommendation is a bounded pilot on one read-heavy service with a documented rollback to MySQL and written latency, error-rate, and cost thresholds that gate any expansion. Total ask: one engineer, time-boxed, with the integration suite and rollback procedure as the two non-negotiable deliverables.

To engineering: The driver registers D1 as a native Laravel connection, so DB::connection('d1') and Eloquent work as expected — but there is no PDO underneath, so anything expecting a handle will break, and you should inventory that before you start. Scope the connection per-model during the pilot rather than flipping DB_CONNECTION; a one-line revert beats a coordinated env change. Every statement is an HTTPS round trip, so profile round trips per request, not just milliseconds — N+1 stops being a style issue and becomes a budget one. DB::transaction() is batch atomicity, not a real transaction: no row locking, no FOR UPDATE, and partial batch failures can be ambiguous — audit every call site you port and make writes idempotent. Design around SQLite's ALTER limits, declare $casts on every model because type affinity will not coerce for you, and chunk both bulk inserts and long update/delete statements. Wrap the HTTP client with retry with jittered backoff on 429/5xx and never on 4xx, and override the exception handler so on-call can tell a rate limit from a dialect bug — the rendered SQL plus bindings is your only evidence, since there's no console to drop into. Run a real-D1 integration suite on every Laravel and PHP upgrade: v1.2.1 shipped purely to paper over a grammar-constructor change between Laravel 11 and 12, and that's exactly the kind of breakage that appears silently after an unrelated composer update. Vendor the package or keep a private fork from day one.