Skip to main content
This guide shows how to set up a Turso database and use the sync features from your application.
This particular usage uses the Turso Cloud to sync the local Turso databases and assumes that you have an account.
1

1. Setup Turso Cloud database

  • Follow our Quickstart to install the CLI, create a database
  • Get the database URL (libsql://...): 
turso db show <db>
  • Create a token for your app:
turso db tokens create <db>
2

2. Setup a basic connection with sync

You need three essentials to enable sync:
  • Local path: where the local, synced tursodb file is stored
  • Remote URL: your Turso Cloud URL (libsql://...)
  • Auth token: Turso Cloud token to authenticate requests
import { connect } from '@tursodatabase/sync';

const db = await connect({
  path: './app.db',                               // local path
  url: 'libsql://...',                            // remote URL (generated with turso db show <db-name> --url)
  authToken: process.env.TURSO_AUTH_TOKEN,        // authentication token (generated with turso db tokens create <db-name>)
  // longPollTimeoutMs: 10_000,                   // optional: server waits before replying to pull
  // bootstrapIfEmpty: false,                     // set to false to avoid bootstrapping on first run
});
On the first run, the local database is automatically bootstrapped from the remote — so the remote must be reachable during the initial connect.If you set bootstrap_if_empty to false, the local database will start empty instead. You can bootstrap or update it later at any time by explicitly calling pull().
3

3. Push changes

Push sends your local changes to the Turso Cloud server. Under the hood, logical statements are sent, and on conflicts the strategy is “last push wins”.
await db.exec("CREATE TABLE IF NOT EXISTS notes(id TEXT PRIMARY KEY, body TEXT)");
await db.exec("INSERT INTO notes VALUES ('n1', 'hello')");

await db.push();
4

4. Pull changes

Pull fetches remote changes and applies them locally. It returns a boolean indicating whether anything changed.
  • Configure long_poll_timeout_ms/LongPollTimeoutMs if you want the server to wait for changes and avoid empty replies.
  • If you pushed earlier, a subsequent pull can still return that something changed due to server-side conflict resolution frames.
// Returns true if anything changed locally
const changed = await db.pull();
console.info('pulled changes:', changed);
5

5. Checkpoint

Checkpoint compacts the local WAL to bound local disk usage while preserving sync state.
await db.checkpoint();
6

6. Stats

Stats help you observe sync behavior and usage (WAL sizes, last push/pull times, network usage, revision, etc.).
const s = await db.stats();
console.info({
  cdcOperations: s.cdcOperations,
  mainWalSize: s.mainWalSize,
  revertWalSize: s.revertWalSize,
  networkReceivedBytes: s.networkReceivedBytes,
  networkSentBytes: s.networkSentBytes,
  lastPullUnixTime: s.lastPullUnixTime,
  lastPushUnixTime: s.lastPushUnixTime,
  revision: s.revision,
});