Доступ к базам данных в Node.js
Запрос пользователя почти всегда заканчивается обращением к базе, и именно там сервис чаще всего теряет время, соединения и данные. Ошибки доступа редко выглядят как падение: это медленный ответ, исчерпанный пул, повисшая транзакция или тихо продублированная строка. Разберём, как Node-сервис работает с PostgreSQL через pg: от пула соединений и параметризованных запросов до транзакций, N+1, ORM и миграций.
Содержание
- Где живёт доступ к данным
- Драйвер и пул соединений
- Размер пула и лимиты
- Параметризованные запросы
- Транзакции: один клиент на операцию
- Транзакция на весь запрос
- Ошибки драйвера и повтор
- Проблема N+1
- ORM как слой
- Миграции
- Таймауты и отмена
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Где живёт доступ к данным
SQL в Node-сервисе легко расползается по коду: pool.query в контроллере, ещё один в middleware, третий в обработчике вебхука. Через месяц никто не знает, какие запросы идут в рамках транзакции, а тест на бизнес-правило требует живой базы.
Поэтому доступ к данным выносят в отдельный слой — репозитории:
src/
db/
pool.js # соединение и его настройки
transaction.js # обёртка над BEGIN/COMMIT
repositories/
tasks.js # запросы к tasks
projects.js # запросы к projects
services/
tasks.js # бизнес-логика, не знает про pg
routes/
tasks.js # HTTP, не знает про SQL
У такого разделения три следствия. SQL живёт в одном месте и его видно целиком. Сервис работает с доменными объектами, а не с rowCount и rows. А тесты репозитория можно писать против реальной базы, не поднимая HTTP-слой.
Граница важна и в обратную сторону: контроллер не должен собирать where из req.query, а сервис — знать про $1. Иначе параметры запроса и SQL переплетаются, и валидация из статьи «Конфигурация и валидация» оказывается единственным барьером между клиентом и базой.
Теория самих баз — индексы, планы, изоляция, нормализация — в этом разделе не разбирается: это тема раздела «Базы данных». Здесь только серверная сторона: как Node открывает соединения, отправляет запросы и обрабатывает ответы.
Драйвер и пул соединений
Прямой путь в PostgreSQL из Node — пакет pg, реализация протокола поверх TCP. У него два основных класса:
| Класс | Что делает | Когда использовать |
|---|---|---|
Client | одно соединение | скрипты, миграции, CLI |
Pool | набор соединений и очередь ожидания | серверное приложение |
Соединение с базой — не бесплатная операция: TCP-handshake, TLS, аутентификация и инициализация сессии занимают миллисекунды, а на удалённой базе и десятки миллисекунд. Открывать соединение на каждый запрос значит платить эту цену постоянно и упираться в лимит базы. Пул держит готовые соединения и переиспользует их.
// src/db/pool.js
import { Pool } from 'pg';
import { config } from '../config.js';
import { logger } from '../lib/logger.js';
export const pool = new Pool({
connectionString: config.DATABASE_URL,
max: config.DB_POOL_MAX,
idleTimeoutMillis: 30_000,
connectionTimeoutMillis: 2_000,
statement_timeout: 5_000,
application_name: 'taskflow-api',
});
pool.on('error', (error) => {
logger.error({ err: error }, 'idle database client error');
});
Разберём настройки:
max— сколько соединений держать одновременно; по умолчанию 10.idleTimeoutMillis— через сколько закрывать простаивающее соединение; по умолчанию 10 секунд.connectionTimeoutMillis— сколько ждать подключения и свободного клиента из пула;0означает «ждать бесконечно».statement_timeout— серверный лимит на выполнение запроса.application_name— метка, по которой процесс видно вpg_stat_activity; без неё в списке соединений десятки безымянных клиентов.
DB_POOL_MAX добавляется в схему конфига из статьи «Конфигурация и валидация» рядом с DATABASE_URL — тогда опечатка в имени переменной роняет сервис на старте, а не на первом запросе.
Обработчик pool.on('error') обязателен. Если база перезапустилась или балансировщик разорвал idle-соединение, pg выбросит событие error на клиенте. Без слушателя EventEmitter превратит его в uncaughtException и уронит процесс — подробнее в статье «EventEmitter и события». Сам пул после такого события продолжает работать: следующий запрос создаст новое соединение.
Пул ленивый: new Pool() не открывает соединения, а первое появляется при первом запросе. Поэтому ошибка конфигурации видна не на старте, а на первом обращении — если нужен fail fast, на старте выполняют select 1. Заодно это проверка readiness, о которой говорилось в статье «Логирование и наблюдаемость».
Закрывать пул нужно явно при остановке:
await pool.end();
pool.end() перестаёт выдавать новые клиенты, закрывает простаивающие соединения и ждёт, пока занятые вернутся в пул. В graceful shutdown это один из последних шагов — после того как сервер перестал принимать трафик.
Размер пула и лимиты
Главная ошибка — считать пул локальной настройкой. Он задаётся на процесс, а процессов в проде много:
10 подов × DB_POOL_MAX=20 = 200 соединений
PostgreSQL max_connections = 100
Итог предсказуем: часть подов не сможет подключиться, а select 1 в readiness начнёт падать. При этом приложение будет выглядеть исправным — ошибка приходит из базы, а не из кода.
Формула простая:
pool_max ≤ (max_connections − служебный запас) / число процессов
Служебный запас нужен для миграций, административных подключений и pg_dump. Если процесс запущен через cluster или PM2 в режиме нескольких воркеров, пул появляется в каждом воркере: четыре воркера с max: 10 — это сорок соединений, а не десять.
Второе заблуждение — «чем больше пул, тем быстрее». База упирается в CPU, диск и блокировки; лишние соединения добавляют переключения контекста и конкуренцию за одни и те же ресурсы. Оптимальный размер обычно невелик и подбирается нагрузочным тестом, а не на глаз.
Что происходит, когда пул занят: запросы встают в очередь внутри процесса. Если очередь не ограничена, запрос может прождать дольше, чем клиент готов ждать, и вернуться уже никому не нужным. connectionTimeoutMillis ограничивает это ожидание и превращает перегрузку в быструю ошибку вместо тихого зависания.
При большом числе подов пул выносят наружу — ставят PgBouncer в transaction-режиме. Тогда приложение открывает много дешёвых соединений к пулеру, а тот держит десяток реальных к базе. Плата — ограничения: session-настройки и prepared statements в transaction-режиме работают не так, как при прямом подключении, поэтому настройки вроде statement_timeout задают через пулер или на уровне роли.
Параметризованные запросы
Значения в SQL передаются плейсхолдерами, а не конкатенацией:
// правильно
const { rows } = await pool.query(
'select id, title, done from tasks where owner_id = $1 and done = $2',
[userId, done],
);
// неправильно: инъекция
const { rows } = await pool.query(
`select id, title from tasks where owner_id = '${userId}'`,
);
Разница не в «экранировании кавычек», а в протоколе. Когда pg получает массив значений, он отправляет запрос через extended query protocol: SQL и параметры идут отдельно, база разбирает запрос до того, как увидит данные. Значение ' or 1=1 -- остаётся строкой и никогда не станет частью синтаксиса.
У этого есть приятный побочный эффект: в одном вызове с параметрами нельзя выполнить несколько statement’ов через ;. Это закрывает целый класс атак и заодно мешает случайно отправить «пакет» запросов, который выполнится наполовину.
Тип значения база выводит из контекста, но иногда нужен явный каст:
await pool.query(
'select id from tasks where id = $1::uuid',
[taskId],
);
Без каста PostgreSQL может не понять, что $1 — UUID, и сравнение с колонкой типа uuid даст ошибку operator does not exist. Каст заодно превращает мусор в понятную ошибку 22P02 вместо неожиданного поведения.
Идентификаторы и динамический SQL
Параметром нельзя передать имя таблицы, колонки или направление сортировки. order by $1 не подставит значение — PostgreSQL воспримет это как константу и просто отсортирует по ней, а попытка собрать строку через конкатенацию снова открывает инъекцию.
Поэтому динамические части берут из allowlist:
const SORTABLE = {
created: 'created_at',
title: 'title',
due: 'due_at',
};
function listTasks({ ownerId, sort = 'created', order = 'desc' }) {
const column = SORTABLE[sort] ?? 'created_at';
const direction = order === 'asc' ? 'asc' : 'desc';
return pool.query(
`select id, title, done
from tasks
where owner_id = $1
order by ${column} ${direction}
limit $2`,
[ownerId, limit],
);
}
Здесь в SQL попадают только значения из словаря и два литерала, а всё остальное — параметры. Ключ, которого нет в SORTABLE, молча превращается в дефолтную сортировку: это лучше, чем 500, и безопаснее, чем попытка «починить» вход.
Тот же приём нужен для фильтров, которые добавляются условно:
const conditions = ['owner_id = $1'];
const values = [ownerId];
if (done !== undefined) {
values.push(done);
conditions.push(`done = $${values.length}`);
}
const sql = `select id, title from tasks where ${conditions.join(' and ')}`;
Условия собираются из фиксированных фрагментов, а нумерация $n растёт вместе с массивом. Такой код легко ошибиться в индексе, поэтому его покрывают тестами на каждый вариант фильтра.
Отдельная ловушка — like:
await pool.query(
'select id from tasks where title ilike $1',
[`%${escapeLike(term)}%`],
);
Символы % и _ в пользовательском вводе — часть шаблона, а не текста. Их экранируют, иначе поиск по 100% начнёт возвращать всё подряд.
Транзакции: один клиент на операцию
Транзакция гарантирует, что несколько изменений применятся целиком или не применятся вовсе. В pg это не отдельный API, а последовательность команд на одном соединении:
begin;
update accounts set balance = balance - 100 where id = 1;
update accounts set balance = balance + 100 where id = 2;
commit;
Ключевая деталь: pool.query каждый раз берёт произвольный свободный клиент. Два вызова подряд могут уйти в разные соединения, и begin в одном не будет виден другому. Поэтому транзакцию выполняют через pool.connect():
// src/db/transaction.js
import { pool } from './pool.js';
export async function withTransaction(fn) {
const client = await pool.connect();
let broken = false;
try {
await client.query('begin');
const result = await fn(client);
await client.query('commit');
return result;
} catch (error) {
try {
await client.query('rollback');
} catch {
broken = true; // состояние соединения неизвестно
}
throw error;
} finally {
client.release(broken ? new Error('connection state unknown') : undefined);
}
}
Что здесь важно:
release()ровно один раз и вfinally. Если release стоит вtryи обработчик бросил исключение, соединение утечёт. После исчерпания пула сервис зависнет наpool.connect().rollbackвcatch, а не вfinally. Вfinallyоткат выполнялся бы и после успешногоcommit, то есть на пустой транзакции.release(err)уничтожает соединение. Если откат не удался, состояние клиента неизвестно: в нём может остаться открытая транзакция или незавершённый протокол. Такой клиент нельзя возвращать в пул.- Возврат значения — только после
commit.returnвнутриtryсначала выполнитfinally, ноcommitдолжен стоять доreturn, иначе вызывающий код получит результат ещё не подтверждённой транзакции.
Вложенные транзакции и блокировки
Вложенного begin в PostgreSQL нет: второй begin внутри транзакции выдаст предупреждение и не создаст новый уровень. Если часть операции нужно откатить отдельно, используют savepoint:
await client.query('savepoint before_audit');
try {
await logAudit(client, event);
} catch {
await client.query('rollback to savepoint before_audit');
}
Для сценариев «прочитать и изменить» одной транзакции мало: два параллельных запроса прочитают одно и то же значение и запишут результат поверх друг друга. Нужна блокировка строки:
const { rows } = await client.query(
'select id, balance from accounts where id = $1 for update',
[accountId],
);
for update блокирует строку до конца транзакции, и второй запрос ждёт. Альтернатива — атомарный update ... where условие returning *: кто обновил, тот и выиграл. Такой приём разобран в статье «Аутентификация в API» на примере ротации refresh-токена.
Уровни изоляции и то, какие аномалии они предотвращают, — тема раздела «Базы данных». В прикладном коде важно помнить: транзакция удерживает соединение и блокировки, поэтому внутри неё не делают HTTP-вызовов, не ждут очередей и не запускают долгие вычисления.
Транзакция на весь запрос
Явная передача client в каждый репозиторий быстро надоедает:
await withTransaction(async (client) => {
const task = await tasksRepo.findById(client, id);
await tasksRepo.move(client, id, projectId);
await activityRepo.log(client, id, 'moved');
});
Забытый client в одном вызове означает, что часть работы вышла из транзакции и не откатится. Решение — AsyncLocalStorage: контекст с клиентом кладут в хранилище, а репозитории берут его оттуда.
// src/db/context.js
import { AsyncLocalStorage } from 'node:async_hooks';
import { pool } from './pool.js';
import { withTransaction } from './transaction.js';
const txStore = new AsyncLocalStorage();
export function currentDb() {
return txStore.getStore()?.client ?? pool;
}
export function runInTransaction(fn) {
return withTransaction((client) => txStore.run({ client }, () => fn(client)));
}
Репозиторий больше не принимает клиента:
// src/repositories/tasks.js
import { currentDb } from '../db/context.js';
export async function findById(id) {
const { rows } = await currentDb().query(
'select id, title, project_id from tasks where id = $1',
[id],
);
return rows[0] ?? null;
}
А маршрут выглядит как обычная последовательность вызовов:
await runInTransaction(async () => {
const task = await findById(taskId);
if (!task) throw new HttpError(404, 'task not found');
await move(task.id, projectId);
await logActivity(task.id, 'moved');
});
AsyncLocalStorage.run() возвращает промис, поэтому контекст живёт всё время выполнения и переносится через await, таймеры и колбэки драйвера. Как это работает и почему enterWith здесь опасен — в статье «Асинхронность в Node.js».
У приёма есть цена. Транзакция становится невидимой: любой код внутри runInTransaction автоматически в неё попадает, включая случайный вызов внешнего API. Поэтому:
- транзакцию открывают точечно на изменяющую операцию, а не на весь HTTP-запрос;
- внутри неё не бывает сетевых вызовов и тяжёлых вычислений;
- долгие операции выносят в фон, а не растягивают транзакцию;
- тесты проверяют, что репозиторий работает и с пулом, и с клиентом транзакции.
В NestJS и Prisma ту же роль играет $transaction, но принцип не меняется: все операции должны идти через один клиент, а граница транзакции должна быть явной.
Ошибки драйвера и повтор
pg возвращает ошибку с полем code — это SQLSTATE. По нему решают, что делать, вместо разбора текста сообщения:
code | Значение | Что делать |
|---|---|---|
23505 | unique_violation | 409 Conflict, поле — из constraint |
23503 | foreign_key_violation | 422 или 409 |
23502 | not_null_violation | 422, но обычно это баг валидации |
22P02 | invalid_text_representation | 422: значение не того типа |
40001 | serialization_failure | повторить транзакцию |
40P01 | deadlock_detected | повторить транзакцию |
57014 | query_canceled | сработал statement_timeout |
57P01 | admin_shutdown | соединение закрыто сервером |
Клиентские ошибки (23xxx, 22xxx) — это не сбой сервиса, а неверные данные: их превращают в 4xx и не пишут в error. Ошибки соединения (ECONNREFUSED, ECONNRESET, ETIMEDOUT) и таймауты — операционные: их логируют, а решение о повторе принимает вызывающий слой.
Повторять безопасно не всё. 40001 и 40P01 означают, что транзакция отменена базой и её можно выполнить заново целиком — это самый чистый случай для retry. Ошибку соединения можно повторить, если операция идемпотентна или защищена ключом идемпотентности; повтор insert без такой защиты создаст дубль или вернёт 23505. Подробнее про backoff и классификацию ошибок — в статье «Таймауты, ретраи и graceful shutdown».
Маппинг ошибок живёт на границе репозитория или в error middleware:
export function toHttpError(error) {
if (error.code === '23505') {
return new HttpError(409, 'already exists', { constraint: error.constraint });
}
if (error.code === '57014') {
return new HttpError(503, 'database timeout');
}
if (['40001', '40P01'].includes(error.code)) {
return new RetryableError(error);
}
return error;
}
Поле error.detail наружу не отдают: в нём бывают значения из строки — например, Key (email)=(user@example.com) already exists. Наружу идёт имя ограничения или общий текст, а подробности — в лог.
Отдельная тонкость — count. select count(*) возвращает int8, а pg по умолчанию отдаёт int8 строкой, потому что число может не влезть в Number. В коде это выглядит как '42' вместо 42:
const { rows } = await pool.query('select count(*) from tasks where owner_id = $1', [ownerId]);
const total = Number(rows[0].count);
Тип можно переопределить через pg.types.setTypeParser, но тогда за точность отвечает приложение. Для пагинации хватает явного Number() на границе.
Проблема N+1
N+1 — это один запрос за списком и ещё N запросов за связанными данными:
// плохо: 1 + N запросов
const { rows: tasks } = await pool.query(
'select id, title, project_id from tasks where owner_id = $1',
[ownerId],
);
for (const task of tasks) {
const { rows } = await pool.query(
'select name from projects where id = $1',
[task.project_id],
);
task.projectName = rows[0]?.name;
}
На десяти задачах это незаметно, на тысяче — тысяча сетевых round-trip’ов вместо одного, и пул занят дольше, чем нужно. Запросы выполняются последовательно, поэтому задержка складывается: при 1 мс на запрос получается секунда только на «достать названия проектов».
Правильных вариантов два. Первый — join, если связь один-к-одному или нужно немного полей:
const { rows } = await pool.query(
`select t.id, t.title, p.name as project_name
from tasks t
join projects p on p.id = t.project_id
where t.owner_id = $1`,
[ownerId],
);
Второй — пакетная загрузка: собрать идентификаторы и сделать один запрос по массиву:
const projectIds = [...new Set(tasks.map((task) => task.project_id))];
const { rows: projects } = await pool.query(
'select id, name from projects where id = any($1::uuid[])',
[projectIds],
);
const byId = new Map(projects.map((project) => [project.id, project]));
tasks.forEach((task) => {
task.projectName = byId.get(task.project_id)?.name;
});
Пакетный вариант удобнее, когда связанные данные нужны не всегда или когда join размножает строки. Для связи один-ко-многим join даёт дубликаты родителя, и либо их схлопывают в коде, либо агрегируют на стороне базы через json_agg.
Увидеть N+1 можно тремя способами:
- Счётчик запросов на запрос. В тесте или на стейдже оборачивают
pool.queryи сравнивают число вызовов с ожидаемым. Тест «список из 50 задач делает не больше двух запросов» ловит регрессию сразу. - Спаны трассировки. Автоинструментация
pgсоздаёт спан на каждый запрос; в трейсе видно пятьдесят одинаковых спанов подряд — это и есть N+1. pg_stat_statements. Расширение показывает суммарное число вызовов по шаблону запроса: один и тот жеselect ... where id = $1с тысячами вызовов — характерный след.
Смотреть надо не на отдельный медленный запрос, а на их количество: N+1 часто состоит из быстрых запросов, которые вместе дают медленный ответ.
ORM как слой
ORM и query builder — это надстройка над драйвером, а не замена ему. Они дают три вещи: типизированные запросы, миграции и маппинг строк в объекты.
| Инструмент | Стиль | Сильная сторона |
|---|---|---|
| Prisma | схема и генерация клиента | типы, миграции, include |
| Drizzle | SQL-подобный builder | близость к SQL, лёгкий runtime |
| Kysely | типизированный query builder | типы без магии, хорош в существующей базе |
Главная выгода — типы на границе базы: select возвращает известную форму, а переименование колонки ломает сборку, а не прод. Главная опасность — та же, что у ручного кода: ORM не отменяет ни N+1, ни транзакций, ни знания SQL.
N+1 в ORM выглядит аккуратнее, но остаётся N+1:
// Prisma: если связь не загружена заранее, каждый доступ — отдельный запрос
const tasks = await prisma.task.findMany({ where: { ownerId } });
for (const task of tasks) {
console.log(task.project.name);
}
Лечится eager loading:
const tasks = await prisma.task.findMany({
where: { ownerId },
include: { project: { select: { name: true } } },
});
В Drizzle аналогичную роль играет with в relational queries, в Kysely — явный join. Но eager loading тоже не бесплатен: include по связи один-ко-многим может породить большой join или несколько запросов, поэтому состав выборки проверяют так же, как ручной SQL.
Второе правило — ORM живёт в репозитории. Если PrismaClient импортируется в сервис или контроллер, домен начинает зависеть от схемы базы: тесты требуют клиента, а смена ORM превращается в переписывание бизнес-логики. Репозиторий возвращает доменные объекты, а не Prisma.Task.
Третье — escape hatch обязателен. Сложный отчёт, оконная функция, upsert с условием или for update часто проще выразить SQL’ом. У Prisma это $queryRaw с тегированным шаблоном, у Drizzle — sql, у Kysely — sql внутри builder’а. Важно, чтобы такие запросы оставались параметризованными: тегированный шаблон подставляет значения как параметры, а конкатенация строк — нет.
Что ORM не решает: выбор индекса, план запроса, уровень изоляции, стоимость join’а. Это остаётся знанием SQL и темой раздела «Базы данных».
Миграции
Схема базы меняется вместе с кодом, и изменения должны быть версионированы. Миграция — это файл с SQL и запись в таблице применённых миграций:
-- migrations/004_add_project_id.sql
alter table tasks
add column project_id uuid references projects(id);
create index tasks_project_id_idx on tasks (project_id);
Инструмент выбирают по стеку: node-pg-migrate для чистого pg, prisma migrate для Prisma, drizzle-kit для Drizzle. Все они хранят историю и применяют только новые файлы.
Три правила, которые экономят инциденты:
Миграции — отдельный шаг деплоя. Если запускать их при старте приложения, десять подов одновременно попытаются применить один файл. Часть упадёт на конфликте DDL, часть подерётся за блокировки, а сервис начнёт принимать трафик в промежуточном состоянии схемы. Поэтому миграции запускают джобой до выкатки, а приложение стартует уже на готовой схеме.
Нужен advisory lock. Деплой может запустить миграцию дважды — из-за ретрая или ручного вмешательства. Transaction-level блокировка гарантирует, что второй процесс дождётся первого и увидит, что работа уже сделана:
select pg_advisory_xact_lock(42);
Изменения — обратно совместимыми. Старая и новая версии приложения какое-то время работают одновременно. Поэтому колонку добавляют nullable, бэкфиллят отдельно, переключают чтение, и только потом делают not null и удаляют старое. Это паттерн expand/contract: каждый шаг совместим с обеими версиями кода.
Чего не делать: synchronize: true в проде, ручные alter table «по-быстрому», откат миграции через удаление файла и правку схемы вручную. История миграций должна совпадать с реальной схемой, иначе следующий деплой на чистой базе соберёт не то, что работает в проде.
Таймауты и отмена
У запроса к базе несколько независимых таймаутов, и путать их дорого:
| Таймаут | Где работает | Что ограничивает |
|---|---|---|
connectionTimeoutMillis | клиент | подключение и ожидание клиента из пула |
query_timeout | клиент | ожидание ответа драйвером |
statement_timeout | сервер | выполнение запроса базой |
idle_in_transaction_session_timeout | сервер | простой сессии внутри транзакции |
Ключевое различие: клиентский таймаут не отменяет запрос. Когда query_timeout истекает, pg перестаёт ждать и возвращает ошибку, но PostgreSQL продолжает выполнять запрос, держать соединение, блокировки и снимок. Если таких запросов накопилось много, база работает на клиентов, которых уже нет.
Поэтому statement_timeout обязателен. Его задают на уровне роли, базы или подключения:
export const pool = new Pool({
connectionString: config.DATABASE_URL,
statement_timeout: 5_000,
query_timeout: 6_000,
});
query_timeout здесь чуть больше серверного: сервер успевает ответить ошибкой 57014, и приложение получает понятную причину, а не обрыв на своей стороне.
Для отдельных операций лимит можно переопределить внутри транзакции:
await client.query("set local statement_timeout = '30s'");
await client.query(
'update tasks set project_id = $1 where project_id is null',
[defaultProjectId],
);
set local действует до конца транзакции и не протекает в следующие запросы на этом соединении — важно, потому что соединение вернётся в пул и им воспользуется другой запрос.
Второй серверный лимит — idle_in_transaction_session_timeout — закрывает сессию, которая открыла транзакцию и зависла. Без него забытый commit держит блокировки и мешает vacuum’у до перезапуска соединения. Разумное значение — несколько минут, а не часы.
Отмена по AbortSignal у pg нет: сигнал не пробрасывается в драйвер. Если клиент ушёл, запрос всё равно доработает, поэтому ставку делают на серверные таймауты и короткие транзакции, а не на отмену со стороны Node.
Практика: TaskFlow
Соберём доступ к данным для TaskFlow из статей «Express и middleware» и «Конфигурация и валидация».
1. Пул и транзакции. src/db/pool.js и src/db/transaction.js из этой статьи, src/db/context.js с AsyncLocalStorage.
2. Репозиторий задач. Все запросы — через currentDb(), поэтому один и тот же код работает и в обычном запросе, и внутри транзакции:
// src/repositories/tasks.js
import { currentDb } from '../db/context.js';
export async function listByOwner(ownerId, { done, limit }) {
const conditions = ['t.owner_id = $1'];
const values = [ownerId];
if (done !== undefined) {
values.push(done);
conditions.push(`t.done = $${values.length}`);
}
values.push(limit);
const { rows } = await currentDb().query(
`select t.id, t.title, t.done, t.project_id, p.name as project_name
from tasks t
left join projects p on p.id = t.project_id
where ${conditions.join(' and ')}
order by t.created_at desc
limit $${values.length}`,
values,
);
return rows;
}
export async function move(taskId, projectId) {
const { rowCount } = await currentDb().query(
'update tasks set project_id = $2, updated_at = now() where id = $1',
[taskId, projectId],
);
return rowCount === 1;
}
Здесь закрыты три вещи: значения параметризованы, связанные проекты приходят одним join’ом вместо N+1, а rowCount честно говорит, нашлась ли строка.
3. Перемещение задачи в транзакции. Два изменения должны примениться вместе:
// src/routes/tasks.js
router.patch('/:id/move', validate({ params: TaskIdParamsSchema, body: MoveTaskSchema }), async (req, res) => {
const { id } = req.validated.params;
const { projectId } = req.validated.body;
await runInTransaction(async () => {
const moved = await tasksRepo.move(id, projectId);
if (!moved) throw new HttpError(404, 'task not found');
await activityRepo.log(id, 'moved', req.user.id);
});
res.status(204).end();
});
Ошибка на любом шаге откатит оба изменения, а клиент получит 404 или 422 из error middleware, а не 500.
4. Ошибки. toHttpError из раздела про коды превращает 23505 в 409, а 57014 — в 503. Текст detail наружу не уходит.
5. Миграция. Отдельный файл, отдельный шаг деплоя:
-- migrations/005_tasks_project_id.sql
alter table tasks add column project_id uuid references projects(id);
create index tasks_project_id_idx on tasks (project_id);
create index tasks_owner_created_idx on tasks (owner_id, created_at desc);
Что закрыто: пул ограничен и посчитан от лимита базы; соединения не утекают; транзакция атомарна и не растянута на HTTP-вызовы; список задач не порождает N+1; ошибки базы превращаются в понятные статусы; миграция не гоняется между подами.
Что добавляют дальше: PgBouncer при росте числа подов, реплика для чтения, pg_stat_statements и алерты по занятости пула, а также тест, который считает запросы на ключевых сценариях.
Частые ошибки
- Пул на каждый запрос.
new Pool()в обработчике открывает соединения и не закрывает их; пул создаётся один раз на процесс. - Пул больше лимита базы. Десять подов умножают
maxна десять и упираются вmax_connections. - Нет
pool.on('error'). Оборванное idle-соединение становитсяuncaughtException. pool.queryвнутри транзакции.beginиcommitуходят в разные соединения, транзакция не работает.release()не вfinally. При исключении соединение утекает, и пул постепенно исчерпывается.- Двойной
release(). Возврат одного клиента дважды ломает учёт пула. rollbackзабыт. Соединение возвращается с открытой транзакцией, и следующие запросы попадают в неё.- Конкатенация значений в SQL. Инъекция и поломка на кавычке в тексте.
- Имя колонки из query без allowlist.
order by ${sort}— такая же инъекция, как вwhere. - N+1 в цикле. Один запрос на элемент превращает список в сотни round-trip’ов.
- Долгая транзакция с HTTP-вызовом внутри. Соединение и блокировки держатся на время чужого таймаута.
query_timeoutбезstatement_timeout. База продолжает считать запрос, который клиент уже бросил.count(*)как число.pgотдаётint8строкой, и сравнениеtotal > 0ведёт себя не так, как ожидается.- Миграции при старте каждого пода. Гонка за DDL-блокировки и трафик на промежуточной схеме.
error.detailв ответе. В тексте ошибки оказываются значения из строк, включая персональные данные.- ORM-типы в домене. Смена ORM превращается в переписывание бизнес-логики, а тесты требуют базы.
Ключевые тезисы для интервью
pgработает поверх пула:Poolпереиспользует соединения, аpool.queryберёт произвольного клиента, поэтому транзакция требуетpool.connect()—beginиcommitдолжны идти по одному соединению. Размер пула задаётся на процесс, умножается на число реплик и считается отmax_connections, а не «побольше».- Значения передаются только параметрами
$1: extended protocol отделяет SQL от данных, поэтому инъекция невозможна. Идентификаторы и сортировка параметрами не передаются — только allowlist. - Транзакция живёт на одном клиенте:
begin→ работа →commit,rollbackвcatch,release()вfinallyровно один раз, аrelease(err)уничтожает соединение с неизвестным состоянием. AsyncLocalStorageпозволяет репозиториям автоматически попадать в текущую транзакцию, но делает её невидимой — поэтому границу открывают точечно и не смешивают с внешними вызовами.- N+1 — это один запрос за списком плюс N за связями; лечится join’ом, пакетной загрузкой или eager loading, а ловится счётчиком запросов и спанами трассировки.
- Клиентский таймаут не отменяет запрос:
statement_timeoutобязателен, иначе база продолжает работать на клиентов, которых уже нет. - Миграции — отдельный шаг деплоя под advisory lock: одновременный старт подов иначе превращается в гонку за DDL-блокировки.
Заключение
Доступ к базе — это не «вызвать query», а управление ресурсом, который общий для всех запросов и всех реплик. Пул ограничивает параллелизм, параметры защищают синтаксис, транзакция удерживает инвариант на одном соединении, а таймауты не дают зависнуть ни клиенту, ни базе. Ошибки здесь почти всегда тихие: утёкшее соединение, открытая транзакция, лишние сто запросов — всё это выглядит как «сервис стал медленнее», а не как падение.
Практический минимум: один пул на процесс с посчитанным max, pool.on('error'), репозитории вместо SQL в контроллерах, withTransaction с release() в finally, statement_timeout и query_timeout, allowlist для динамического SQL, join или пакетная загрузка вместо N+1, миграции отдельным шагом. ORM можно добавить сверху, но она не отменяет ни одного из этих правил.
Дальше логично перейти к Redis и фоновым задачам: там те же вопросы про пул, таймауты и идемпотентность, но с другой моделью доставки.
Полезные ссылки
- node-postgres — документация
pg:Pool,Client, транзакции, типы - pg-pool — настройки пула и поведение очереди
- PostgreSQL: Error Codes — SQLSTATE и классы ошибок
- PostgreSQL:
SET TRANSACTION— уровни изоляции иset local - PostgreSQL: Advisory Locks — блокировки для миграций
- Prisma — схема,
include, миграции и$queryRaw - Drizzle ORM — relational queries и
sql - Kysely — типизированный query builder
- node-pg-migrate — миграции для чистого
pg - PgBouncer — режимы пулинга и ограничения
- Express и middleware — место репозитория в слоях приложения
- Конфигурация и валидация —
DATABASE_URLи проверка входа до запроса - Асинхронность в Node.js —
AsyncLocalStorageи контекст запроса - Логирование и наблюдаемость — readiness, метрики пула и трейсы запросов