Database (ctx.db)

Records

A record comes back with your fields at the top level, plus system fields that start with $:

Filters

find and deleteWhere take filters as an object of field names and values. They are deliberately simple:

• Exact matches only. Every key must equal its value, and all keys must match. There are no operators: no greater-than, no "in", no contains.
• Compared as text. { qty: 5 } matches a stored 5, and { active: true } matches true. You can't match null or a nested object.
• Top-level fields only. Names may contain letters, digits and underscores. A name like address.city is rejected with an error, never silently ignored.
• created_by is special. It matches the record's creator, not a field in your data.

find

const { records, total } = await ctx.db.find('orders', { status: 'open' }, 50)
// records: up to 50 open orders, oldest first
// total:   how many open orders exist in all

An optional fourth argument pages and sorts:

const page2 = await ctx.db.find('orders', { status: 'open' }, 50, {
  offset: 50,
  orderBy: 'created_at',
  orderDesc: true,
})

update

update merges: the fields you pass are set, and every other field keeps its value. It finds the record by $id alone. Because ctx.db bypasses access rules, confirm the record belongs to the user before changing it:

export async function handler(ctx) {
  const userId = ctx.auth.user_id
  if (!userId) return { error: 'sign in required' }

  const orderNo = ctx.request.body.order_no
  const { records } = await ctx.db.find('orders', { order_no: orderNo, owner_id: userId }, 1)
  if (records.length === 0) return { error: 'order not found' }

  const order = await ctx.db.update(records[0].$id, { status: 'cancelled' })
  return { order }
}

To make an update conditional, pass the $revision you read as expectedRevision. If the record changed since, nothing is written and it throws with error code revision_mismatch.

const order = await ctx.db.get(orderId)
await ctx.db.update(order.$id, { status: 'shipped' }, { expectedRevision: order.$revision })

upsert

Updates the record that matches match, or creates one if nothing matches, and returns{ record, created }. If match finds more than one record, it throws with status 409 rather than guessing which one you meant.

const { record, created } = await ctx.db.upsert('counters', { name: 'orders' }, { value: 1 })

deleteWhere

Deletes every record that matches and returns { deleted: n }. Two safeguards apply: empty filters are refused, so you can't wipe a collection by accident, and append-only collections refuse bulk deletes entirely.

const { deleted } = await ctx.db.deleteWhere('sessions', { owner_id: userId })

batch

batch runs a list of writes in one transaction. If any of them fails, none of them apply. Each operation is an object with a type:

An update with expected_revision applies only if the record still has that revision. If someone changed it in the meantime, the whole batch rolls back and throws with error code revision_mismatch. Re-read the record and try again.

const { records } = await ctx.db.find('products', { sku: sku }, 1)
const product = records[0]

try {
  const { results } = await ctx.db.batch([
    {
      type: 'update',
      record_id: product.$id,
      data: { stock: product.stock - 1 },
      expected_revision: product.$revision,
    },
    { type: 'insert', collection: 'sales', data: { sku: sku, owner_id: userId } },
  ])
  return { results }
} catch (err) {
  if (err.errorCode === 'revision_mismatch') {
    return { error: 'stock changed, try again' }
  }
  throw err
}

For a single conditional write, update takes expectedRevision too.

Errors

Every method throws KoolbaseDatabaseException when the request fails: a collection or record that doesn't exist, a unique-constraint clash, a revision mismatch, and so on. In TypeScript it carries:

Dart

The same eight methods, with the same arguments. Options are maps, such as {'orderBy': 'name'}. In Dart, ctx is a map, so each method is looked up and called as a function. The access-rules warning above applies here too.

Future<Map<String, dynamic>> handler(Map<String, dynamic> ctx) async {
  final auth = ctx['auth'] as Map<String, dynamic>;
  final userId = auth['user_id'] as String?;
  if (userId == null) return {'error': 'sign in required'};

  final db = ctx['db'] as Map<String, dynamic>;
  final result = await (db['find'] as Function)('orders', {'owner_id': userId}, 50);

  return {'orders': result['records'], 'total': result['total']};
}

In test mode

When a Function runs in test mode, ctx.db writes nothing. Each method returns a simulated result marked __test: true, and find returns no records. asUser() returns the same simulated methods.