Skip to content

Known Limitations

Imam Ali Mustofa edited this page Nov 10, 2026 · 2 revisions

Known Limitations

Explicitly listed, because nothing here is hidden.

Laravel 10/11 — not supported

The package cannot be installed alongside Laravel 10 or 11: dependencies conflict (darkterminal/turso-php-installer requires laravel/prompts ^0.3.5, incompatible with Laravel 10's prompts ^0.1), and both Laravel major versions are EOL upstream.

Offline writes are in beta

Both flavors depend on libSQL extension 1.7.0+, whose offline-write support is itself in beta. Upstream bugs will surface here as they appear in the extension.

prepare() is refused in offline-write mode

In offline_write mode, prepare() throws — by design in the extension, so a prepared statement cannot bypass the write journal. This driver works around it by routing through execute()/query() with bound parameters; raw SQL strings should still avoid prepare() in that mode.

Offline-write bootstrap requirement (Turso Cloud flavor)

On a fresh local replica, the first write before any sync() fails at the next sync() with a frame conflict (sent=1, got=17). Always call DB::sync() once on a fresh replica before writing.

Turso Cloud flavor requires real Turso Cloud

The cloud flavor cannot be emulated locally and is not exercised by CI; the self-hosted sqld flavor (offline_write mode) is what the harness verifies.

Plain http:// sync URLs

A plain http://localhost:8080 sync URL into tursodatabase is not accepted by this driver (Laravel treats it as an unsupported driver). Use libsql:// URLs; plain http only works combined with DB_SQLD_OFFLINE_MODE.

libsql:// scheme

libsql:// is the scheme for Turso Cloud; it implies HTTPS/TLS. It does not speak to a plain http:// sqld server.

No L10/11 support, no offline-write in CI

See above. These are documented, not hidden.

1.7.0+ blob writes — downgrade caveat

Transport for blobs changed in 1.7.0: transported blobs are written with an explicit libsqlblob: marker so reads decode them unambiguously. Data written by 1.7.0+ needs 1.7.0+ to be read back correctly (older drivers surface the raw marker string). Unmarked data written by earlier releases is still decoded via the legacy double-base64 heuristic.

Clone this wiki locally