Embedded Replicas

Turso’s embedded replicas are a game-changer for SQLite, making it more flexible and suitable for various environments. This feature shines especially for those using VMs or VPS, as it lets you replicate a Turso database right within your applications without needing to relying on Turso’s edge network. For mobile applications, where stable connectivity is a challenge, embedded replicas are invaluable as they allow uninterrupted access to the local database.

Embedded replicas provide a smooth switch between local and remote database operations, allowing the same database to adapt to various scenarios effortlessly. They also ensure speedy data access by syncing local copies with the remote database, enabling microsecond-level read operations — a significant advantage for scenarios demanding quick data retrieval.

​

How it works

1. You configure a local file to be your main database.

   • The url parameter in the client configuration.

2. You configure a remote database to sync with.

   • The syncUrl parameter in the client configuration.

3. You read from a database:

   • Reads are always served from the local replica configured at url.

4. You write to a database:

   • Writes are always sent to the remote primary database configured at syncUrl.
   • Any write transactions with reads are also sent to the remote primary database.
   • Once the write is successful, the local database is updated with the changes automatically (read your own writes — can be disabled).

​

Periodic sync

You can automatically sync data to your embedded replica using the periodic sync interval property. Simply pass the syncInterval parameter when instantiating the client:

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

const client = createClient({
  url: "file:path/to/db-file.db",
  authToken: "...",
  syncUrl: "...",
  syncInterval: 60,
});

​

Read your writes

Embedded Replicas also will guarantee read-your-writes semantics. What that means in practice is that after a write returns successfully, the replica that initiated the write will always be able to see the new data right away, even if it never calls sync().

Other replicas will see the new data when they call sync(), or at the next sync period, if Periodic Sync is used.

​

Encryption at rest

Embedded Replicas support encryption at rest with one of the libSQL client SDKs. Simply pass the encryptionKey parameter when instantiating the client:

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

const db = createClient({
  url: "file:encrypted.db",
  encryptionKey: process.env.ENCRYPTION_KEY,
});

​

Usage

To use embedded replicas, you need to create a client with a syncUrl parameter. This parameter specifies the URL of the remote Turso database that the client will sync with:

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

const client = createClient({
  url: "file:replica.db",
  syncUrl: "libsql://...",
  authToken: "...",
});

You can sync changes from the remote database to the local replica manually:

await client.sync();

​

Things to know

• Do not open the local database while the embedded replica is syncing. This can lead to data corruption.
• In certain contexts, such as serverless environments without a filesystem, you can’t use embedded replicas.
• There are a couple scenarios where you may sync more frames than you might expect.
  • A write that causes the internal btree to split at any node would cause many new frames to be written to the replication log.
  • A server restart that left the on-disk wal in dirty state would regenerate the replication log and sync additional frames.
  • Removing/invalidating the local files on disk could cause the embedded replica to re-sync from scratch.
• One frame equals 4kB of data (one on disk page frame), so if you write a 1 byte row, it will always show up as a 4kB write since that is the unit in which libsql writes with.

​

Deployment Guides