Привет, я Сергей Маркизов, разработчик диджитал-продакшна Далее. В наших проектах часто использую Drizzle — современную, типобезопасную ORM для TypeScript, которая не усложняет базовую задачу: читать и писать данные. В этой статье расскажу, чем библиотека отличается от других и как с ней работать.

Базы данных являются основным средством обеспечения персистентности современных приложений. Для работы с ними зачастую используются различные ORM-решения, ведь они позволяют избавиться от необходимости написания большого количества шаблонного кода при работе с БД.

Но, несмотря на все свои плюсы, ORM сталкиваются с постоянной критикой из-за своих минусов.

1. Плохая производительность и неспособность использовать многие возможности конкретных баз данных.

2. Большие размеры кодовой базы этих решений, как правило, приводят к долгоживущим багам, которые не исправляются годами. 

3. Попытки сделать один инструмент для работы как с SQL, так и с NoSQL базами еще сильнее сужают полноценное использование возможностей СУБД.

Так, на проектах, где требуется построение сложных SQL-запросы, TypeORM быстро теряет все свои преимущества. Внутренние механизмы технологии дают большой оверхед и работают не всегда корректно — даже при использовании QueryBuilder. Более того, с применением этого конструктора увеличивается вероятность возникновения багов из-за отсутствия проверки типов. Особенно при запросах, результаты которых не укладываются в схему данных таблиц.

Все же не стоить хейтить все ORM, попробовав один-два инструмента. Существуют и достаточно легковесные решения для работы с БД. Один из них — Drizzle ORM.

Знакомство с Drizzle ORM и описание отличительных черт

Если вы устали от сложных ORM, которые прячут SQL за слоями абстракций, то вам стоит обратить внимание на Drizzle.

Это легковесный, типобезопасный и максимально близкий к SQL инструмент для работы с базами данных — с широкой поддержкой типизированных запросов с помощью TypeScript.

Drizzle позволяет строить SQL-запросы с проверкой типов на основе описания схемы базы данных и не имеет накладных расходов, присущих многим альтернативным инструментам для работы с БД.

Поддерживаемые БД и создание соединения с базой

На текущий момент Drizzle поддерживает следующие SQL-СУБД: PostgreSQL, MySQL, SQLite.

Для создания соединения достаточно указать URL базы данных:

const connection = drizzle(process.env.DATABASE_URL);

Но для полноценного использования возможностей типизации TypeScript следует указать схему при создании соединения:

const connection = drizzle(process.env.DATABASE_URL!, {
  casing: 'snake_case', // В случае различий в регистре
  logger: true,         // Можно передать логгер или true для использования логгера по умолчанию
  schema: {
    ...schema,
    ...relations,
  },
});

Подробное описание схемы данных и ограничений

В основе описания структуры базы данных в Drizzle ORM лежат таблицы и отношения между ними:

const customBoolean = customType<{ data: boolean }>({
  dataType() {
    return 'boolean';
  },
});

export const examples = pgTable("examples", {
  id: uuid().primaryKey().defaultRandom(), // Первичный ключ
  createdAt: timestamp().defaultNow().notNull(), // Временные метки создания можно определить таким образом

  someVarchar: varchar({ length: 256 }).unique(),
  someInteger: integer().notNull(),
  someDecimal: decimal(),
  someBoolean: boolean().default(true),
  someArray: varchar({}).array(),
  someJson: json(),
  someJsonb: jsonb(),
  someText: text(),
  someTime: time(),
  someTimestamp: timestamp(),
  someUuid: uuid(),
  someCustomBoolean: customBoolean(),
}, table => [ // Индексы на несколько колонок можно добавить следующим образом
  index('examples_some_idx').on(table.someInteger, table.someTimestamp),
  unique('examples_unique').on(table.someBoolean, table.someText),
]);

One-to-one

export const players = pgTable('players', {
  id: uuid().primaryKey().defaultRandom(),
  firstName: varchar({ length: 255 }).notNull(),
  lastName: varchar({ length: 255 }).notNull(),
});

export const playerGameStates = pgTable('player_game_state', {
  id: uuid().primaryKey().defaultRandom(),
  playerId: uuid().notNull().references(() => players.id),
  metadata: jsonb().notNull(),
});

export const playersRelations = relations(players, ({ one }) => ({
  state: one(playerGameStates, {
    fields: [players.id],
    references: [playerGameStates.playerId],
  }),
}));

One-to-many

export const positions = pgTable('positions', {
  id: uuid().primaryKey().defaultRandom(),
  name: varchar({ length: 256 }).unique().notNull(),
  responsibilities: varchar({ length: 256 }).array().notNull(),
});

export const employees = pgTable('employees', {
  id: uuid().primaryKey().defaultRandom(),
  firstName: varchar({ length: 256 }).unique().notNull(),
  lastName: varchar({ length: 256 }).unique().notNull(),
  positionId: uuid().notNull().references(() => positions.id),
});

