Migrating from Drizzle
Turbine replaces Drizzle's SQL-builder calls with a Prisma-style object API, and generates its types from the database instead of from pgTable() declarations. Both can load a nested with tree in one SQL statement.
Steps#
-
Install Turbine and generate a client from your existing database:
npm install turbine-orm npx turbine generate -
Create the client in place of
drizzle():// Before import { drizzle } from 'drizzle-orm/node-postgres'; const db = drizzle(pool); // After import { turbine } from './generated/turbine/index.js'; const db = turbine({ connectionString: process.env.DATABASE_URL }); -
Convert queries with the API mapping below. Operators become object keys, so the
eq,gtandlikeimports go away. -
Run
npx turbine doctorand add the foreign-key indexes it reports. Nested reads probe the child table once per parent row, so an unindexed foreign key gets expensive. -
Audit the behavior differences.
-
Once nothing imports Drizzle, uninstall
drizzle-ormanddrizzle-kit. Keepdrizzle/until your migrations take over.
API mapping#
| Drizzle | Turbine |
|---|---|
db.select().from(users) | db.users.findMany() |
db.select().from(users).where(eq(users.id, 1)) | db.users.findUnique({ where: { id: 1 } }) |
.limit(10).offset(20) | findMany({ limit: 10, offset: 20 }) |
db.query.users.findMany({ with: { posts: true } }) | db.users.findMany({ with: { posts: true } }) |
db.insert(users).values({ ... }) | db.users.create({ data: { ... } }), returns the row |
db.insert(users).values([...]).onConflictDoNothing() | db.users.createMany({ data: [...], skipDuplicates: true }) |
.onConflictDoUpdate({ target, set }) | db.users.upsert({ where, create, update }) |
db.update(users).set({ ... }).where(...) | db.users.update({ where: { ... }, data: { ... } }) |
db.delete(users).where(...) | db.users.delete({ where: { ... } }), returns the row |
db.transaction(async (tx) => ...) | db.$transaction(async (tx) => ...) |
sql`SELECT ...` | db.raw`SELECT ...` , or db.sql<Row>`...` for typed rows |
Filters and updates#
// Drizzle
await db.select().from(users).where(and(gt(users.age, 18), like(users.name, '%smith%')));
await db.update(posts).set({ viewCount: sql`${posts.viewCount} + 1` }).where(eq(posts.id, 42));// Turbine
await db.users.findMany({ where: { age: { gt: 18 }, name: { contains: 'smith' } } });
await db.posts.update({ where: { id: 42 }, data: { viewCount: { increment: 1 } } });Nested reads#
// Drizzle
const users = await db.query.users.findMany({
where: (users, { eq }) => eq(users.orgId, 1),
with: { posts: { limit: 5, orderBy: (posts, { desc }) => [desc(posts.createdAt)] } },
});// Turbine
const users = await db.users.findMany({
where: { orgId: 1 },
with: { posts: { orderBy: { createdAt: 'desc' }, limit: 5 } },
});Relations come from foreign keys, so there is no relations() declaration to port.
Schema translation#
On an existing database, turbine generate reads the schema, so you do not need to translate anything. For a code-first schema, pgTable() becomes a defineSchema() table:
// Drizzle
export const posts = pgTable('posts', {
id: serial('id').primaryKey(),
userId: integer('user_id').notNull().references(() => users.id),
title: text('title').notNull(),
published: boolean('published').notNull().default(false),
});// Turbine
import { defineSchema } from 'turbine-orm';
export default defineSchema({
posts: {
id: { type: 'serial', primaryKey: true },
userId: { type: 'integer', notNull: true, references: 'users.id' },
title: { type: 'text', notNull: true },
published: { type: 'boolean', notNull: true, default: false },
},
});Field names are camelCase and become snake_case columns. Turbine's type: 'timestamp' creates TIMESTAMPTZ, while Drizzle's timestamp() is zone-less, so introspect an existing database rather than retyping those columns.
Behavior differences to audit#
- Empty
whereon a write throws.update,updateMany,deleteanddeleteManywith an emptywherethrowValidationError(E003) unless you passallowFullTableScan: UNSAFE. - Zone-less
timestampanddatecolumns read as UTC, whatever the process's time zone. See Zone-less columns. numericreads as astring,int8as anumber, or astringaboveNumber.MAX_SAFE_INTEGER.- Relation arrays have no guaranteed order. Add
orderByinsidewithwhen order matters. - Errors are typed. Constraint violations throw classes such as
UniqueConstraintError(E008). They extendError, so existing handlers still catch them.
What you give up#
- SQL-shaped queries. There is no
select().from().join()chain. Usedb.sqlfor queries the object API does not express. - Equal footing across databases. Turbine is PostgreSQL-first. SQLite, MySQL, SQL Server and PowDB share the query API, but some features are PostgreSQL-only and the schema CLI targets PostgreSQL. See What is actually Postgres-only.
- Types inferred from the schema file. There is no
$inferSelect. Rerunnpx turbine generateafter each schema change.
See also#
- Quick Start: set up a project from scratch.
- Reading and writing and Filtering and sorting: every query method, operator and option.
- Relations: nested reads and relation filters.
- Migrations: the production migration workflow.