Query Methods

The superapp client exposes standard Drizzle ORM query methods. All methods return promises and queries are executed via Drizzle Proxy.

import { drizzle } from '@superapp/db'
import { eq, desc, count, sum } from 'drizzle-orm'
import * as schema from './generated/schema'

const db = drizzle({ connection, token, schema })

Method Reference

`db.select()`

Select rows from a table with optional filtering, sorting, joins, and pagination.

// All columns
const orders = await db.select().from(schema.orders)

// Specific columns
const orders = await db.select({
  id: schema.orders.id,
  amount: schema.orders.amount,
}).from(schema.orders)

Chainable methods:

Method	Description
`.from(table)`	Table to select from
`.where(condition)`	Filter condition
`.orderBy(column)`	Sort order (`asc()` or `desc()`)
`.limit(n)`	Maximum rows to return
`.offset(n)`	Rows to skip
`.leftJoin(table, on)`	Left join another table
`.innerJoin(table, on)`	Inner join another table
`.groupBy(column)`	Group results

import { eq, desc } from 'drizzle-orm'

const orders = await db.select({
  id: schema.orders.id,
  amount: schema.orders.amount,
  customerName: schema.customers.name,
}).from(schema.orders)
  .leftJoin(schema.customers, eq(schema.orders.customerId, schema.customers.id))
  .where(eq(schema.orders.status, 'active'))
  .orderBy(desc(schema.orders.createdAt))
  .limit(50)
  .offset(0)

`db.query.*.findMany()`

Relational queries with eager loading. Similar to Prisma's include.

const orders = await db.query.orders.findMany({
  with: { customer: true },
  where: eq(schema.orders.status, 'active'),
  orderBy: desc(schema.orders.createdAt),
  limit: 50,
})
// { id, amount, status, customer: { id, name, email } }[]

Option	Type	Description
`with`	`object`	Relations to eager load
`where`	`SQL`	Filter condition
`orderBy`	`SQL`	Sort order
`limit`	`number`	Maximum rows
`offset`	`number`	Rows to skip
`columns`	`object`	Columns to include/exclude

`db.query.*.findFirst()`

Find a single record. Returns undefined if no match.

const order = await db.query.orders.findFirst({
  where: eq(schema.orders.id, 'ord_abc123'),
  with: { customer: true },
})
// { id, amount, status, customer: { ... } } | undefined

`db.insert()`

Insert one or more rows.

// Single row
const [order] = await db.insert(schema.orders).values({
  amount: 250,
  status: 'pending',
  customerId: 'cust_abc123',
}).returning()

// Multiple rows
await db.insert(schema.orders).values([
  { amount: 100, status: 'pending', customerId: 'cust_1' },
  { amount: 200, status: 'pending', customerId: 'cust_2' },
])

// Upsert
await db.insert(schema.customers)
  .values({ id: 'cust_1', name: 'Acme', email: 'a@acme.com' })
  .onConflictDoNothing()

Chainable methods:

Method	Description
`.values(data)`	Row data to insert
`.returning()`	Return inserted rows
`.onConflictDoNothing()`	Skip on conflict
`.onConflictDoUpdate({ target, set })`	Update on conflict

`db.update()`

Update rows matching a condition.

const [updated] = await db.update(schema.orders)
  .set({ status: 'shipped' })
  .where(eq(schema.orders.id, 'ord_abc123'))
  .returning()

Chainable methods:

Method	Description
`.set(data)`	New values to set
`.where(condition)`	Filter condition
`.returning()`	Return updated rows

`db.delete()`

Delete rows matching a condition.

await db.delete(schema.orders)
  .where(eq(schema.orders.id, 'ord_abc123'))

Chainable methods:

Method	Description
`.where(condition)`	Filter condition
`.returning()`	Return deleted rows

Aggregations

Use Drizzle's aggregation functions with db.select().

import { count, sum, avg, min, max } from 'drizzle-orm'

// Count
const [{ total }] = await db.select({ total: count() }).from(schema.orders)

// Sum with filter
const [{ revenue }] = await db.select({
  revenue: sum(schema.orders.amount),
}).from(schema.orders)
  .where(eq(schema.orders.status, 'active'))

// Group by
const byStatus = await db.select({
  status: schema.orders.status,
  count: count(),
  total: sum(schema.orders.amount),
}).from(schema.orders)
  .groupBy(schema.orders.status)

Error Handling

All methods throw on server errors. Catch errors to handle permission denials, validation failures, and network issues.

try {
  await db.insert(schema.orders).values({
    amount: -100,
    status: 'invalid',
  })
} catch (error) {
  // error.message: "You do not have permission to perform this action."
}

Permission Notes

Permission filters are applied transparently on all queries
Column restrictions are enforced — selecting restricted columns returns an error
Server-side presets (like createdBy, organizationId) are injected automatically on inserts
The count and aggregation results reflect only rows the user is permitted to see

On this page