Skip to content

Offline Writes

Imam Ali Mustofa edited this page Nov 10, 2026 · 1 revision

Offline Writes (Two Flavors)

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.

Flavor 1 — Turso Cloud (remote_replica mode)

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

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 TABLE left the cloud database clean;
  • PROOF-OFFLINE-CLOUD: {"ok":12,"fail":0,"all_ok":true} via docker/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=TursoCloudOfflineWriteTest

Required ordering (important)

On 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.

Flavor 2 — Self-hosted sqld (offline_write mode)

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=true

Activation: 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

Verified in the docker proof harness (docker/proof/):

  • offline_outage: isOnline() returns false during 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).

Not supported

  • 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.

Limitations (libSQL extension, upstream)

  • Offline-write support is in beta in the libSQL extension itself.
  • In offline_write mode the extension refuses prepare() — this driver therefore binds parameters and routes statements through execute()/query() with a corrected fetchArray() handling.
  • DDL (CREATE TABLE) journals the same way as DML.

Clone this wiki locally