Zero 1.5

Schema Change Improvements and Client Group Auth

Installation

Copynpm install @rocicorp/zero@1.5

Upgrading

userID: "anon"

If you are using userID: 'anon' for logged-out users, change it to userID: null or userID: undefined. Passing userID: 'anon' is deprecated because it can't work with Authenticated Client Groups (below).

Change this:

Copyimport {ZeroProvider} from '@rocicorp/zero/react'
 
return (
  <ZeroProvider userID={userID ?? "anon"}>
    <App />
  </ZeroProvider>
)

To this:

Copyimport {ZeroProvider} from '@rocicorp/zero/react'
 
return (
  <ZeroProvider userID={userID}>
    <App />
  </ZeroProvider>
)

Authenticated Client Groups

The handleQueryRequest and handleMutateRequest helpers now take an options object instead of multiple arguments. They also require a new userID parameter.

Change this:

Copy// query handler
handleQueryRequest(
  (name, args) => {
    const query = mustGetQuery(queries, name)
    return query.fn({args})
  },
  schema,
  request,
)
 
// mutate handler
handleMutateRequest(
  dbProvider,
  transact => transact((tx, name, args) => {
    const mutator = mustGetMutator(mutators, name)
    return mutator.fn({args, tx})
  }),
  request,
)

To this:

Copy// query handler
handleQueryRequest({
  handler: (name, args) => {
    const query = mustGetQuery(queries, name)
    return query.fn({args})
  },
  schema,
  request,
  userID,
})
 
// mutate handler
handleMutateRequest({
  dbProvider,
  handler: transact => transact((tx, name, args) => {
    const mutator = mustGetMutator(mutators, name)
    return mutator.fn({args, tx})
  }),
  request,
  userID,
})

This is a security enhancement and is recommended for all users. See Why pass userID back to Zero? and PR 5836 for more information. The old signature is still supported but deprecated.

Deploy Order

Make sure to deploy zero-cache before your API server. This is existing standard practice for Zero, but it matters for this release because the 1.5 handleQueryRequest and handleMutateRequest helpers return a new response shape that zero-cache 1.4 cannot parse.

Features

• Schema Change Hooks: Added zero_<shard>.update_schemas(), so databases that do not support or allow event triggers can manually notify Zero after schema changes. The Supabase publication-change workaround is also simpler: after ALTER PUBLICATION, only a trailing COMMENT ON PUBLICATION is needed.

Performance

• Faster flipped-join fetches when the parent key is unique

Fixes

• zero-cache enforces that authenticated userID matches clientGroup
• CREATE/DROP INDEX CONCURRENTLY could break replication
• Long-lived connections could miss periodic auth revalidation
• Allow omitting ctx param when no context type is defined
• Make /keepalive timeout + graceful-shutdown opt-in except in ECSs
• Error: pipelines must be initialized during transform or drain
• Shadow sync could miss its first run before replication-manager restarted
• Row-set drift across view-syncer re-hydration could result in stale rows
• Make WebSocket compression and max-payload settings client-only

Breaking Changes

None. Two APIs were deprecated:

• userID: 'anon' for logged-out clients
• The positional signatures of handleQueryRequest and handleMutateRequest

See Upgrading for more information.