Offline-first replication

sync keeps a local copy of a person's rows on their device, so the app works with no network and merges back when it is online. Reach for it for notes, tasks and field work.

The app pushes what it did and pulls what others did when it flushes. Two devices that changed the same row while apart keep both changes, field by field. Every row is checked for the caller's tenant and access on its way in and on its way out, and erasing a person reaches every device.

sync:
  driver: local
  tables:
    notes: { version: 1, conflicts: last-writer-wins }
  quota: { rows: 100000, bytes: 50MB, batch: 500 }
  max-clock-drift: 5m
  page: 500

import { sync } from "mainsdk/experimental/sync";

const replica = await sync.open({ tables: ["notes"], for: user, transport });   // local copy, scoped to the user's tenant
await replica.notes.insert({ text: "works offline" });                          // merged when the device is back online
await replica.flush();

sync:
  driver: local

Quick start

sync:
  driver: local
  tables:
    notes: { version: 1, conflicts: last-writer-wins }
  quota: { rows: 100000, bytes: 50MB, batch: 500 }
  max-clock-drift: 5m

import { sync } from "mainsdk/experimental/sync";
import { SyncServer } from "mainsdk/experimental/sync-server";

declare const config: Record<string, unknown>;        // the sync section of main.yaml
declare const access: ConstructorParameters<typeof SyncServer>[0]["access"];

const server = new SyncServer({ config, access });
const who = { id: "u_1", tenant: "t1" };

const replica = await sync.open({ tables: { notes: { version: 1 } }, for: who, transport: server.transport(who) });
await replica.notes.insert({ text: "works offline" });
await replica.flush();

In an app the device and the server are different machines: the server serves server.handler(who) over HTTP and the device opens its replica with httpTransport(url, { fetch }).

Configuration

What you get

Always:

• Reads and writes never wait for the network. A write is saved to the replica's store before the call returns.
• Two edits to different fields of one row both survive. Two edits to the same field keep the later one and record the clash.
• The server checks the tenant and the person's access on every pushed and pulled row, with the same function collab uses.
• A device on another schema version of a table is refused and keeps its queue.
• Erasing a person removes their rows from every device, and wipes the devices of that person.

Examples

Keep the server's value on a table

sync:
  tables:
    prices: { version: 1, conflicts: server-wins }
    tags: { version: 1, conflicts: "action:merge-tags" }

With server-wins a device's clashing write is recorded in replica.conflicts() and the server's value stays. With action:merge-tags pass resolve to SyncServer; it receives the table, the field and both values and returns what the field becomes.

Store a replica on the device

import { type SyncStorage } from "mainsdk/experimental/sync";

declare const indexedDb: SyncStorage;       // your IndexedDB or Expo SQLite driver

export const store: SyncStorage = indexedDb;

A store is five calls: get, set, delete, keys(prefix) and clear. Pass it as storage to sync.open.

Errors and checks

mainsdk check reports MAIN-SYNC-0007 for a synced table with no whole-number version or a conflicts value it does not know, with the line in main.yaml. Each code's cause and fix is in check codes.

Swapping drivers

The server keeps rows through a store port and the device through a replica store port. local keeps both in memory. A database driver for the server and IndexedDB and Expo SQLite stores for devices plug into the same ports, and ElectricSQL and PowerSync come later as drivers. The calls do not change.

Testing

syncRig() from @mainsdk/testing gives a server on a simulated clock, devices whose network you switch off and whose clocks you skew, and an access rule you set. No network and no timers: time moves when the test moves it. See Test your app.

Security and privacy

• A pushed change stamped for another tenant fails the whole push. Every row is checked for write on the way in and for read on the way out.
• The server sets a row's owner from the caller, never from the device, and refuses stamps from the future.
• privacy.erase removes a person's rows here when the server is built with privacy and tenant; devices learn on their next pull.
• Rows are stored in the tenant's region record. Fields carry no author, so erasing removes the rows a person owns, not their edits inside rows others own.

Next

• Use offline-first replication in your app: the steps, end to end.
• Realtime
• Access