Repository navigation
Known Limitations
Explicitly listed, because nothing here is hidden.
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.
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.
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.
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.
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.
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:// is the scheme for Turso Cloud; it implies HTTPS/TLS. It does not
speak to a plain http:// sqld server.
See above. These are documented, not hidden.
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.