Turbine

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#

  1. Install Turbine and generate a client from your existing database:

    npm install turbine-orm
    npx turbine generate
  2. 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 });
  3. Convert queries with the API mapping below. Operators become object keys, so the eq, gt and like imports go away.

  4. Run npx turbine doctor and add the foreign-key indexes it reports. Nested reads probe the child table once per parent row, so an unindexed foreign key gets expensive.

  5. Audit the behavior differences.

  6. Once nothing imports Drizzle, uninstall drizzle-orm and drizzle-kit. Keep drizzle/ until your migrations take over.

API mapping#

DrizzleTurbine
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 where on a write throws. update, updateMany, delete and deleteMany with an empty where throw ValidationError (E003) unless you pass allowFullTableScan: UNSAFE.
  • Zone-less timestamp and date columns read as UTC, whatever the process's time zone. See Zone-less columns.
  • numeric reads as a string, int8 as a number, or a string above Number.MAX_SAFE_INTEGER.
  • Relation arrays have no guaranteed order. Add orderBy inside with when order matters.
  • Errors are typed. Constraint violations throw classes such as UniqueConstraintError (E008). They extend Error, so existing handlers still catch them.

What you give up#

  • SQL-shaped queries. There is no select().from().join() chain. Use db.sql for 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. Rerun npx turbine generate after each schema change.

See also#