Skip to main content
This particular usage uses the Turso Cloud to sync the local Turso databases and assumes that you have an account.
Partial sync lets your app open and use a database without downloading the entire file. The client lazily fetches pages of the database file from the Turso Cloud when a query touches data that is not present locally. This reduces startup time and network usage for large databases, while remaining fully compatible with the push/pull methods used by Turso’s standard sync solution.
  • Reads on not-yet-downloaded data transparently trigger on-demand page fetches.
  • Writes still apply locally first and are pushed as logical statements.

​
Modes

Two bootstrap strategies define what is present locally at connect time:
  • Prefix bootstrap: download the first N bytes of the database file.
    • Good default when you want a minimal, predictable starting footprint.
  • Query bootstrap: download pages touched by running a server-side SQL query.
    • Ideal to hydrate only a narrow working set (e.g., a single user’s rows, small tables with metadata, references, etc).
Both modes continue to lazily fetch missing pages on demand.

​
Prefix bootstrap

import { connect } from '@tursodatabase/sync';

const db = await connect({
  path: './app.db',
  url: 'libsql://...',
  authToken: process.env.TURSO_AUTH_TOKEN,
  partialSync: {
    bootstrapStrategy: { kind: 'prefix', length: 128 * 1024 }, // 128 KiB
  },
});

​
Query bootstrap

import { connect } from '@tursodatabase/sync';

const db = await connect({
  path: './app.db',
  url: 'libsql://...',
  authToken: process.env.TURSO_AUTH_TOKEN,
  partialSync: {
    bootstrapStrategy: {
      kind: 'query',
      query: `SELECT * FROM messages WHERE user_id = 'u_123' LIMIT 100`,
    },
  },
});

​
Optimizations

​
Segment size (batched lazy reads)

segment size
When the client needs a page that isn’t present locally, partial sync performs an on-demand fetch from the remote database. To reduce round-trips and speed up these fetches, you can configure the segment size: instead of requesting a single page, the client downloads a whole segment of pages in one request. This lets the client amortize network overhead and hydrate nearby pages that are likely to be accessed soon. How it works Suppose your database has:
  • page_size = 4 KiB
  • segment_size = 16 KiB
If a local query touches page 6, the client computes the segment that page belongs to:
  • 16 KiB segment = 4 pages
  • Segment covering page 6 = pages 5-8
The client then fetches all four pages in a single request and stores them locally. Future reads to those pages incur no additional network cost. Benefits
  • Fewer HTTP requests (one segment fetch vs. many single-page fetches)
  • Faster hydration of hot ranges
  • Better performance for workloads with spatial locality (e.g., range scans, index lookups)
Default The default segment_size is 128 KiB (typically 32 pages on a 4 KiB page size), which provides a good balance between request overhead and total bytes transferred.
If your workload touches data in tight clusters (e.g., reading several adjacent rows), larger segment sizes can significantly improve performance.Conversely, very sparse/random-access workloads may benefit from smaller segment sizes.
await connect({
  ...
  partialSync: {
    bootstrapStrategy: { kind: 'prefix', length: 128 * 1024 }, // 128 KiB
    segmentSize: 16 * 1024,
  },
});

​
Prefetch

prefetch
Prefetch is an optional optimization that builds on top of lazy page fetches. When enabled, the client not only retrieves the pages required by the current query, but also inspects the structure of the newly downloaded pages and recent access patterns to predict which pages are likely to be needed next. If the client detects a natural continuation of the access pattern — such as child pages referenced by an internal B-tree node — it proactively downloads those pages in advance. This reduces the number of future on-demand fetches and helps avoid stalls during operations like range scans, index walks, or sequential lookups. 
await connect({
  ...
  partialSync: {
    bootstrapStrategy: { kind: 'prefix', length: 128 * 1024 }, // 128 KiB
    prefetch: true,
  },
});
segment_size and prefetch are complementary.Segment size batches nearby pages into a single on-demand fetch, while prefetch looks at the query’s access pattern and proactively fetches additional pages likely to be needed next.Using both together can provide the best performance for real-world workloads.