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 transport2. 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 generateThis 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 statusEndpoints and SSL#
…db.batadata.comis the direct endpoint. Use it forturbine generate, migrations and Node.js servers.…-pooler.db.batadata.comis the pooled endpoint (PgBouncer). Use it for many short-lived connections that do not use the HTTP driver.- Always use TLS.
sslmode=requireis the minimum;sslmode=verify-fullwith a CA is the strongest. Recentpgversions warn thatrequirewill meanverify-fullin a future major;uselibpqcompat=true&sslmode=requirekeeps 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:
| Feature | Edge / 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#
- Serverless & Edge: the full
turbineHttpguide and thePgCompatPoolcontract. - Migrate from Drizzle or from Prisma: your connection string and
turbine generateare the only BataDB-specific pieces. - Transactions & Pipelines: pipelines save the most round trips on the edge.
- Typed Errors: the errors you get when you reach for a session-only feature over HTTP.