Database client

Every app gets a typed database client, generated from the workspace schema. Import it from zitejs/db:

import { zite } from 'zitejs/db';

The client is used inside backend workflows — the frontend never talks to the database directly. Each table is a property on zite, addressed by its SDK name (PascalCase), with fully-typed record types. Read the generated .zite/db.ts to see the exact names and types.

Methods

// Query many rows
const { records, hasMore } = await zite.Tickets.findAll({
  filter: { status: 'open' },
  sort: [{ field: 'createdAt', direction: 'desc' }],
  limit: 100,
  offset: 0,
});

// One row by id (or by filter)
const ticket = await zite.Tickets.findOne({ id: 'rec_123' });
const byEmail = await zite.Customers.findOne({ filters: { email: 'a@b.com' } });

// Create, update, delete
const created = await zite.Tickets.create({ record: { subject: 'Help', status: 'open' } });
const updated = await zite.Tickets.update({ id: created.id, record: { status: 'closed' } });
await zite.Tickets.delete({ id: created.id });

// Insert many (optionally upsert on matching fields)
const result = await zite.Customers.bulkCreate({
  records: [{ email: 'a@b.com' }, { email: 'c@d.com' }],
  matchOn: ['email'],
});

Method	Arguments	Returns
`findAll`	`{ limit?, offset?, sort?, filter?, fields? }`	`{ records, hasMore }`
`findOne`	`{ id? }` or `{ filters? }` (+ `fields?`)	the record, or `undefined`
`create`	`{ record }`	the created record
`update`	`{ id, record }`	`{ id, fields }`
`delete`	`{ id }`	`{ id }`
`bulkCreate`	`{ records, matchOn? }`	`{ success, records }`

Filters and sorting

Filters are objects keyed by field SDK name. A bare value means equality; an object applies an operator:

{ status: 'open' }                      // equality
{ createdAt: { gt: '2026-01-01' } }     // operator

Operator	Meaning	Example
(bare value)	Equals	`{ status: 'open' }`
`contains`	Substring match	`{ subject: { contains: 'refund' } }`
`gt`	Greater than	`{ createdAt: { gt: '2026-01-01' } }`
`gte`	Greater than or equal	`{ priority: { gte: 3 } }`
`lt`	Less than	`{ createdAt: { lt: '2026-02-01' } }`
`lte`	Less than or equal	`{ priority: { lte: 2 } }`

There is no eq or neq here — equality is the bare-value shorthand. The row filters in zite.permissions.json are a separate system and do have eq and neq.

Sort is an array: sort: [{ field: 'createdAt', direction: 'desc' }]. Use fields: ['subject', 'status'] to fetch only the columns you need.

findAll returns at most 2,000 records (hasMore tells you there are more). For counts, sums, group-bys, and joins, use zite.sql() — aggregating in JavaScript over a capped result set gives wrong numbers on large tables.

Read-only SQL

zite.sql() runs a single read-only SELECT against the workspace database using human-readable SDK names:

const { rows, rowCount, truncated } = await zite.sql({
  query: `
    SELECT "status", COUNT(*) AS n
    FROM "Tickets"
    WHERE "createdAt" > $1
    GROUP BY "status"
  `,
  params: ['2026-01-01'],
});

Always use SDK names, never display labels. A wrong name is a runtime error, not a type error:

Identifier	Convention	Quote?	Example
Table	PascalCase SDK name	Yes	`"Tickets"`
Field	camelCase SDK name	Yes	`"assigneeEmail"`
System column	lowercase	Optional	`id`, `created_at`, `updated_at`
Link table	Both table SDK names, alphabetical	Yes	`"Tickets"` + `"Users"` → `"TicketsUsers"`
Link table id column	camelCase table name + `Id`	Yes	`"ticketsId"`, `"usersId"`

Postgres lowercases unquoted names, which is why everything but the system columns must be double-quoted. The .zite/db.ts header lists the link tables for your workspace.

SELECT only. Pass runtime values through params ($1, $2, …) — never string-interpolate them into the query. Soft-deleted rows are excluded automatically.

Results are capped at 2,000 rows; truncated is true when the cap is hit.

Also on the client

The generated zite object also exposes zite.notifications (see Notifications) and zite.meta.listUsers() for the workspace’s users.

Get started

Core concepts

Build with agents

Zite.js framework

Tutorials

Recipes

Deploy

Resources

Methods

Filters and sorting

Read-only SQL

Also on the client

​Methods

​Filters and sorting

​Read-only SQL

​Also on the client

Methods

Filters and sorting

Read-only SQL

Also on the client