Turbine for AI agents

npx turbine skill

npx turbine init        # writes turbine.config.ts and a turbine/ directory
npx turbine generate    # introspect the live database, emit a typed client

const users = await db.users.findMany({
  where: { orgId: 1 },
  with: { posts: { with: { comments: { with: { author: true } } } } },
});
 
users[0].posts[0].comments[0].author.name; // inferred end to end, no manual casts

import { SerializationFailureError, UniqueConstraintError } from 'turbine-orm';
 
try {
  await db.orders.create({ data });
} catch (err) {
  if (err instanceof UniqueConstraintError) {
    // E008, duplicate; surface a clean conflict
  } else if (err instanceof SerializationFailureError && err.isRetryable) {
    // E013, retry the transaction; the flag is a typed const, so the compiler knows it is safe
  }
}

## Database: Turbine ORM
 
This project uses turbine-orm (Postgres-first, Prisma-like API). Reference:
https://turbineorm.dev/llms.txt and https://turbineorm.dev/llms-full.txt.
 
Client
- Import the generated client: `import { turbine } from '@/generated/turbine'`.
- `const db = turbine()` reads DATABASE_URL. Call `db.disconnect()` on shutdown.
- Never hand-write entity types; run `npx turbine generate` after any schema change
  and import types from `generated/turbine`.
 
Reads
- `db.<table>.findMany({ where, with, orderBy, limit, offset, cursor, select, omit })`.
  `take`/`skip` are accepted as aliases for `limit`/`offset`.
- Nested relations go in `with`, never Prisma's `include`, and never as N+1 loops or
  manual joins. An unrecognized option is IGNORED, so an `include` returns rows with
  the relation missing. `with` results are fully typed at any depth.
- `select` and `omit` name columns only. A relation named in `select` throws (E003);
  relations carry their own nested `select`.
- Under `relationLoadStrategy: 'join'` the whole `with` tree resolves in ONE SQL
  statement (json_agg). The default is `'auto'`, which keeps that plan but may move
  an individual relation (or `_count`) to one flat follow-up statement when the join
  would be slower, e.g. an unindexed correlation column. The returned rows are
  identical either way, so do not assert on statement counts unless the query pins
  a strategy.
- `findUnique` needs a `where` that identifies one row (PK, a unique column, or every
  column of a compound unique) and returns `T | null`; anything else throws E003.
  `findUniqueOrThrow` throws NotFoundError (E001) on a miss. Use `findFirst` for
  "any row matching a filter", with an `orderBy` if which row matters.
 
Writes
- `create`, `createMany`, `update`, `updateMany`, `delete`, `deleteMany`, `upsert`.
- For counters use atomic operators: `data: { viewCount: { increment: 1 } }`.
- `update`/`delete` with an empty `where` throws ValidationError (E003) by design.
- Relation ops inside `data` (connect/create/disconnect/set/update/upsert) run in one tx.
 
Safety
- Every value is parameterized ($1, $2, ...); never string-interpolate SQL. Use `db.raw`
  or `db.sql<T>` (both bind `${value}` as params) only when the builder can't express it.
- Wrap multi-step writes in `db.$transaction(async (tx) => { ... })`.
 
Errors
- Catch typed errors and branch on the class/code (TURBINE_E001..E020), not the message.
- Retry only when `err.isRetryable` is true (DeadlockError E012, SerializationFailureError E013).
 
Migrations
- Local iteration: edit `turbine/schema.ts` (defineSchema), then `turbine push`, then
  `turbine generate`. Production: SQL migrations via `turbine migrate` (never edit an
  applied migration file, checksums are validated).