Durability Tiers
Look up the read and write durability tiers and how far each one waits for data to travel.Write waits distinguish local persistence from Core acceptance. Synchronization continues with either choice.
| Tier | Where | What confirmation means |
|---|---|---|
"local" | This device | Saved by the local persistence driver, without waiting for the network. |
"global" | Core | Authorized and durably accepted by Core. Other clients receive updates through their subscriptions. |
For background on how data flows between tiers, see How Sync Works.
Write tiers
Mutations such as insert, upsert, update, delete, and restore apply locally with no
durability guarantee and return a MutationResult. Transaction helpers resolve to the same kind of
result. Call .wait({ tier: ... }) when you need confirmation that the mutation reached a specific
durability tier.
See Writing Data for detailed guidance on which tier to use and code examples.
Mutation errors
Jazz throws errors it can detect locally as soon as you call the mutation. The server may reject the
change later, e.g. if the user does not have permissions. The change can appear locally before that
rejection arrives. If this happens, .wait(...) rejects and Jazz removes the local change.
If you are not waiting with .wait(...), use db.onMutationError(listener) to handle a rejection.
Transactions use .wait(...) and report errors in the same way as individual mutations.
Read tiers
Read choices control which data a query uses and when its first result is delivered. They are intentionally separate from write durability.
New applications should use the two product read choices "local-first" and "remote":
"local-first"uses cached local knowledge and shows pending local writes immediately, while still syncing."remote"uses the server's current query scope, without pending local writes. A one-shot remote read made during an outage rejects with a transport error once the client has noticed the server is unreachable (a few seconds in), even while it keeps reconnecting.
On the thin client every read is a server read, whatever its tier. While the backend is unreachable, one-shot reads and subscriptions wait and are answered after the reconnect. To keep reading while offline, upgrade to the local-first client.
Without a tier, browser and React Native clients read "local-first", and when they have a server
the first result waits up to 5 seconds for it (see below). Other clients read "remote" when they
have a server, and "local-first" when they don't.
Remote reads and your own writes:
- A one-shot remote read (
db.all,db.one) is answered after your earlier writes have been uploaded, so it sees them. - A remote subscription shows pending writes only once the server confirms them.
- Neither holds across a reconnect yet: writes still being re-sent after a reconnect may be missing from a remote read (#3863).
Waiting for the server (firstLoadRemoteWaitMs)
A local-first read accepts an optional firstLoadRemoteWaitMs that bounds how long
its first result may wait for the server. With an explicit tier: "local-first" the default is 0,
plain "local-first". A browser or React Native read that names no tier defaults to 5000 when a
server is configured; pass firstLoadRemoteWaitMs: 0 to show local data at once. TypeScript rejects
the option with "remote" (JavaScript callers have it ignored).
Only the initial load waits: a one-shot read, or a subscription's first callback. While the client
looks online (its connection is live, or its connection attempt started less than five seconds
ago), the first result waits up to firstLoadRemoteWaitMs for the server's answer and then shows that
server-confirmed result, together with the client's own pending writes. If the server has not
answered by then, the local result is shown. The read waits even when local data exists, but never
longer than the timeout.
On the local-first client it never waits on a server it cannot reach. The first result is local, and immediate, when no
server is configured, after db.disconnect(), while the connection is down or retrying, or when the
connection attempt fails. If the connection drops during the wait, the local result is delivered at
that moment. After the first result, a subscription behaves exactly like "local-first": local
writes show immediately and remote rows appear as they sync.
Queries with an offset are the exception. A partly synced local cache would apply the offset to
the wrong rows, so while waiting an offset window reads the server's page. If the timeout passes
first, it shows the cached page; a subscription then switches to the server's page when it
arrives, so rows can shift at that moment.
Removed read tiers
Reads accept only "local-first" and "remote"; any other name throws.
"local-first-unless-empty"(ReadTier.LocalFirstUnlessEmpty) was removed. It showed a non-empty cache at once and made only an empty local result wait for the server, without a time limit once connected. Use"local-first"plus afirstLoadRemoteWaitMsof, for example, a few seconds. The new option also waits when the cache has data, but is always bounded by the timeout.- The read names
"local"and"global"(and the"core"alias) were removed. Use"local-first"for"local"and"remote"for"global". A one-shot"remote"read still sees your earlier writes, but a"remote"subscription shows your pending writes only once the server confirms them, where the old"global"subscription showed them at once. "remote-if-possible"and"edge"were removed in alpha.57.
Losing remote access does not erase cached data: local-first reads may still show it. An actual synced deletion, however, hides the row from local reads too.
Write durability is separate and unchanged: it uses wait({ tier: "local" | "global" }).
These options apply to:
db.all(query, options?)db.one(query, options?)db.subscribe(query, callback, options?)useAll(query, options?)/useAllSuspense(query, options?)(React/Expo)new QuerySubscription(query, options?)(Svelte)useAll(query, options?)(Vue)useAll(() => ({ query, options }))(Solid)
The React Native/Expo alpha uses these same read and write durability tiers
after opening its client with createJazzClient. Its native
relay owns persistence and upstream connectivity; do not substitute a browser
storage driver or a JavaScript-side SQLite path.
App.tsxconst remoteTodos = useAll(app.todos, { tier: "remote" });
App.vueexport function subscribeTodosAtGlobal(db: Db, onCount: (count: number) => void) {return db.subscribe(app.todos.where({ done: false }), (todos) => onCount(todos.length), {tier: ReadTier.Remote,});}
App.svelteconst remoteTodos = new QuerySubscription(app.todos, { tier: 'remote' });
App.tsxexport function subscribeTodosAtGlobal(db: Db, onCount: (count: number) => void) {return db.subscribe(app.todos.where({ done: false }), (todos) => onCount(todos.length), {tier: ReadTier.Remote,});}
app.tsexport async function readTodosAtRemoteTier(db: Db) {return db.all(app.todos.where({ done: false }), { tier: ReadTier.Remote });}
app.tsexport const readTodosAtRemoteTier = Effect.gen(function* () {const jazz = yield* Jazz;return yield* jazz.all(app.todos.where({ done: false }), { tier: ReadTier.Remote });});
For most queries and subscriptions, omitting a tier is the right choice: Jazz delivers results from local storage immediately and streams in remote updates as they arrive. Reserve explicit tiers for cases where eventual consistency is not acceptable.