Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
turbine
✓ import { turbine } from 'turbine-orm'
✗ const turbine = require('turbine-orm')
ESM-only since v0.15.0. CommonJS require will fail. Use dynamic import() if needed.
turbineHttp
✓ import { turbineHttp } from 'turbine-orm/serverless'
✗ import { turbineHttp } from 'turbine-orm'
Serverless/edge adapter is in a separate export path. Importing from main package gives the standard pool-based client.
SchemaBuilder
✓ import { SchemaBuilder } from 'turbine-orm/schema'
✗ import { SchemaBuilder } from 'turbine-orm'
Schema builder is not exported from the main entry. Must use the /schema subpath import.
UniqueConstraintError
✓ import { UniqueConstraintError } from 'turbine-orm/errors'
✗ import { UniqueConstraintError } from 'turbine-orm'
Typed errors are in a separate export path for tree-shaking.
Shows how to define a schema with two tables (users and posts), create a Turbine ORM instance, and run a single-query nested read using findUnique with include.
import { turbine } from 'turbine-orm';
import pg from 'pg';
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL ?? 'postgres://localhost:5432/mydb'
});
const db = turbine(pool, (schema) => ({
user: schema.table('users', (t) => ({
id: t.serial().primary(),
name: t.text().notNull(),
email: t.text().unique(),
})),
post: schema.table('posts', (t) => ({
id: t.serial().primary(),
title: t.text().notNull(),
authorId: t.integer().references('user', 'id'),
})),
}));
async function main() {
const user = await db.findUnique('user', {
where: { email: 'alice@example.com' },
include: { posts: true }
});
console.log(user);
await db.$disconnect();
}
main().catch(console.error);
Debug
Known issues
breakingESM-only since v0.15.0 – require() will throw ERR_REQUIRE_ESMfixSwitch to ES module imports (import/export) or use dynamic import('turbine-orm') in CommonJS files. affects: >=0.15.0
breakingServerless adapter moved to /serverless subpath in v0.14.0fixChange 'turbine-orm' imports for turbineHttp to 'turbine-orm/serverless'
affects: >=0.14.0
deprecatedSchemaBuilder class was renamed to Schema in v0.13.0 – SchemaBuilder still exported but deprecatedfixReplace 'SchemaBuilder' with 'Schema' in imports and usage.
affects: >=0.13.0 <0.16.0
gotchaPipeline queries do NOT run in a transaction – each query is individually auto-committedfixWrap pipeline calls in BEGIN/COMMIT manually if atomicity is required. Use db.$transaction() instead.
affects: all
gotchaStudio is read-only by default but can be started with --write flag for development – never use in productionfixRun 'npx turbine studio' without flags for read-only. For write access, add --write but restrict to localhost.
affects: all
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module /node_modules/turbine-orm/index.js from ... not supported
Turbine ORM v0.15+ is ESM-only, but project uses CommonJS require()
fixUse import statement instead of require(), or set type: 'module' in package.json, or use dynamic import()
Error: Cannot find module 'turbine-orm/errors'
Missing /errors export path – installed version may be <0.12.0 or project uses bundler without subpath exports
fixUpgrade to >=0.12.0 and ensure bundler supports Node.js subpath exports (most modern bundlers do)
TypeError: pool.query is not a function
Passed a pg.Client or pg.Pool instance with incorrect export – turbine() expects a pool object with .query() method
fixUse new pg.Pool() not new pg.Client(). Ensure you import pg correctly and initialize pool properly.
Error: relation 'users' does not exist
Table name mismatch between schema definition and actual database table (case sensitivity or pluralization)
fixEnsure schema.table() names match exact PostgreSQL table names. Use double quotes if mixed case: schema.table('"Users"', ...) Audit
Dependencies
pgrequiredPostgreSQL client - only runtime dependency
@types/pgoptionalTypeScript type definitions for pg - required when using TypeScript