Getting started

Introduction

What drizzle-resource does, what it replaces, and when to use it.

drizzle-resource builds list endpoints on Drizzle ORM. You declare a resource for a table, and every query against it takes one typed request and returns rows, page info, facet counts and totals.

A resource says:

  • which relations each row loads;
  • which fields clients may filter, search, sort and facet on;
  • which tenant rule every query must carry.

Select a key in the definition below to see what it adds to the request, the SQL, the types and the table.

orders.resource.ts14 lines
1export const orders = engine.defineResource("orders", {
2 views: { list: { select: { reference: true,
3 totalAmount: true, customer: { select: { name: true } } } } },
4 query: {
5 scope: (f, ctx) => f.is("customer.orgId", ctx.orgId),
6 search: { allowed: ["reference", "customer.name"] },
7 sort: { defaults: [{ key: "createdAt", dir: "desc" }] },
8 facets: { allowed: ["status"] },
9 pagination: { modes: ["cursor"] },
10 },
11 summary: (o) => ({
12 revenue: sum(o.totalAmount),
13 }),
14});
Request it acceptsvalidated
{
  view: "list",
  search: { value: "halv" },
  sorting: [{ key: "createdAt", dir: "desc" }],
  facets: [{ key: "status" }],
  pagination: { mode: "cursor", pageSize: 25 },
  summary: true,
}
// orgId comes from the server, never the client
SQL it runsPostgreSQL
select "reference", "total_amount", c."name"
from "orders" join "customers" c on ...
where c."org_id" = $1
  and ("reference" ilike $2 or c."name" ilike $2)
order by "created_at" desc, "id" desc
limit 26
-- one aggregate statement
select "status", count(*), sum("total_amount")
group by grouping sets (("status"), ())
Types you getinferred
type Row = {
  reference: string; totalAmount: number;
  customer: { name: string }
}
type Response = {
  rows: Row[];
  pageInfo: { nextCursor: string | null };
  facets: { status: { value: string; count: number }[] };
  summary: { revenue: string | null };
}
type SortKey = "createdAt" | "reference" | …
type SearchField = "reference" | "customer.name"
Table it powersyour UI
🔒 acmeSearch “halv”
shipped 612
pending 231
processing 264
cancelled 98
referencecustomertotal
ORD-29999Halvorsen Freight$4,128
ORD-29981Halvorsen Freight$790
ORD-29944Halvorsen Freight$2,310
sorted by createdAt ↓
revenue $411,230Next →

scopeThe tenant rule wraps every request on the server. The client can't send it or remove it.

What it replaces

Without it, each list endpoint parses its own query string, builds its own WHERE clause, runs its own count, and adds extra queries for filter sidebars:

// orders.controller.ts, and a slightly different copy for every other table
const 
page
=
Number
(
req
.
query
.
page
) || 1
const
pageSize
=
Number
(
req
.
query
.
pageSize
) || 20
const
sort
=
req
.
query
.
sort
|| 'createdAt'
const
dir
=
req
.
query
.
dir
=== 'asc' ? 'asc' : 'desc'
const
search
=
req
.
query
.
search
as string
const
where
=
and
(
eq
(
orders
.orgId,
ctx
.
user
.
orgId
),
search
?
or
(
ilike
(
orders
.
reference
, `%${
search
}%`), ...) :
undefined
,
) const [
rows
, [{
count
}]] = await
Promise
.
all
([
db
.
query
.
orders
.
findMany
({
with
: {
customer
: true },
limit
:
pageSize
,
// @ts-expect-error example placeholder
offset
: (
page
- 1) *
pageSize
,
// @ts-expect-error example placeholder
orderBy
,
}),
Promise
.
resolve
(
countRows
),
])

Each copy differs a little: other sort parameters, other search fields, a count that ignores one of the filters. Clients have to learn a new request shape per endpoint, and the tenant check has to be remembered in every one.

The three parts

PartWhat it does
createQueryEngine({ db, schema, relations })Binds to your Drizzle setup once. Field paths and types are derived from your schema and relations.
engine.defineResource(root, options)Declares one list endpoint: relations to load, field rules, tenant scope, views, totals and optional custom stages.
resource.query({ request, context })Runs a request: scope, validation, the page of ids, the rows, then facets and totals when asked for.

The request has the same shape for every resource, so a frontend data table can talk to all of them.

What it does not do

  • It does not replace Drizzle. It uses your Drizzle instance, schema and relations.
  • It does not handle writes, migrations, authentication or routing.
  • It is not an HTTP framework. You call it from your own route handlers.

When to use it

  • Admin interfaces with sortable columns, a search box and filter panels.
  • Filter sidebars that need bucket counts next to the result list.
  • APIs consumed by a data table component that expects one request and response shape.
  • Multi-tenant backends where every list query must be limited to the caller's tenant.

If you have one endpoint with simple needs and want to write the SQL yourself, you don't need it. It pays off once several tables need the same behaviour.

Copyright © 2026