Навигация

Доступ к базам данных в Node.js

Запрос пользователя почти всегда заканчивается обращением к базе, и именно там сервис чаще всего теряет время, соединения и данные. Ошибки доступа редко выглядят как падение: это медленный ответ, исчерпанный пул, повисшая транзакция или тихо продублированная строка. Разберём, как Node-сервис работает с PostgreSQL через pg: от пула соединений и параметризованных запросов до транзакций, N+1, ORM и миграций.

Содержание

  1. Где живёт доступ к данным
  2. Драйвер и пул соединений
  3. Размер пула и лимиты
  4. Параметризованные запросы
  5. Транзакции: один клиент на операцию
  6. Транзакция на весь запрос
  7. Ошибки драйвера и повтор
  8. Проблема N+1
  9. ORM как слой
  10. Миграции
  11. Таймауты и отмена
  12. Практика: TaskFlow
  13. Частые ошибки
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Где живёт доступ к данным

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ЗначениеЧто делать
23505unique_violation409 Conflict, поле — из constraint
23503foreign_key_violation422 или 409
23502not_null_violation422, но обычно это баг валидации
22P02invalid_text_representation422: значение не того типа
40001serialization_failureповторить транзакцию
40P01deadlock_detectedповторить транзакцию
57014query_canceledсработал statement_timeout
57P01admin_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
DrizzleSQL-подобный 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 и фоновым задачам: там те же вопросы про пул, таймауты и идемпотентность, но с другой моделью доставки.

Полезные ссылки