Turbine

Views & Generated Columns

Turbine generates read-only accessors for database views, and treats STORED generated columns as readable but never writable. Both rules hold in the generated types and again at runtime.

Views#

Pass --include-views to introspect views and materialized views along with tables:

npx turbine generate --include-views

Each view gets an entity type and the read methods (findMany, findFirst, count, aggregate and the rest):

// active_users is a Postgres view
const active = await db.activeUsers.findMany({
  where: { orgId: 1 },
  orderBy: { name: 'asc' },
});

SQLite views#

For a project configured with engine: 'sqlite', turbine generate --include-views and turbine pull --include-views discover ordinary views in the main database. Views are excluded by default; the existing include/exclude filters apply. The CLI opens the existing database read-only. Temporary and attached views are excluded, and this does not manage view DDL or materialized views.

SQLite views have no inferred primary or unique keys, so generated accessors omit findUnique and findUniqueOrThrow. Write methods remain in the generated types and reject with E003 at runtime, including views with INSTEAD OF triggers. JSON view columns retain decoding when the base table is filtered out. Computed columns keep the unknown types SQLite reports.

Library callers can pass { includeViews: true } to introspectSqliteDatabase(handle, options) or introspectBetterSqlite3Database(handle, options). Both accept the same filters and preserve the caller-owned handle. The better-sqlite3 client uses the same read-only view metadata and E003 write refusals.

Views are read-only#

Every write method on a view throws ValidationError (E003) before any SQL runs, on every SQL engine:

await db.activeUsers.create({ data: { name: 'x' } });
// ValidationError: Cannot create "active_users": it is a view (read-only).

Views without a primary key#

A view with no primary key cannot address one row, so its accessor has no findUnique or findUniqueOrThrow. Calling either is a compile error. A view that exposes a primary key keeps the full read API.

STORED generated columns#

Postgres computes a GENERATED ALWAYS AS (...) STORED column from other columns:

CREATE TABLE invoices (
  id    bigserial PRIMARY KEY,
  qty   integer NOT NULL,
  price integer NOT NULL,
  total integer GENERATED ALWAYS AS (qty * price) STORED
);

total is in the Invoice entity type and comes back on every read. It is left out of InvoiceCreate and InvoiceUpdate, so writing it is a compile error. Untyped data that reaches create, update or upsert with the column throws ValidationError (E003):

await db.invoices.create({ data: { qty: 2, price: 3 } });           // total = 6
await db.invoices.create({ data: { qty: 2, price: 3, total: 6 } }); // ValidationError

See also#

  • Schema: introspection and type mapping.
  • Zod Schemas: generated columns are left out of the create and update schemas too.