Schema

Turbine gets its schema one of two ways: you declare tables in TypeScript with defineSchema(), or it introspects an existing database. Either way, turbine generate writes the same typed client, so you can mix the two.

Define tables with defineSchema#

// turbine/schema.ts
import { defineSchema } from 'turbine-orm';
 
export default defineSchema({
  organizations: {
    id: { type: 'serial', primaryKey: true },
    name: { type: 'text', notNull: true },
  },
  users: {
    id: { type: 'serial', primaryKey: true },
    email: { type: 'text', unique: true, notNull: true },
    orgId: { type: 'integer', notNull: true, references: 'organizations.id' },
    role: { type: 'text', notNull: true, default: "'member'" },
    createdAt: { type: 'timestamptz', notNull: true, default: 'now()' },
  },
});

Table and field keys are camelCase; Turbine writes snake_case names to the database (orgId becomes org_id). Relations are not declared: they come from foreign keys. Apply the schema with npx turbine push in development, or with migrations.

Column types#

There is no code-first spelling for a zone-less TIMESTAMP column. Create one in a SQL migration and generate picks it up. A bigint or bigserial value above Number.MAX_SAFE_INTEGER reads as a string.

Column options#

Table options#

memberships: {
  userId: { type: 'integer', notNull: true, references: 'users.id' },
  orgId: { type: 'integer', notNull: true, references: 'organizations.id' },
  role: { type: 'text', notNull: true },
  primaryKey: ['userId', 'orgId'],
  indexes: [{ columns: ['orgId', 'role'] }],
  checks: [{ name: 'valid_role', expression: "role IN ('member', 'admin')" }],
},

findUnique takes a composite key as an object: where: { userId: 1, orgId: 2 }. Every foreign-key column gets an index automatically. A declared index with the same name replaces it.

Foreign keys#

posts: {
  id: { type: 'serial', primaryKey: true },
  userId: {
    type: 'integer',
    notNull: true,
    references: { target: 'users.id', onDelete: 'cascade' },
  },
},
// "user_id" INTEGER NOT NULL REFERENCES "users"("id") ON DELETE CASCADE

onDelete and onUpdate take 'cascade', 'restrict', 'set null', 'set default' or 'no action'.

A reference to a table in the same schema must name a column that exists, or defineSchema throws ValidationError (E003). A table outside the schema is not checked.

Enums#

export default defineSchema(
  {
    posts: {
      id: { type: 'serial', primaryKey: true },
      status: { type: 'enum', enumName: 'post_status', notNull: true, default: "'draft'" },
    },
  },
  { enums: { post_status: ['draft', 'published', 'archived'] } },
);

On PostgreSQL this emits CREATE TYPE "post_status" AS ENUM (...) before the tables that use it. MySQL gets an inline ENUM(...), and SQLite and SQL Server get a text column with a CHECK over the labels.

Unknown keys throw#

A key defineSchema does not know throws ValidationError (E003) with the nearest valid key, and is a compile error in an object literal:

role: { type: 'text', defaultValue: "'member'" },
// defineSchema: unknown key "defaultValue" in column "users.role". Did you mean "default"?

The same error covers an index naming an unknown column, a table or column named __proto__, and two fields that map to one database column.

Column tags#

pii, updatedAt and tsType change how the client behaves, not the table. The database has nowhere to store them, so turbine generate reads them from your schema file.

PII fields#

users: {
  id: { type: 'serial', primaryKey: true },
  email: { type: 'text', notNull: true, pii: true },
},

A PII column is left out of every default read, including nested with rows and the row a write returns.

To read it, pass includePii: UNSAFE, a privilege option. Naming the column in select without it throws ValidationError (E003).

• Writes accept PII values as usual.
• where, orderBy and having on a PII column are always allowed.
• groupBy by a PII column, and _min / _max over one, need includePii: UNSAFE. _count, _sum and _avg do not.
• A PII column that is part of the primary key is always returned. Tag sensitive data, not keys.
• Studio and the MCP server redact PII cells, using the tags in your generated metadata.

The generated entity type marks each PII field optional.

Auto-updated timestamps, updatedAt#

posts: {
  id: { type: 'serial', primaryKey: true },
  title: { type: 'text', notNull: true },
  updatedAt: { type: 'timestamptz', notNull: true, default: 'now()', updatedAt: true },
},

Every update, updateMany and the update half of an upsert sets the column to the current time, unless the payload names it. It is Prisma's @updatedAt. Inserts are not stamped, so give the column a default.

Typing a JSON column, tsType#

settings: { type: 'jsonb', tsType: '{ theme: string; beta?: boolean }' },