export const positionsRelations = relations(positions, ({ many }) => ({
  employees: many(employees),
}));

export const employeesRelations = relations(employees, ({ one }) => ({
  position: one(positions, {
    fields: [employees.positionId],
    references: [positions.id],
  }),
}));

Many-to-many

export const customers = pgTable('customers', {
  id: uuid().primaryKey().defaultRandom(),
  firstName: varchar({ length: 256 }).unique().notNull(),
  lastName: varchar({ length: 256 }).unique().notNull(),
});

export const services = pgTable('services', {
  id: uuid().primaryKey().defaultRandom(),
  name: varchar({ length: 256 }).unique().notNull(),
});

export const subscriptions = pgTable('subscriptions', {
  createdAt: timestamp().defaultNow().notNull(),
  isActive: boolean().notNull().default(true),
  customerId: uuid().notNull().references(() => customers.id),
  serviceId: uuid().notNull().references(() => services.id),
}, table => [
  primaryKey({ columns: [table.customerId, table.serviceId] }),
]);

export const customersToServicesSubscriptionRelation = relations(subscriptions, ({ one }) => ({
  customer: one(customers, {
    fields: [subscriptions.customerId],
    references: [customers.id],
  }),
  service: one(services, {
    fields: [subscriptions.serviceId],
    references: [services.id],
  }),
}));

Миграции и построение схемы на основе существующей базы

Для работы с миграциями в Drizzle ORM используется утилита drizzle-kit. Ее нужно установить отдельно.

npm install drizzle-kit

Набор команд:

npx drizzle-kit migrate # Применить миграции
npx drizzle-kit generate # Сгенерировать миграции на основе текущей схемы и структуры базы данных
npx drizzle-kit push # Актуализировать базу данных в обход механизма миграций (удобно при прототипировании)
npx drizzle-kit pull # Построить файлы схемы и отношений на основе существующей базы данных

Конфигурация инструмента описывается в файле drizzle.config.ts или drizzle.config.js.

import 'dotenv/config'; // Подгружаем переменные окружения
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  out: './drizzle', // Рабочая директория для миграций и генерации схемы
  schema: './src/drizzle/schema.ts', // Схема, которая будет использоваться для генерации миграций
  dialect: 'postgresql',
  casing: 'snake_case',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Создание запросов

Для валидации передаваемых значений используется TypeScript, для валидации схем данных — расширение drizzle-zod.

Извлечение данных через ORM-запросы

Извлечение данных в Drizzle ORM можно осуществлять без построения запросов вручную. Для этого в нем предусмотрено два метода: findMany и findFirst.

const accounts = await postgres.query.accounts.findMany({
    where: eq(schema.accounts.isActive, true),
    limit: 5,
    offset: 100,
    orderBy: [desc(schema.accounts.createdAt)],
});

const account = await postgres.query.accounts.findFirst({
    where: and(
        eq(schema.accounts.isActive, true),
        isNotNull(schema.accounts.email),
    ),
    with: {
        carts: true,
    },
});

Извлечение данных через оператор SELECT

Для извлечения данных можно воспользоваться встроенным API построения SQL-запросов. По синтаксису он почти не отличается от других query builder'ов, за исключением типизации, которая здесь строго выведена из схемы.

postgres.select().from(schema.stores)

postgres.select({
    id: schema.stores.id,
    title: schema.stores.title,    
})
.from(schema.stores)
.where(eq(schema.stores.isActive, true))

Джоины описываются таким же образом, как и в большинстве других конструкторов запросов.

await postgres.select()
.from(schema.customerCarts)
.innerJoin(schema.orders, and(
    eq(schema.orders.cartId, schema.customerCarts.id),
    gte(schema.orders.totalCost, 100),
))

Псевдонимы колонок и SQL-выражения можно задать с помощью встроенного в Drizzle ORM оператора sql. Остальные его возможности мы рассмотрим позже.

postgres.select({
  id: sql`${schema.accounts.id}`.as('someId'),
  fullName: sql`${schema.accounts.firstName} || ' ' || ${schema.accounts.lastName}	`.as('fullName'),
}).from(schema.accounts)

Подзапросы и CTE описываются схожим образом:

const subquery = postgres.select().from(schema.stores);

const rowsFromSubquery = await postgres.select().from(schema.stores);


