Repository navigation
Offline Writes
libSQL's offline-write support has two flavors, selected by two different constructor flags. They are not interchangeable; each writes to a different system and requires different setup.
DB_CONNECTION=libsql
DB_DATABASE=database.sqlite # local replica file
DB_AUTH_TOKEN=<cloud token>
DB_SYNC_URL=<cloud sync url>
DB_OFFLINE_WRITES=true
# DB_SQLD_OFFLINE_MODE must be false (omit it)Activation: offline_writes: true without sqld_offline_mode.
Behavior: writes journal locally against the embedded replica; DB::sync()
pushes the journal to Turso Cloud.
Verified live against a real Turso Cloud database (not reproducible in CI — no cloud credentials for CI exist):
- bootstrap pull from remote to local replica was successful;
- journaled local writes pushed with
sync()(plain remote read-back returned the inserted rows); - a pushed
DROP TABLEleft the cloud database clean; -
PROOF-OFFLINE-CLOUD: {"ok":12,"fail":0,"all_ok":true}viadocker/proof/offline-cloud.sh.
tests/Feature/TursoCloudOfflineWriteTest.php runs the same flow and is
skipped by default in CI. Enable manually with:
TURSO_CLOUD_DB_URL=... TURSO_CLOUD_DB_TOKEN=... \
./vendor/bin/pest --filter=TursoCloudOfflineWriteTestOn a fresh replica file, call DB::sync() before any write, so the
frames from the remote are downloaded first. Writes made before the first
sync() upload the local frames with an incorrect base index and the push
fails with server returned a conflict: sent=1, got=17. The sqld flavor
(below) does not have this requirement.
DB_CONNECTION=libsql
DB_DATABASE=database.sqlite
DB_AUTH_TOKEN=<token>
DB_SYNC_URL=http://127.0.0.1:8080
DB_SQLD_OFFLINE_MODE=true
DB_OFFLINE_WRITES=trueActivation: sqld_offline_mode: true and offline_writes: true.
Behavior: writes apply to a local write journal; DB::sync() replays the
journal to sqld. isOnline() and getPendingOperationsCount() are available.
Verified in the docker proof harness (docker/proof/):
-
offline_outage:isOnline()returnsfalseduring a real network outage; -
offline_journal:CREATE TABLE+ 3 inserts journal locally; -
offline_blind_window: host-side raw Hrana check shows sqld has zero jour rows during the outage (the server never sees unsynced writes); -
offline_reconnected:isOnline()true after reconnect; -
offline_drain:DB::sync()drains the journal (pending == 0); - server-side row count verified by raw Hrana client, key+value exact.
This is also the combination exercised in docker/proof/ on every
CI-equivalent run (proof:offline-write + proof:offline-sync).
- Laravel 10/11 — the package cannot be installed there.
-
Turso Cloud flavor against plain
libsql-server— the cloud flavor goes through HTTPS/libSQL protocol only against Turso Cloud.
- Offline-write support is in beta in the libSQL extension itself.
- In
offline_writemode the extension refusesprepare()— this driver therefore binds parameters and routes statements throughexecute()/query()with a correctedfetchArray()handling. - DDL (
CREATE TABLE) journals the same way as DML.