Methods Reference

This page lists the practical method surface you use day-to-day in KadakORM.

1) connect()

connect(url: string): Database
connect(config: ConnectionConfig): Database
connect(config: string | ConnectionConfig, tables: Record<string, Table>): Database

What it does

• Creates a database client.
• Exposes every registered table as db.<tableName>.
• Keeps raw SQL access via db.sql.

Common options

• url
• readReplicas
• debug
• warnings (relaxed | strict | silent)
• defaultLimit
• retryAttempts
• validateResults
• explainAnalyze
• selectCacheTtlMs

2) Database-level methods

db.transaction()

db.transaction(async (tx) => {
  // use tx inside this callback
})

• Runs all statements in one transaction.
• Rolls back if any statement throws.

db.close()

await db.close()

• Closes main and replica connections.
• Useful in scripts, workers, and tests.

db.sql

await db.sql`SELECT now()`

• Escape hatch for raw SQL.
• Use when you need full SQL control.

3) Table client methods (db.users.*)

findMany(query?)

await db.users.findMany({
  isActive: true,
  $or: [{ role: 'admin' }, { role: 'owner' }],
  $order: { createdAt: 'desc' },
  $limit: 50,
})

• Top-level object is the filter.
• Special keys: $limit, $order, $or.

findFirst(query?)

const user = await db.users.findFirst({ email: 'riya@example.com' })

• Same filter format as findMany.
• Returns first row or null.

insert(data)

await db.users.insert({ email: 'a@example.com', name: 'A' })
await db.users.insert([{ email: 'a@example.com' }, { email: 'b@example.com' }])

• Accepts single object or array.
• Runs schema validation and default automation.

update(filter, patch)

await db.users.update({ id: 1 }, { name: 'Riya' })

• filter: which rows.
• patch: changed fields only.
• Empty patches are rejected.

delete(filter)

await db.users.delete({ id: 1 })

• Soft-deletes if table has soft delete enabled.
• Falls back to hard delete if not.

hardDelete(filter)

await db.users.hardDelete({ id: 1 })

• Physical row removal.
• Use only for explicit purge flows.

4) Table definition + validators

table(name, columns, options?)

const users = table('users', {
  id: 'id',
  email: 'email',
  name: 'text',
  age: 'int?',
}, {
  timestamps: true,
  softDelete: true,
})

Validator methods

users.insertValidator()
users.updateValidator()
users.selectValidator()

• insertValidator(): API create payload contract.
• updateValidator(): API patch payload contract.
• selectValidator(): read row contract.

5) Column builder methods (kadak.*)

Use for advanced control:

const users = table('users', {
  email: kadak.email().unique(),
  age: kadak.number().min(13).max(100),
  createdAt: kadak.timestamp().default('now'),
})

Common chainable methods:

• .optional()
• .default(value)
• .defaultSql(sql)
• .unique()
• .index()
• .primary()
• .references('table.column')
• .min(), .max(), .regex(), .email(), .url()

6) Operators in filters

await db.users.findMany({
  age: { $gt: 18, $lte: 65 },
  email: { $in: ['a@example.com', 'b@example.com'] },
})

Supported operators:

• $gt, $gte, $lt, $lte
• $in

null values are also supported directly:

await db.users.findMany({ deletedAt: null })

For basic queries, keep the simple path:

await db.users.findMany({ isActive: true, $limit: 50 })