Live queries

A live query is a registered Drizzle query. The browser sends its reference and validated JSON arguments. It never sends SQL.

Register the query

This is the complete generated query file.

src/queries.ts

import { api } from "@chardb/core/server";
import { desc, eq } from "drizzle-orm";
import { z } from "zod";
import { messages } from "./schema.ts";

export const listMessages = api.query({
  ref: "messages#list",
  args: z.object({
    organizationId: z.string(),
    limit: z.number().int().min(1).max(100).default(50),
  }),
  query: (db, args) => db
    .select()
    .from(messages)
    .where(eq(messages.organizationId, args.organizationId))
    .orderBy(desc(messages.createdAt), desc(messages.id))
    .limit(args.limit),
});

Keep ref stable after release. It identifies the query across the browser bundle, Worker, reconnects, and pending subscriptions. The organization predicate is required even though CharDB also applies the ownership policy. It tells the router which partition can answer the query. Configure one client with the public Worker URL and the same Better Auth client. CharDB derives /ws from this URL.

src/web/App.tsx

const workerUrl = window.location.origin;
const db = createChardbReactClient({
  url: workerUrl,
  ownership: "organization",
  auth: ({ baseURL }) => createAuthClient({
    baseURL,
    plugins: [anonymousClient(), organizationClient(), jwtClient()],
  }),
});

Pass the exported handle to the configured client. It reads the active organization from Better Auth and adds organizationId to the wire arguments.

src/MessageList.tsx

import { listMessages } from "./queries.ts";

export function MessageList() {
  const { data: messages = [], state } = db.useQuery(listMessages, {
    limit: 50,
  });

  if (state === "pending") return <p>Loading messages...</p>;

  return messages.map((message) => (
    <p key={message.id}>{message.body}</p>
  ));
}

pending means the first snapshot has not arrived. live means the subscription is current. refetching means CharDB could not safely resume an earlier snapshot and is replacing it.

Write through a mutation

const post = db.useMutation(postMessage);

await post({
  id: crypto.randomUUID(),
  body: "ship it",
});

The client adds the active organization and retains one mutation ID while it reconnects, so a retry does not create a second write. Every matching subscription receives a complete replacement snapshot after the commit. Use Files when a row needs an attachment.

Core

Clients

Features

Operate

Plan ahead

Cookbook

Register the query

Write through a mutation

​Register the query

​Subscribe in React

​Write through a mutation

Register the query

Subscribe in React

Write through a mutation