const statsCTE = postgres.$with('stats').as(
    postgres.select({
        accountId:  sql`${schema.accounts.id}`.as('accountId'),
        storeId: sql`${schema.stores.id}`.as('storeId'),
        totalCost: sql`sum(${schema.orders.totalCost})`.as('totalCost'),
        count: sql`sum(${schema.customerCartProducts.count})`.as('count'),
    }).from(schema.stores)
    .innerJoin(schema.customerCarts, eq(schema.customerCarts.storeId, schema.stores.id))
    .innerJoin(schema.accounts, eq(schema.accounts.id, schema.customerCarts.accountId))
    .innerJoin(schema.customerCartProducts, eq(schema.customerCartProducts.cartId, schema.customerCarts.id))
    .innerJoin(schema.orders, eq(schema.orders.cartId, schema.customerCarts.id))
    .where(and(
        inArray(schema.stores.title, stores),
        eq(schema.customerCarts.wasOrdered, true)
    ))
    .groupBy(schema.stores.id, schema.accounts.id)
);

const rowsWithCTE = await postgres.with(statsCTE).select().from(schema.accounts).innerJoin(statsCTE, eq(statsCTE.accountId, schema.accounts.id))

Добавление данных

Drizzle ORM дает возможность проверки корректности типов данных при добавлении в базу — на основе описанной схемы данных. Эти типы можно явно указывать в коде, что позволяет избежать ошибок из-за недостающих данных при подобных операциях. Также можно указать поведение в случае конфликта.

// Сохраним тип черновика, для явного указания
type AccountDraft = typeof schema.accounts.$inferInsert;

const draft1: AccountDraft = {
    firstName: 'John',
    lastName: 'Doe',
};

const draft2: AccountDraft = {
    firstName: 'Robinson',
    lastName: 'Crusoe',
};

// const rows = await postgres.insert(schema.accounts).values(draft1).onConflictDoNothing({ target: schema.accounts.id }).returning();

const rows = await postgres.insert(schema.accounts).values([
    draft1,
    draft2
]).returning().onConflictDoUpdate({
    target: schema.accounts.id,
    set: { firstName: 'Julius', lastName: 'Caesar' },
});

Обновление данных

Обновление данных в Drizzle ORM максимально приближено к SQL.

await postgres.update(schema.stores).set({
    isActive: false,
}).where(
    gte(schema.stores.createdAt, new Date('2025-01-01'))
).returning();

Удаление данных

Удалять данные можно с помощью ранее указанных выражений.

await postgres.delete(schema.players).where(and(
    eq(schema.players.firstName, 'John'),
    eq(schema.players.lastName, 'Doe'),
)).returning();

Работа с оператором sql

При работе с ORM-библиотекой могут возникнуть ситуации, когда написать конкретный запрос с использованием синтаксиса ORM оказывается сложно.

В подобных случаях стоит прибегнуть к использованию параметризованных сырых запросов raw queries и/или преобразованию объектов из TypeScript к SQL-подобному синтаксису — для указания в параметрах. Для этого в Drizzle ORM существует специальный оператор sql. Ниже рассмотрим основные варианты его использования.

Шаблон sql

Простой пример использования оператора sql — подстановка в сырой SQL-запрос наименований таблиц и колонок, а также параметров:

await postgres.execute(
    sql`select ${schema.accounts.phone}, ${schema.accounts.email} from ${schema.accounts} where ${schema.accounts.id} = ${accountId}`
)

sql``.mapWith()

Для указания правил, по которым стоит преобразовывать те или иные данные, можно воспользоваться конструкцией:

postgres.select({
    id: schema.accounts.id,
    count: sql<number>`count(*)`.mapWith(Number) 
}).from(schema.accounts);

sql``.as()

Для того чтобы задать псевдоним для имени, можно взять следующую конструкцию:

sql`sum(store_products.cost)`.as('store_products_total_cost')

sql.raw()

Метод sql.raw() нужен тогда, когда требуется защита содержимого от экранирования или любых других преобразований.

Пример из документации:

sql`select * from ${usersTable} where id = ${12}`;
// select * from "users" where id = $1; --> [12]

sql.raw(`select * from "users" where id = ${12}`);
sql`select * from ${usersTable} where id = ${sql.raw(12)}`;
// select * from "users" where id = 12;

sql.join()

Метод sql.join() поможет объединить несколько параметризованных запросов. 

sql.join([
    sql`select id, first_name, last_name, 'account' from ${schema.accounts}`,
    sql`select id, first_name, last_name, 'employee' from ${schema.employees}`,
], sql.raw(' union '))

// select id, first_name, last_name, 'account' from "accounts" union select id, first_name, last_name, 'employee' from "employees"

Работа с транзакциями

Работа с транзакциями в Drizzle ORM реализована на основе вызова callback`а с получением объекта транзакции для осуществления операций с базо

await postgres.transaction(async trx => {
    const cart = await postgres.query.customerCarts.findFirst({
        where: and(
            eq(schema.customerCarts.accountId, accountId),
            eq(schema.customerCarts.wasOrdered, true)
        )
    });

    // Вложенные транзакции тоже поддерживаются
    await trx.transaction(nestedTrx => nestedTrx.query.accounts.findFirst({ where: eq(schema.accounts.id, accountId) }));

    // trx.rollback(); // Можно откатить транзакцию вручную
    // throw new Error('I will rollback this transaction'); // Или через прикидывание ошибки
}, {
    isolationLevel: "read committed", 
    accessMode: "read write",
    deferrable: true,
});
```

