Database (libSQL)

One database technology covers local dev, CI, and global production: libSQL, the open fork of SQLite built for the edge. Session, cache, and queue all use the database driver on libSQL — zero extra services to run or pay for. The same SQL, the same migrations, the same query path from docker compose up to a multi-region deploy. The queue worker that drains that database queue is a self-hosted always-on process (queue:work in compose/k8s/VPS), not a CaaS sidecar (ADR 0009).

Local: self-hosted sqld

Dev compose runs the official server image ghcr.io/tursodatabase/libsql-server. It speaks the same Hrana protocol as the managed providers, so code that runs locally runs unchanged against Bunny Database or Turso.

sqld:
  image: ghcr.io/tursodatabase/libsql-server
  command: ["/bin/sqld"]
  environment:
    SQLD_DB_PATH: /var/lib/sqld
  ports: ["8181:8181"]

The app connects over Hrana at http://sqld:8181 (host http://localhost:8181). SQLD_DB_PATH sets where the local SQLite file lives; the entrypoint wires --db-path and the listen address itself.

Production: remote libSQL

Remote-only — not embedded replica mode. Point the app at a managed endpoint or your own sqld:

Provider	URL	Notes
Bunny Database	`libsql://[id].lite.bunnydb.net`	Managed, globally replicated, Public Preview, free, 1 GB/DB cap
Turso	`libsql://[id].turso.io`	Managed, embedded replicas available (not used here)
Self-hosted sqld	`http://sqld:8181`	Same image as dev, behind TLS

Bunny Database caveats: 1 GB per DB, ~10s replication window, no read-your-writes on replicas. Fine for template-scale apps.

Laravel adapter

turso/libsql-laravel is a technical preview and requires illuminate ^11|^12. This platform installs the maintained Laravel 13 fork mehdiamenein/libsql-laravel (constraint ^13.0) via a Composer VCS repository. The fork carries:

cursor() / select() signature fixes for Laravel 13
PDO getAttribute probes the database queue driver relies on
URL-based config (libsql://...)
CharBox empty-string patch for a native client crash

Config

URL-based. Three env vars cover every environment:

DB_CONNECTION=libsql
DB_URL=libsql://[id].lite.bunnydb.net   # remote; empty in dev (compose wires sqld)
DB_AUTH_TOKEN=...                        # remote only; omit locally

Hrana

libSQL's client/server protocol, over HTTP at /v2/pipeline. JSON execute / close requests — one TCP path, no binary driver socket. Same protocol in dev and prod is what makes the local sqld container a faithful stand-in for Bunny Database.

flowchart LR
  App[App container] -->|"Hrana / HTTP :8181"| Sqld[Local sqld]
  App -->|"Hrana / HTTPS"| Bunny[Bunny Database]
  App -->|"Hrana / HTTPS"| Turso[Turso]
  App -->|"Hrana / HTTP"| Self[Self-hosted sqld]

Exception: Reverb scale-out

Reverb has no database persister. Horizontal replicas need Redis pub/sub (REVERB_SCALING_ENABLED=true). The broadcast queue may still stay on QUEUE_CONNECTION=database; Redis is optional and separate.