К содержимому
Войти

Node.js Road Map

🐘 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:

ОпцияПо умолчаниюЧто значит
max10больше 10 клиентов пул не откроет
idleTimeoutMillis10000клиент без работы закрывается через 10 секунд
connectionTimeoutMillis0ждать клиента из пула бесконечно
maxLifetimeSeconds0соединение живёт сколько угодно

Размер пула считают от базы, а не от сервиса. Четыре пода по 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 7TypeORMDrizzle
Источник схемыфайл schema.prisma на своём языкеклассы с декораторами @Entity, @Columnтаблицы как TypeScript-код
Как получаешь типыprisma generate генерирует клиентаиз классов сущностейвыводятся из схемы, без генерации
Стиль запросовобъекты: findMany({ where, include })Repository (Data Mapper), BaseEntity (Active Record), QueryBuilderSQL-подобный билдер: select().from().where(), плюс реляционные запросы
Миграцииprisma migrate dev создаёт, migrate deploy применяетmigration:generate, migration:run, migration:revertdrizzle-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