Client API

What the client does around every query: timeouts, middleware, query plans, and the options it is created with.

Per-query timeout#

Every method takes timeout in milliseconds, or 0 for none.

import { TimeoutError } from 'turbine-orm';
 
try {
  await db.orders.update({ where: { id }, data: { status: 'shipped' }, timeout: 2_000 });
} catch (err) {
  if (err instanceof TimeoutError && err.outcome === 'not-executed') {
    // Nothing changed: safe to retry.
  }
}

A TimeoutError (E002) carries outcome. 'not-executed' means nothing changed, for example when the PostgreSQL server confirms Turbine's cancel. 'unknown' means a write may have applied, which is the answer on other engines; check before retrying.

Inside $transaction on PostgreSQL, a timed-out statement rolls the transaction back, and $transaction rejects with TransactionRolledBackError (E019) even if you catch the timeout.

Middleware#

db.$use(async (params, next) => {
  const start = Date.now();
  const result = await next(params);
  console.log(`${params.model}.${params.action} took ${Date.now() - start}ms`);
  return result;
});

Middleware can read params, time the call and transform the result. It cannot change the query: editing params.args makes next() throw a TypeError. Put tenant and soft-delete filters in a global filter.

explain#

const plan = await db.posts.explain({ where: { orgId: 7 }, orderBy: { createdAt: 'desc' } });
// ['Sort  (cost=…)', '  ->  Index Scan using posts_org_id_idx on posts …', …]

Returns the plan for the statement findMany(args) would run, as lines. SQLite uses EXPLAIN QUERY PLAN, PowDB its own explain, and SQL Server throws E017. Match node names, not layout.

Client configuration#

turbine() and new TurbineClient() take a TurbineConfig. Quick Start and Serverless cover the connection fields.

const db = turbine({ connectionString: process.env.DATABASE_URL, poolSize: 20 });

• max, idleTimeoutMillis and connectionTimeoutMillis work as aliases.
• An unknown key logs unknown-config-key with the nearest option, and never throws.
• Behind a transaction pooler Turbine does not recognize, set preparedStatements: false, or queries fail with prepared statement "..." does not exist.
• Each connection keeps every named statement it parses. Build select, omit and with from user input only through a fixed allowlist.

Client escape hatches#

const audit = db.table<{ id: number; action: string; at: Date }>('audit_log');
const recent = await audit.findMany({ orderBy: { at: 'desc' }, limit: 20 });

See also#

• Transactions: $transaction and pipeline.
• Observability: logging, events and metrics.
• Serverless and edge: supplying your own pool.