Introduction
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.
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
| Part | What 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.