Turbine

Turbine + BataDB

From zero to typed queries on BataDB, a serverless platform that speaks the Postgres wire protocol, with branching and scale-to-zero. The same typed queries run over a TCP pool on Node.js and over SQL-over-HTTP on the edge.

1. Install#

npm install turbine-orm            # the ORM, one runtime dependency (pg)
npm install @batadata/serverless   # only for the edge / HTTP transport

2. Generate your client#

Point Turbine at your direct BataDB endpoint. Get the connection string from bata create … --json, the dashboard's Connect panel, or bata db url:

DATABASE_URL="postgresql://cloud_admin:…@cp-XXXX.us-east-1.db.batadata.com:5432/postgres?sslmode=require" \
  npx turbine generate

This writes a typed client to ./generated/turbine/. It reads the catalog over TCP, so the branch's compute must be running. bata generate wraps the same command. Re-run it, or use --watch, when your schema changes.

3. Connect from Node.js#

On a long-running server or worker, Turbine owns the pool and every feature is available, including transactions, streaming, LISTEN / NOTIFY, pgvector and RLS.

import { turbine } from './generated/turbine/index.js';
 
const db = turbine({
  connectionString: process.env.DATABASE_URL,
});
 
const authors = await db.authors.findMany({
  where: { active: true },
  with: { posts: { orderBy: { views: 'desc' }, limit: 5 } }, // one query, no N+1
  limit: 20,
});

4. Connect from the edge#

On Vercel Edge, Cloudflare Workers, Deno Deploy or any serverless runtime, use SQL-over-HTTP through @batadata/serverless. Its Pool (version 0.3.0+) is a PgCompatPool, so turbineHttp binds it directly:

import { Pool } from '@batadata/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({
  apiKey: process.env.BATA_API_KEY,      // bata_…, routes and authorizes the request
  projectId: process.env.BATA_PROJECT_ID,
  branchId: process.env.BATA_BRANCH_ID,  // optional, defaults to the primary branch
});
 
const db = turbineHttp<TurbineClient>(pool, SCHEMA);
 
const authors = await db.authors.findMany({
  where: { name: 'Ada Lovelace' },
  with: { posts: true },
});

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

5. Query telemetry#

@batadata/serverless 0.7.0+ forwards Turbine's query events to your BataDB project, for either client above:

import { batadbTelemetry } from '@batadata/serverless';
 
const telemetry = batadbTelemetry(db); // reads BATA_API_KEY, BATA_PROJECT_ID, BATA_BRANCH_ID
// on shutdown (or at the end of a serverless invocation): await telemetry.stop() / telemetry.flush()

It sends parameterized SQL shapes and per-minute p50 / p95 / p99 latency per model and action, never parameter values. It runs on a background timer that never throws into your app. Wrap a code path in db.$tag('checkout', fn) to group its queries under that tag.

6. Migrations#

Migrations are plain SQL files:

npx turbine migrate create add_authors_table
DATABASE_URL="…" npx turbine migrate up
npx turbine migrate status

Endpoints and SSL#

  • …db.batadata.com is the direct endpoint. Use it for turbine generate, migrations and Node.js servers.
  • …-pooler.db.batadata.com is the pooled endpoint (PgBouncer). Use it for many short-lived connections that do not use the HTTP driver.
  • Always use TLS. sslmode=require is the minimum; sslmode=verify-full with a CA is the strongest. Recent pg versions warn that require will mean verify-full in a future major; uselibpqcompat=true&sslmode=require keeps libpq's meaning.

Limits over HTTP#

SQL-over-HTTP is stateless, one transaction per request. Features that need a held connection throw a typed error instead of running non-atomically:

FeatureEdge / HTTP (turbineHttp)Direct (turbine({ connectionString }))
findMany / findUnique / nested with✓✓
Single-statement create / update / delete / upsert✓✓
aggregate / groupBy✓✓
$transaction / db.transaction()✗✓
Streaming (findManyStream)✗✓
$listen / $notify✗✓

Run transactions, streaming and realtime on a server or worker over the direct connection. Serve reads and single-statement writes from the edge.

Why Turbine on BataDB?#

  • 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. A cold compute pays its wake-up cost once per request, not once per query.
  • No adapter layer: turbineHttp(pool, SCHEMA) works with any pg-compatible driver.
  • SQL-first migrations: no shadow database and no proprietary schema language.

Branching is a BataDB feature: Turbine runs the same code against whichever branch your connection string names.

Next steps#