Репликация — в ручном режиме

На момент написания статьи Drizzle ORM не предоставляет встроенной поддержки работы с репликами read/write split. Тем не менее, ее можно реализовать вручную — например, через обертку над drizzle(...), создавая два подключения: одно для записи, другое для чтения.

Примерная структура:

const master = drizzle(process.env.WRITE_DB_URL);
const replica = drizzle(process.env.READ_DB_URL);

// Пишем в master
await master.insert(schema.logs).values({ message: 'hello' });

// Читаем из реплики
const logs = await replica.select().from(schema.logs);

Переключение между инстансами базы придется реализовывать на уровне приложения, особенно при использовании транзакций — они должны всегда работать только на master.

Работа с расширениями для Drizzle ORM

Drizzle ORM поддерживает экосистему расширений, которые позволяют упростить интеграцию с другими библиотеками и улучшить developer experience при разработке. Ниже — два наиболее полезных.

drizzle-zod

Пакет drizzle-zod позволяет автоматически генерировать Zod-схемы на основе описанных в Drizzle таблиц. Это удобно для валидации входных данных, например, в API-обработчиках.

import { createInsertSchema } from 'drizzle-zod';
import { users } from './schema';

const insertUserSchema = createInsertSchema(users);

insertUserSchema— полноценная Zod-схема, которую можно использовать в API для проверки данных.

drizzle-orm/trpc

Для работы с tRPC можно использовать генерацию типов и схем напрямую из Drizzle — это позволяет избежать дублирования контрактов между бэкендом и фронтом.

import { inferRouterInputs, inferRouterOutputs } from '@trpc/server';

type AppRouter = typeof appRouter;

type Inputs = inferRouterInputs<AppRouter>;
type Outputs = inferRouterOutputs<AppRouter>;

Статически типизированные маршруты + строгие схемы данных на уровне API.

Интеграция с фреймворками

Drizzle можно легко использовать в любом современном TypeScript-приложении. Особенность — он не привязан к фреймворку, но спокойно работает с:

• Next.js (App Router) — подключение через серверные обработчики;

• Remix — через лоадеры и экшены;

• NestJS — можно обернуть в провайдер или сервис, как любой другой клиент базы.

Гибкость Drizzle ORM позволяет внедрять инструмент поэтапно — без жестких требований к архитектуре приложения, но с полной типовой поддержкой на всех уровнях.

Ограничения или что стоит учитывать в работе с Drizzle ORM

Drizzle ORM решает многие проблемы классических ORM: он дает типы, остается ближе к SQL и не навязывает архитектуру. Но у него, как и у любого инструмента, есть свои ограничения. Они особенно заметны тем, кто приходит из мира Prisma или TypeORM.

Только SQL-базы

Drizzle работает только с реляционными СУБД: PostgreSQL, MySQL и SQLite. Если вы ищете поддержку MongoDB, Redis или другой NoSQL — этот инструмент не подойдет.

Больше контроля — меньше автоматизации

Drizzle не генерирует схемы «по моделям», не скрывает SQL и не предлагает магии. Это плюс, если вы хотите контролировать все вручную. Но если вы привыкли к удобству Prisma, например, когда можно не думать о связях и все описывается декларативно, то придется переключиться в другой режим работы.

Миграции — только через CLI

Применение миграций реализовано через drizzle-kit. В рантайме, при старте приложения, автоматическое применение миграций не предусмотрено. Это означает, что в CI/CD-процессе нужно явно учитывать миграции как отдельный шаг.

Нет встроенной репликации

Drizzle не управляет подключениями к репликам и не делает read/write split. Все переключение между инстансами баз, например, мастер и реплика — на стороне приложения.

Быстро развивающийся API

Проект активно развивается, и отдельные части экосистемы, например, drizzle-zod, drizzle-studio, могут меняться. Документация не всегда успевает за обновлениями — иногда придется смотреть в исходники.

Меньше готовых решений

Drizzle пока не может похвастаться большим количеством гайдов, Stack Overflow-ответов и туториалов. Для некоторых задач придется изобретать свое — зато часто это «чистый» TypeScript без лишней обвязки.

Drizzle ORM — хороший выбор, если вам нужен контроль, типизация и чистый SQL без лишнего слоя между вами и базой. Она не делает все за вас, но это понятный и стабильный инструмент, на который можно положиться в реальной работе.

Напишите в комментариях, если уже пробовали Drizzle. Будет интересно узнать, как вы его используете и с какими задачами он справился или, наоборот, не справился.