LiteFS, libSQL and replication for serverless apps

Replication models for an embedded database, LiteFS and its FUSE-based primary, Turso and libSQL, read replicas and consistency trade-offs.

Replication models

LiteFS in outline

# litefs.yml
fuse:
  dir: "/litefs"
data:
  dir: "/var/lib/litefs"
lease:
  type: "consul"
  hostname: "node-1"
  consul:
    url: "http://consul.service.consul:8500"
exec:
  - cmd: "/app/server"

• LiteFS mounts a FUSE directory; the application opens the database at the mount path and behaves exactly as with a local file.
• A lease held in Consul or etcd decides which node is the primary. Only the lease holder may write; other nodes serve reads and proxy writes to the primary.
• Because it is a FUSE filesystem, it needs the FUSE device and privileges that some platforms (including many serverless runtimes) do not grant.
• Transactions larger than the FUSE buffer wear down the model: the documentation recommends keeping writes under about 1 MB and avoiding very large transactions.
• Expected write latency includes the round trip to the primary, so a write from a distant region is slower than a local one - the read is fast, the write is not.

# inspect the mounted database and the replication state
litefs status
curl -s http://localhost:20202/   # the LiteFS HTTP API
# /: primary. /primary: current primary address
# /backup: a consistent backup including the WAL

libSQL and Turso

import { createClient } from "@libsql/client";

const client = createClient({
  url: "file:local.db",                    // the local replica
  syncUrl: "libsql://my-db.turso.io",      // the remote primary
  authToken: process.env.TURSO_TOKEN,
  syncInterval: 60_000,
});

await client.sync();                        // pull the latest from the primary
const rs = await client.execute("select id, title from book limit 10");

// writes are forwarded to the primary, reads are served locally
await client.execute({
  sql: "insert into book (title) values (?)",
  args: ["The Dispossessed"],
});

• An embedded replica gives you local reads at SQLite speed and a durable primary in the cloud, which is a good fit for edge or offline-capable applications.
• Reads can be stale by the sync interval unless you call sync() or the client performs a read-your-writes check with a stored frame number.
• libSQL adds features beyond SQLite: HTTP and WebSocket access, server-side functions, and a vector type. That also means it diverges from stock SQLite over time.
• Check the licence and the operational model of any managed offering, and test the failure mode when the primary is unreachable - the local replica can keep serving reads, but writes will fail.

-- read-your-writes: record the frame after a write, then wait for it locally
-- select current_frame from pragma_libsql_frame;   -- provider specific
-- then poll until the local replica has replayed at least that frame

FAQ

Related

SQLite on mobile, desktop and in the browser Next steps: choosing SQLite vs a client-server database

Last refreshed 2026-09-18.