Zero 0.25

DX Overhaul, Query Planning

Installation

npm install @rocicorp/zero@0.25

Overview

This release massively overhauls and simplifies the entire Zero API.

Conceptually, Zero is now just schemas, queries, and mutators.

There are no longer first-class auth or permission systems. There are no longer "custom mutators" and "crud mutators", or "synced queries" and "zql queries".

All the old APIs have been deprecated, and the docs have been rewritten and simpilfied. Additionally, this release introduces a raft of big new features.

To ease the transition, and allow access to new features without a ton of work, you can still use the old APIs via the enableLegacyQueries and enableLegacyMutators flags. Note that support for these older APIs will be removed for the Zero beta early next year.

Upgrading

We have implemented both "minimal" and "maximal" sample upgrades.

The minimal upgrades show how to update to 0.25 with very little work, by opting into deprecated APIs:

The maximal upgrades show how to use all the new features. Refer to the commit log of each PR for step-by-step examples of how to upgrade:

Additionally, the old hello-zero sample has been updated from the original CRUD mutators and queries all the way to the latest hotness. So if you were still using those APIs, you can use this as a guide to upgrade.

Features

  • Query Planning: Zero now automatically plans joins, similar to other databases. You no longer need to specify flip:true to optimize whereExists() calls.
  • Reworked Query DX: Queries now receive a Context automatically – you don't have to pass it at the call site. Also, any Standard Schema conforming library can be used for validation and the API has been generally simplified and streamlined.
  • Reworked Mutator DX: The mutator API has been overhauled to match queries. Mutators now also support validation.
  • drizzle-zero and prisma-zero are now first-class: They have moved into the rocicorp org and are now officially supported.
  • Default Schema Type: The Schema type can now be registered as a default with Zero. You can just say useZero() – useZero<Schema> is no longer needed. You can also delete your createUseZero() helper if you have one. This registration happens by default if you use the new drizzle-zero or prisma-zero packages.
  • New Connection Status API: Brand new connection status API with overhauled error-handling and reconnection behavior.
  • Mutator promises now return structured errors: The client and server promises now always resolve. In the case of an error, they now return a structured error object.
  • New Install Guide: Rewritten guide to add Zero to an existing project.
  • New zero-out tool: Removes all trace of Zero from Postgres.
  • Support for Generated Columns: In Postgres 18+, generated stored columns are now synced. This is useful for denormalizing data from JSON columns to support filtering in Zero.

Performance

Queries should be 0.2x to 4x faster, depending on the query. Some highlights:

Fixes

Breaking Changes

Despite the large DX update, we tried to make the upgrade as smooth as possible. However, there are a few breaking changes we could not easily avoid.

  1. If you do not want to immediately opt-in to the new query and mutator APIs, set enableLegacyQueries and enableLegacyMutators to true in your schema.ts.
  2. If you are using the .client or .server promises with custom mutators, these no longer ever reject. They now always resolve with a result type that has success/error cases
  3. Mutators now reject while Zero is offline. You may want to use the new Connection Status API to detect this and display custom UI to users.
  4. The pattern for reauthentication has changed. The auth parameter is now always a string – the function form is no longer supported. Instead, call zero.connection.connect({auth: token}) to reconnect. This was done to simplify the API and support reauth via cookies consistently.
  5. The onError feature of Zero has been removed. It was undocumented and only half-working. Please use the new Connection Status API to detect errors and display custom UI to users.