Turbine

Turbine + Neon

From zero to typed queries on Neon, with the same API on Node.js and the edge.

1. Install#

npm install turbine-orm @neondatabase/serverless

2. Generate your client#

Point Turbine at your Neon database:

DATABASE_URL="postgresql://..." npx turbine generate

This reads your schema and writes a typed client to ./generated/turbine/.

3. Connect (Node.js / long-running server)#

For a long-running Node.js process, such as an Express or Fastify server:

import { turbine } from './generated/turbine/index.js';
 
const db = turbine({
  connectionString: process.env.DATABASE_URL,
});
 
const users = await db.users.findMany({
  with: { posts: true },
});

4. Connect (Serverless / Edge)#

For Vercel Edge, Cloudflare Workers, Deno Deploy or any serverless runtime, pass Neon's Pool to turbineHttp:

import { Pool } from '@neondatabase/serverless';
import { turbineHttp } from 'turbine-orm/serverless';
import type { TurbineClient } from './generated/turbine/index.js';
import { SCHEMA } from './generated/turbine/metadata.js';
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db = turbineHttp<TurbineClient>(pool, SCHEMA);
 
// Same API, works on Vercel Edge, Cloudflare Workers, etc.
const users = await db.users.findMany({
  with: { posts: true },
});

The <TurbineClient> type argument gives you the typed accessors, such as db.users.

5. Migrations#

Migrations are plain .sql files. migrate up refuses a pooled (-pooler) connection string, so use Neon's direct one.

# Create a migration
npx turbine migrate create add_users_table
 
# Apply migrations
DATABASE_URL="..." npx turbine migrate up
 
# Check status
npx turbine migrate status

Why Turbine on Neon?#

  • No WASM: the edge entry is held under 120 kB brotli in CI.
  • Single-query nested reads: one SQL statement via json_agg, not N+1.
  • Pipeline batching: several queries in one round trip, which matters most on high-latency serverless links.
  • No adapter layer: turbineHttp(pool, SCHEMA) with any pg-compatible driver.
  • SQL-first migrations: no shadow database, no proprietary schema DSL.

Next steps#