Zero is a query-driven sync engine for TypeScript apps. It replicates Postgres into a SQLite replica inside `zero-cache`, then syncs subsets of rows to clients based on the queries your app runs. Client reads/writes hit local storage first (instant UI); `zero-cache` keeps clients up to date via logical replication.

Recommended reading order for wiring a Zero app: Install -> Schema -> Queries -> Auth -> Mutators -> ZQL -> Deployment/Config -> Debugging

## Key mental models

### Queries

- Clients do NOT send arbitrary queries to `zero-cache`.
- You define Queries and Mutators in code (`defineQueries`, `defineMutators`).
- The client runs its own ZQL optimistically against a local store (e.g. IDB), and `zero-cache` calls your server endpoints (`ZERO_QUERY_URL`) to resolve a name+args into ZQL/logic, where you also enforce permissions via `context`. `zero-cache` runs that returned ZQL against its SQLite replica, and returns the authoritative results to the client.
- Queries **must** be optimized, e.g. using `npx analyze-query`. The query plan commonly has `TEMP B-TREE` when it is not optimized. You should be cautious when adding complex/heavy queries that are not properly indexed in Postgres, since `zero-cache` derives indexes from upstream. See Slow Queries below.

### Mutators

- Mutators also run on the client optimistically first.
- The client can query the local store in a mutator, but a query must exist that is _active_ for the data to exist in the local store. See Reading Data for what "active" means.
- Mutations are then sent to `zero-cache`, which calls your server's `ZERO_MUTATE_URL` endpoint, where they run directly against Postgres upstream.

### Warnings/common pitfalls

- Zero types are registered globally with `declare module`.
- Treat query results as immutable (e.g. don't mutate returned objects from `useQuery`).
- Prefer client-generated random IDs passed into mutators over auto-increment IDs (e.g. using `uuidv7` or `nanoid`).
- Do not generate IDs inside mutators, since mutators run multiple times (sometimes twice on the client and once on the server).
- When auth errors occur, the client must reconnect manually using the Connection Status API.
- When developing locally, prefer creating migrations and executing them against the local database. Resetting the database during local development requires also deleting the SQLite replica and restarting `zero-cache`.

## Get Started

- [Quickstart](https://zero.rocicorp.dev/docs/quickstart)
- [Installation](https://zero.rocicorp.dev/docs/install)
- [Samples](https://zero.rocicorp.dev/docs/samples)

## Learning Zero

- [What is Sync?](https://zero.rocicorp.dev/docs/sync): A Slightly Opinionated Tour of the Space
- [When to Use](https://zero.rocicorp.dev/docs/when-to-use): And When Not To – A Quick Guide
- [Status](https://zero.rocicorp.dev/docs/status)

## Using Zero

- [Schema](https://zero.rocicorp.dev/docs/schema)
- [Authentication](https://zero.rocicorp.dev/docs/auth)
- [Reading Data](https://zero.rocicorp.dev/docs/queries): Reading and Syncing Data
- [Writing Data](https://zero.rocicorp.dev/docs/mutators): Writing Data
- [ZQL Reference](https://zero.rocicorp.dev/docs/zql): Zero Query Language
- [ZQL on the Server](https://zero.rocicorp.dev/docs/server-zql)
- [Connection Status](https://zero.rocicorp.dev/docs/connection)
- [Offline](https://zero.rocicorp.dev/docs/offline)

## Postgres

- [Provider Support](https://zero.rocicorp.dev/docs/connecting-to-postgres)
- [Feature Compatibility](https://zero.rocicorp.dev/docs/postgres-support)

## Integrations

- [React](https://zero.rocicorp.dev/docs/react)
- [SolidJS](https://zero.rocicorp.dev/docs/solidjs)
- [React Native](https://zero.rocicorp.dev/docs/react-native)
- [Community](https://zero.rocicorp.dev/docs/community)

## Deployment

- [Hosting](https://zero.rocicorp.dev/docs/deployment)
- [Configuration](https://zero.rocicorp.dev/docs/zero-cache-config)

## Debugging

- [Inspector](https://zero.rocicorp.dev/docs/debug/inspector)
- [Slow Queries](https://zero.rocicorp.dev/docs/debug/slow-queries)
- [Replication](https://zero.rocicorp.dev/docs/debug/replication)
- [Query ASTs](https://zero.rocicorp.dev/docs/debug/query-asts)
- [OpenTelemetry](https://zero.rocicorp.dev/docs/debug/otel)
- [zero-out](https://zero.rocicorp.dev/docs/debug/zero-out)

## Meta

- [Release Notes](https://zero.rocicorp.dev/docs/release-notes)
- [Reporting Bugs](https://zero.rocicorp.dev/docs/reporting-bugs)
- [Open Source](https://zero.rocicorp.dev/docs/open-source)
- [LLMs](https://zero.rocicorp.dev/docs/llms)