A json or jsonb column generates as unknown. tsType replaces that in the generated types, adding | null for a nullable column.

The text must be one type on one line. It can reference your own types with import('../src/types.js').Settings.

tsType changes only the generated TypeScript, not how values are read or written. The same override can live in turbine.config.ts as columnTypes, which wins when both name a column.

How generate picks up the tags#

turbine generate introspects the database, then overlays pii, updatedAt, maxLength and tsType from your schema file (schemaFile in turbine.config.ts, default turbine/schema.ts). It prints a line such as Applied column tags from turbine/schema.ts: 2 pii, 1 updatedAt.

If the schema file cannot be loaded, or a pii or updatedAt tag names a table or column the database lacks, generate fails rather than emit an unprotected client. A project with no file at the default path skips the overlay.

Introspection#

npx turbine generate   # alias: turbine pull

generate reads tables, columns, keys, indexes, enums and STORED generated columns, and derives relations from foreign keys (hasMany, belongsTo, hasOne, and many-to-many through junction tables). Pass --include-views for views. It writes three files to ./generated/turbine/:

• types.ts: entity interfaces plus *Create and *Update input types.
• metadata.ts: the runtime SCHEMA metadata.
• index.ts: the typed TurbineClient subclass and the turbine() factory.

When a derived relation name would collide with a column, the relation gets a different name. To choose names yourself, use relationNames.

Runtime metadata without a database, schemaDefToMetadata#

schemaDefToMetadata() builds the client metadata from a defineSchema result, with no connection and no codegen. Use it for tests, in-memory SQLite and PowDB:

import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
import { turbinePowDB } from 'turbine-orm/powdb';
 
const schema = defineSchema({ /* ... */ });
const db = await turbinePowDB({ embedded: './data' }, schemaDefToMetadata(schema));

Apply schema changes#

The diff creates tables and adds or changes columns, indexes and constraints.

A column missing from the schema produces a DROP COLUMN, which push and migrate up refuse until you confirm. A table missing from the schema is listed but never dropped.

The same steps are available from code:

import { schemaDiff, schemaPush, schemaToSQL } from 'turbine-orm';
import schema from './turbine/schema.js';
 
const ddl = schemaToSQL(schema);                       // string[], no connection
const diff = await schemaDiff(schema, process.env.DATABASE_URL!);
console.log(diff.statements, diff.warnings);
 
await schemaPush(schema, process.env.DATABASE_URL!);   // one transaction

Type mapping#

How generate types introspected Postgres columns:

Zone-less columns: timestamp and date read as UTC#

A timestamp (without time zone) or date value has no offset, so Turbine reads it as UTC rather than in the process's local zone. A stored date '2026-07-21' reads as 2026-07-21T00:00:00.000Z wherever the process runs.

Writes match: a Date bound to a zone-less column is written with its UTC components. SQLite, MySQL and SQL Server bind a Date for a date column as its UTC day.

To read and write in local time instead, pass utcTimestamps: false. The setting is process-wide:

• The first client in the process settles it. A later client asking for the opposite throws ValidationError (E003).
• A client that opens its own pool installs the parsers on the pg module, so other code using pg in the process reads UTC too.
• A client on a pool you supply applies the parsers to its own queries only, but takes part in the same check.

infinity and -infinity#

PostgreSQL stores infinity and -infinity in date, timestamp and timestamptz columns. No Date can hold them, so Turbine reads them as the numbers Infinity and -Infinity on every read path.

• row.validUntil.toISOString() throws a TypeError on those rows. Check typeof value === 'number' first.
• JSON.stringify renders them as null.
• where: { validUntil: null } does not match them. Use where: { validUntil: 'infinity' }.
• The first read of a stored infinity logs a one-time warning (code temporal-infinity), even in production. Setting temporalInfinity explicitly silences it.

Writing the number back stores infinity again, so a read-modify-write round-trips.

Time-of-day columns: time and timetz#

A time or timetz column reads as the driver's string, '09:00:00'. Writes also take a Date, narrowed to its UTC time of day (Prisma's convention for @db.Time):

await db.shifts.create({ data: { startsAt: '09:00:00' } });
await db.shifts.create({ data: { startsAt: new Date('1970-01-01T09:00:00Z') } });

The same narrowing applies in where and in a groupBy having on the column. In an aggregate filter such as having: { startsAt: { _min: { gte } } }, pass a string instead: a Date there fails with 22007.

See also#

• Migrations: the production migration workflow.
• CLI: generate, push and every flag.
• Reading and writing: querying the tables you defined.