🐘 Postgres из Node: драйвер и ORM
Node-сервис почти всегда ходит в Postgres через пул соединений: драйвер pg напрямую или ORM поверх него. Типичные аварии здесь три: клиента забыли вернуть в пул, транзакцию запустили через pool.query, а ORM тихо сделала тысячу запросов вместо двух. На собеседовании про это спрашивают вместе с вопросом «почему в проекте Prisma, а не TypeORM», и ответ «так было в шаблоне» звучит слабо
🧠 Как это устроено
Зачем нужен пул
Новое соединение с Postgres стоит дорого. Это TCP, часто TLS, аутентификация, и на сервере под каждое соединение стартует отдельный процесс с собственной памятью. Открывать соединение на каждый HTTP-запрос значит платить десятки миллисекунд и упираться в max_connections, который в Postgres по умолчанию равен 100
pg.Pool держит несколько открытых соединений: запрос берёт свободного клиента, выполняет SQL и возвращает его. Если все заняты, запрос ждёт в очереди внутри Node
Значения по умолчанию из документации pg:
| Опция | По умолчанию | Что значит |
|---|---|---|
max | 10 | больше 10 клиентов пул не откроет |
idleTimeoutMillis | 10000 | клиент без работы закрывается через 10 секунд |
connectionTimeoutMillis | 0 | ждать клиента из пула бесконечно |
maxLifetimeSeconds | 0 | соединение живёт сколько угодно |
Размер пула считают от базы, а не от сервиса. Четыре пода по max: 10 открывают до 40 соединений, при деплое blue-green в два цвета — до 80. Это уже рядом со 100. Сумма max по всем экземплярам плюс запас для миграций и админки должна оставаться ниже max_connections. Больше клиентов не значит быстрее: Postgres упирается в ядра и диск, и очередь в Node часто дешевле очереди в базе
С connectionTimeoutMillis: 0 запрос при исчерпанном пуле не падает, а висит, и сервис выглядит живым, но не отвечает. Поставь несколько секунд, и переполненный пул станет понятной ошибкой в логах
pool.query против pool.connect
pool.query(text, values) сам берёт клиента, выполняет один запрос и возвращает клиента. Утечь тут нечему, поэтому для одиночных запросов это вариант по умолчанию
pool.connect() выдаёт клиента тебе в руки, и вернуть его обязан ты через client.release(). Возврат пишут только в finally. Если между connect и release вылетит исключение, а release стоит в конце try, клиент останется занятым навсегда. Десять таких ошибок при max: 10, и пул пуст
client.release(true) не возвращает клиента, а закрывает соединение и освобождает место под новое. Это нужно, когда соединение сломано и отдавать его следующему запросу нельзя
Параметры $1 вместо склейки строк
В запросе pool.query('SELECT * FROM users WHERE email = $1', [email]) текст и значения уходят в Postgres раздельно. Сервер разбирает SQL без значений и подставляет их уже как данные, поэтому строка ' OR '1'='1 останется строкой и не станет частью условия. Шаблонная строка с ${email} склеивает всё в один текст, и Postgres выполнит то, что прислал пользователь
Параметром можно передать только значение. Имя таблицы или колонки параметром не передашь: документация pg прямо говорит, что Postgres не поддерживает параметры для идентификаторов. Для динамического ORDER BY сверяй имя колонки со списком разрешённых, а для DDL есть пакет pg-format
Транзакция живёт на одном соединении
Postgres привязывает транзакцию к соединению. BEGIN, все запросы и COMMIT должны уйти через один и тот же клиент. pool.query каждый раз берёт любого свободного клиента, поэтому BEGIN может открыться на одном соединении, UPDATE выполниться на втором уже без транзакции, а COMMIT уйти на третье, где транзакции нет вовсе
Коварство в том, что локально это работает. Пул в pg-pool отдаёт последнего вернувшегося клиента, и при последовательных await без нагрузки все три запроса попадают в одно соединение. Под нагрузкой соседний запрос забирает клиента между твоими BEGIN и COMMIT. Тогда половина перевода денег закоммичена, или чужой запрос оказался внутри твоей транзакции. Уровни изоляции и блокировки разобраны в модуле «Базы данных»
Три ORM: в чём разница подхода
| Prisma 7 | TypeORM | Drizzle | |
|---|---|---|---|
| Источник схемы | файл schema.prisma на своём языке | классы с декораторами @Entity, @Column | таблицы как TypeScript-код |
| Как получаешь типы | prisma generate генерирует клиента | из классов сущностей | выводятся из схемы, без генерации |
| Стиль запросов | объекты: findMany({ where, include }) | Repository (Data Mapper), BaseEntity (Active Record), QueryBuilder | SQL-подобный билдер: select().from().where(), плюс реляционные запросы |
| Миграции | prisma migrate dev создаёт, migrate deploy применяет | migration:generate, migration:run, migration:revert | drizzle-kit generate и migrate, push для прототипов |
| Цена | своя схема и шаг генерации, сложный SQL уходит в $queryRaw | декораторы и reflect-metadata, типы запросов слабее, много магии в save | нужно думать в SQL, стабильная линия 0.x, версия 1.0 пока в RC |
Prisma 7 заметно поменялась. Драйвер-адаптер теперь обязателен: для Postgres это @prisma/adapter-pg, то есть под Prisma работает тот же pg. Генератор называется prisma-client, клиент работает без Rust-движка и генерируется в папку из обязательного поля output, а не в node_modules. Строка подключения и пути живут в prisma.config.ts, а .env сам не загружается. Проект переводят на ESM, нужен Node 20.19+ и TypeScript 5.4+. migrate dev больше не запускает prisma generate и сиды, их вызывают отдельно. Пулом теперь управляет сам pg с его значениями по умолчанию, в том числе без таймаута на подключение
TypeORM привычна тем, кто писал на Hibernate или Doctrine. Версия 1.0 вышла в мае 2026, подход остался прежним. В Data Mapper запросы живут в репозитории, а сущность остаётся обычным классом. В Active Record сущность наследует BaseEntity и сохраняет себя сама через user.save()
Drizzle не прячет SQL: запрос читается почти как SQL, а типы выводятся из описания таблиц. Его выбирают, когда команда знает SQL и хочет видеть, что уйдёт в базу
N+1: тысяча запросов вместо двух
N+1 получается, когда код берёт список, а потом в цикле догружает связь для каждого элемента: один запрос за 100 пользователями и ещё 100 запросов за их постами. Каждый запрос быстрый, но 101 поход в базу по сети складывается в сотни миллисекунд. В TypeORM с ленивыми связями даже await user.posts в цикле делает отдельный запрос
Найти N+1 проще всего логом запросов: включи его и посмотри, сколько SQL печатает один HTTP-запрос
- Prisma:
new PrismaClient({ adapter, log: ['query'] })или событие$on('query')с текстом, параметрами и длительностью - TypeORM:
logging: ['query']вDataSource - Drizzle:
drizzle({ client: pool, logger: true })
Одинаковый SELECT с разными id подряд и есть N+1. На проде его выдаёт pg_stat_statements: огромное число вызовов при малом времени каждого
Лечат загрузкой связи заранее, одним или двумя запросами
- Prisma:
include: { posts: true }. По умолчанию это два запроса, второй сWHERE "authorId" IN (...). С превью-флагомrelationJoinsвключается стратегияjoin: один запрос черезLATERAL JOIN, переключается опциейrelationLoadStrategy - TypeORM:
relations: { posts: true }вfindилиleftJoinAndSelectв QueryBuilder.eager: trueработает только вfind*, в QueryBuilder нет - Drizzle: обычный
innerJoinилиleftJoin, а в реляционных запросахdb.query.users.findMany({ with: { posts: true } })уходит в базу одним SQL-запросом
В GraphQL у N+1 своё лекарство, DataLoader, подробнее на странице про GraphQL
Пул в Node и PgBouncer
Пул в pg живёт внутри одного процесса. Двадцать подов по 10 соединений дают 200 соединений, и дальше растить нечем. PgBouncer ставят между сервисами и базой: он держит небольшое число настоящих соединений к Postgres и раздаёт их тысячам клиентских
В режиме transaction PgBouncer отдаёт серверное соединение только на время транзакции. Ломается всё, что держится за сессию: SET, LISTEN, сессионные advisory-блокировки, SQL-команды PREPARE. Протокольные подготовленные запросы работают, если включить max_prepared_statements. Пул в приложении остаётся, но небольшой
🛠️ На практике
Транзакция через пул pg
import pg from 'pg'
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 10,
connectionTimeoutMillis: 5000, // по умолчанию 0: ждать клиента вечно
})
// без обработчика ошибка простаивающего клиента роняет процесс
pool.on('error', (err) => console.error('pg idle client error', err))
export async function withTransaction(fn) {
const client = await pool.connect()
try {
await client.query('BEGIN')
const result = await fn(client)
await client.query('COMMIT')
return result
} catch (err) {
await client.query('ROLLBACK')
throw err
} finally {
client.release() // в finally, иначе клиент утечёт на первой же ошибке
}
}
await withTransaction(async (tx) => {
await tx.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [amount, fromId])
await tx.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [amount, toId])
})Все запросы внутри fn идут через переданного клиента, pool.query там ушёл бы мимо транзакции. В ORM обёртка уже есть: prisma.$transaction(async (tx) => …) с таймаутом 5 секунд по умолчанию, dataSource.transaction(async (manager) => …) в TypeORM, db.transaction(async (tx) => …) в Drizzle. Внутри используй tx или manager, а не глобальный клиент
Инъекция и защита
// уязвимо: email = "' OR '1'='1" вернёт всех пользователей
await pool.query(`SELECT * FROM users WHERE email = '${email}'`)
// безопасно: значение уходит отдельно от текста запроса
await pool.query('SELECT * FROM users WHERE email = $1', [email])
// имя колонки параметром не передать, только сверить со списком
const sortable = new Set(['created_at', 'email'])
const column = sortable.has(req.query.sort) ? req.query.sort : 'created_at'
await pool.query(`SELECT * FROM users ORDER BY ${column} LIMIT $1`, [50])В ORM та же ловушка прячется в сырых запросах. В Prisma $queryRaw с тегированным шаблоном превращает ${email} в параметр, а $queryRawUnsafe со склеенной строкой нет. В Drizzle шаблон sql тоже параметризует значения, а sql.raw вставляет текст как есть
Prisma 7 · подключение и N+1 в логе запросов
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter, log: ['query'] })
// N+1: один SELECT за пользователями и ещё по одному на каждого
const users = await prisma.user.findMany()
for (const user of users) {
const posts = await prisma.post.findMany({ where: { authorId: user.id } })
console.log(user.email, posts.length)
}
// два запроса на любое число пользователей: второй с WHERE "authorId" IN (...)
const withPosts = await prisma.user.findMany({ include: { posts: true } })В schema.prisma генератор описан как provider = "prisma-client" с обязательным output = "../src/generated/prisma". После изменения схемы запусти prisma migrate dev, а затем prisma generate: в Prisma 7 первая команда вторую больше не вызывает
TypeORM · чем save отличается от insert
const repo = dataSource.getRepository(User)
// id задан: TypeORM сначала делает SELECT по id, потом INSERT или UPDATE
await repo.save({ id: 42, name: 'Аня' })
// id генерирует база: искать нечего, сразу INSERT
await repo.save({ name: 'Боря' })
// только INSERT: без проверки, без каскадов; при занятом id ошибка уникальности
await repo.insert({ name: 'Вера' })save сравнивает объект с базой, поэтому обновляет только изменённые поля и сохраняет связи с cascade. Цена: лишний SELECT на каждую сущность с id, и цикл из save по тысяче записей даёт около двух тысяч запросов
⚠️ Где ошибаются
client.release()в концеtry, а не вfinally. Каждая ошибка в запросе оставляет одного клиента занятым. Пул пустеет, и однажды сервис зависает без единого исключения. Пишиreleaseвfinallyили используйpool.query, где возврат делает сам пулBEGINчерезpool.query. Локально и в тестах всё проходит, под нагрузкой запросы транзакции разъезжаются по разным соединениям. Транзакция всегда идёт черезpool.connect()и один клиент, а в ORM черезtx- Склейка значения в строку «потому что это число из базы». Сегодня
idпришёл из базы, завтра его передадут в query-параметре. Параметр через$1ничего не стоит, ставь его везде synchronize: trueв TypeORM на проде. Документация TypeORM называет это небезопасным, как только в базе появились данные: переименование поля превратится в удаление колонки и создание новой. На проде нужны миграции, аprisma db pushиdrizzle-kit pushоставь для прототипов- Размер пула без учёта числа экземпляров.
max: 50на каждый под выглядит щедро, пока подов не станет три, а при деплое шесть. Postgres отвечаетtoo many clients already, и падают все сервисы этой базы
🎯 Вопросы с собеседований
Как защититься от SQL-инъекции?
Передавать значения параметрами: $1, $2 в pg, а в ORM обычные методы или тегированные шаблоны вроде $queryRaw и sql. Текст и значения уходят в Postgres раздельно, и значение не станет частью SQL. Имена колонок и таблиц параметром не передать, их сверяют с белым списком. Опасные места в ORM: $queryRawUnsafe в Prisma, sql.raw в Drizzle, строковые условия в QueryBuilder TypeORM со склейкой. И не давай пользователю базы лишних прав, чтобы удачная инъекция не могла удалить таблицу
Как сделать транзакцию через пул pg?
Взять клиента через pool.connect(), на нём выполнить BEGIN, запросы и COMMIT, при ошибке ROLLBACK, а client.release() вызвать в finally. Через pool.query транзакцию делать нельзя: каждый вызов может попасть на другое соединение, а транзакция в Postgres привязана к соединению. Хороший ответ добавляет, что локально баг не виден: без конкуренции пул отдаёт одного и того же клиента. Обычно пишут обёртку withTransaction(fn), которая передаёт клиента в колбэк, чтобы никто не забыл release
Что такое N+1 и как его найти?
Один запрос за списком и ещё по запросу на каждый элемент за его связью. Находят логом запросов (log: ['query'] в Prisma, logging в TypeORM, logger: true в Drizzle): сотня одинаковых SELECT с разными id на один HTTP-запрос и есть N+1. На проде помогает pg_stat_statements. Лечат загрузкой связи заранее: include в Prisma, relations или leftJoinAndSelect в TypeORM, join или with в Drizzle, а в GraphQL DataLoader
Почему Express и Prisma, почему именно эта ORM?
Отвечай через свой проект и компромисс, а не через «модно». Пример для Prisma: схема в одном файле читается всей командой, сгенерированный клиент даёт точные типы результата с учётом select и include, миграции создаются из схемы. Назови и цену: отдельный язык схемы, шаг prisma generate в сборке, сложные отчётные запросы приходится писать через $queryRaw. Покажи, что сравнивал: Drizzle ближе к SQL и обходится без генерации. Про выбор Express подробнее на странице про HTTP-сервер и Express
Чем insert отличается от save в ORM?
В TypeORM save сначала проверяет, есть ли запись: если у объекта задан id, делает SELECT по нему и затем INSERT или UPDATE только изменённых полей. Он же сохраняет связи с cascade и выполняет всё в транзакции. insert отправляет один INSERT без проверки, и если такой id уже есть, получишь ошибку уникальности. Поэтому save берут для редактирования одной сущности, а insert или upsert для массовой загрузки. Распространённое «insert не вызывает слушателей» неверно: @BeforeInsert срабатывает и у него
ORM или чистый SQL?
Обычно берут оба. ORM экономит время на типовом CRUD, даёт типы и миграции, но прячет запросы, и N+1 или лишний SELECT в save видно только в логе. Чистый SQL через pg даёт полный контроль над запросом, окнами и CTE, но типы результата и маппинг пишешь сам. Рабочий вариант: ORM или билдер вроде Drizzle для типовых запросов и сырой SQL с параметрами для отчётов и тяжёлых выборок
📚 Что почитать
- Pooling в node-postgres — когда
pool.query, когдаpool.connect, и почему клиент безreleaseвешает пул - Transactions в node-postgres — каноничный пример транзакции на одном клиенте
- Upgrade to Prisma ORM 7 — драйвер-адаптеры, новый генератор,
prisma.config.tsи что перестало запускаться само - PgBouncer features — режимы пула и что ломается в
transaction