Rocicorp Monorepo

Rocicorp maintains two primary products: Zero and Replicache.

• Zero: A sync engine for building real-time applications. It consists of a client library (zero-client), server-side code (zero-cache), and a query language/IVM engine (zql).
• Replicache: A client library designed for building highly responsive, offline-capable applications.

The z2s package is a compiler that translates ZQL (Zero Query Language) into SQL. It is designed to facilitate the following workflows:

1. Backend Execution: Running ZQL queries directly against your backend database.
2. Code Sharing: Sharing query logic between the frontend and backend applications.
3. Generative Testing: Supporting the testing of ZQL by comparing its output against standard SQL databases.

The ZQL Query Planner is a cost-based optimizer designed to handle WHERE EXISTS and NOT EXISTS (correlated subquery) statements. It optimizes query execution by deciding between different join strategies, such as semi-joins or flipped joins, based on estimated costs and constraints.

Key decisions made by the planner include:

• Join direction: Determining whether to scan the parent or child table first.
• Cost estimation: Calculating the expected cost of various execution plans.
• Constraint propagation: Determining how join predicates constrain table scans.

When planning queries with EXISTS clauses and LIMIT clauses, it is critical to distinguish between two types of selectivity to ensure correct cost estimation:

1. Filter Selectivity: The fraction of child rows that pass filter predicates (e.g., if 50% of posts are published, filter selectivity is 0.5).
2. Semi-Join Selectivity: The fraction of parent rows that have at least one matching child (e.g., what percentage of users have at least one published post).

These are only equal when the fan-out (average number of child rows per parent row) is exactly 1. For one-to-many relationships, the semi-join selectivity is typically much higher than the filter selectivity.

Replicache is optimized for specific workload ranges. If your application operates outside these ranges, contact the Replicache team for guidance:

The Zero E2E Throughput Benchmark is designed to measure the maximum sustainable PostgreSQL write throughput Zero can handle before connected clients experience unbounded lag. It measures the full data path: PostgreSQL writes $\rightarrow$ Replicator (WAL) $\rightarrow$ View-syncer (diff production) $\rightarrow$ Synthetic clients (protocol application).

Key Metrics for Sustainability: A write rate is considered sustainable for a profile if:

• All required clients remain connected.
• Initial sync completes before the measurement window.
• p95 and p99 client-visible lag stay under the configured Service Level Objective (SLO).
• seqLag remains bounded.
• lagSlope is approximately zero or negative after the warmup period.

Replicache is available via the following packages:

• packages/replicache: The core Replicache client library.
• packages/replicache/doc: The documentation for Replicache.

When properly integrated with a backend, Replicache provides Causal+ Consistency. This model provides three primary guarantees for distributed operations (mutations):

• Causal: Causally-related mutations always appear in the same causal order on all clients.
• Convergent: All clients eventually converge on the same ordering of operations.
• Progressive: Clients see progressively newer states of the world and never see operations out of order.

Replicache achieves this by using a combination of tentative transactions (which execute speculatively with causal consistency and may be reordered or re-executed) and a totally ordered prefix of final transactions provided by the server.

Replicache is designed for "memory-fast" performance. Use the following rules of thumb to estimate operation speeds:

The Zero Query Fuzzer uses a layered approach to ensure correctness across the entire stack. The core principle is that any query through Zero must yield the same result as the same query evaluated against PostgreSQL. The fuzzer expands in concentric circles from the innermost engine to the full client behavior:

• L0: IVM Engine: Validates ZQL query semantics and incremental maintenance (the fastest signal).
• L1: Replicator + zero-cache Storage: Validates WAL decoding, replication ordering, schema mapping, and type conversions.
• L2: zero-cache Protocol: Validates protocol serialization, patch/diff construction, and subscription lifecycles.
• L3: zero-client: Validates client-side materialization, local cache application, and reconnection/hydration.
• L4: Full Client Behavior: Validates optimistic mutations, multi-client interactions, and auth/permission filters.