Аргументация выбора

• pgx нативно даёт бинарный протокол (меньше трафика и аллокаций), нативные типы PostgreSQL (jsonb, массивы, диапазоны, uuid без промежуточного []byte), CopyFrom, Batch, LISTEN/NOTIFY и типизированные ошибки pgconn.PgError с кодом и именем констрейнта.
• Цена: привязка к PostgreSQL и свой API - часть экосистемы (например, sqlmock) рассчитана на database/sql. Для меня это не проблема: интеграционные тесты я всё равно пишу на testcontainers с настоящей базой, а не на моках драйвера.
• sqlx разумно брать, если нужен стандартный интерфейс и переносимость: StructScan, Get, Select, sqlx.In закрывают 80 % боли database/sql почти без магии.
• GORM уместен там, где действительно много однотипного CRUD и мало сложных запросов. Проблемы: сгенерированный SQL непредсказуем и его надо логировать, Preload легко забыть и получить N+1, AutoMigrate на проде опасен (он не умеет откатываться и делает неожиданные ALTER).
• sqlc стоит упомянуть отдельно: SQL остаётся SQL-ом, но проверяется ещё при генерации и превращается в типизированные Go-функции. Это лучший из известных компромиссов между контролем и рутиной.

Почему дефолты плохие

• С MaxOpenConns = 0 при всплеске Go откроет столько соединений, сколько горутин пришло, упрётся в max_connections сервера и получит «FATAL: sorry, too many clients already». Причём упадёт не один этот сервис, а все, кто ходит в ту же базу, включая мониторинг.
• MaxIdleConns = 2 при MaxOpenConns = 50: как только нагрузка спадает, пул закрывает всё сверх двух, а на следующем всплеске снова устанавливает соединения - TCP + TLS + аутентификация, миллисекунды на каждое, и всё это в hot path. Симптом: MaxIdleClosed в DBStats растёт тысячами в минуту.

Как считать размер

1. Сверху: max_connections (обычно 100–200) минус резерв (superuser_reserved_connections, мониторинг, миграции, человек с psql), делить на число инстансов всех сервисов, ходящих в эту базу.
2. Снизу, по закону Литтла: нужное число = RPS × средняя длительность запроса. 400 RPS × 10 мс = 4 соединения на инстанс. Если получается 50, лечить надо длительность запросов.
3. Проверка здравого смысла: PostgreSQL хорошо работает, когда активных соединений порядка 2 × CPU. Сверх этого начинается деградация из-за конкуренции за LWLock и вытеснения кэшей, и пропускная способность падает, а не растёт.
4. MaxIdleConns = MaxOpenConns почти всегда подходит сервису под постоянной нагрузкой.
5. ConnMaxLifetime 30–60 минут обязателен, если между приложением и БД есть балансировщик, VIP или облачный прокси: без пересоздания соединения не переедут после failover и не перебалансируются.

Последовательность событий

1. Все MaxOpenConns соединений заняты.
2. Очередная горутина вызывает QueryContext и блокируется внутри database/sql в ожидании освобождения.
3. Растут WaitCount и WaitDuration.
4. Если у запроса есть context с таймаутом, по истечении вернётся context deadline exceeded. Если контекста нет, горутина будет ждать вечно.
5. Очередь растёт, горутины копятся, растёт потребление памяти, HTTP-хендлеры не отвечают, health-check падает, под перезапускается - и трафик уходит на соседние поды, которые падают следом. Каскад.

Типичные первопричины

• Забытый rows.Close() - соединение не возвращается в пул. Классика: return из середины цикла rows.Next() без defer rows.Close(). Симптом: InUse монотонно растёт до потолка, и всё залипает.
• Долгие транзакции: HTTP-вызов или запись в брокер внутри BeginTx/Commit. Соединение занято всё это время.
• Медленный запрос без индекса: 30 запросов по 2 секунды намертво выедают пул из 25.
• N+1 при росте страницы: 500 быстрых запросов вместо двух - и пул не справляется.
• Блокировки в БД: транзакции ждут друг друга, соединения заняты ожиданием.

Когда действительно нужен

• Много инстансов сервиса: 30 подов × 20 соединений = 600 при max_connections = 200.
• Kubernetes с автоскейлингом и serverless - число клиентов меняется на ходу, заранее поделить бюджет невозможно.
• Клиенты, которые не умеют пулить (короткоживущие процессы, cron-скрипты, PHP).
• Нужен единый шлюз для смены мастера при failover: приложения не переподключаются, pgbouncer переключает PAUSE/RESUME.

Почему ломаются prepared statements

PREPARE создаёт именованный план в конкретной серверной сессии. В transaction mode после COMMIT серверное соединение уходит другому клиенту, и следующий EXECUTE попадёт на другое соединение, где плана нет: «prepared statement "stmtcache_…" does not exist». Драйверы Go по умолчанию используют extended protocol с неявной подготовкой, поэтому проблема вылезает сразу, а не в экзотике.

Как обходят

• pgx: config.ConnConfig.DefaultQueryExecMode = pgx.QueryExecModeSimpleProtocol (или QueryExecModeExec) - параметры отправляются вместе с запросом, именованных планов не создаётся. Защита от инъекций сохраняется, но каждый запрос планируется заново.
• pgbouncer 1.21+ умеет отслеживать protocol-level prepared statements (max_prepared_statements > 0) и переигрывать Parse на новом серверном соединении - самое удобное современное решение.
• Два пути к БД: API-трафик через pgbouncer, а фоновые воркеры с длинными транзакциями, LISTEN/NOTIFY и advisory-локами ходят напрямую.

Что ещё ломается в transaction mode

• SET / SET LOCAL: сессионные настройки утекают чужому клиенту или теряются. SET LOCAL внутри транзакции безопасен.
• Temp-таблицы: создаются в сессии, следующей транзакции их не видно.
• LISTEN/NOTIFY живёт только в сессии.
• Advisory locks уровня сессии (pg_advisory_lock): могут «залипнуть» на чужом соединении. Использовать транзакционные pg_advisory_xact_lock.
• Курсоры WITH HOLD вне транзакции.

// Уязвимо
q := "SELECT id, email FROM users WHERE name = '" + name + "'"
// name = "' OR '1'='1"                 → отдаст всю таблицу
// name = "' UNION SELECT id, password_hash FROM admins --"  → утечка
// name = "'; UPDATE users SET is_admin = true WHERE email='me@x.y'; --"

// Закрыто
rows, err := db.QueryContext(ctx, `SELECT id, email FROM users WHERE name = $1`, name)

Почему параметризация действительно защищает

В extended query protocol PostgreSQL сообщение Parse несёт текст запроса с плейсхолдерами, а Bind - значения. Сервер уже построил дерево разбора к моменту, когда увидел значение; подставить в него новый оператор невозможно физически. Защищает разделение каналов, а не экранирование или фильтрация. Поэтому «я экранирую кавычки» заведомо проигрывает: есть многобайтные кодировки, есть числовые контексты без кавычек, есть комментарии.

Динамическая сортировка и имена объектов

// ORDER BY $1 синтаксически валиден, но означает «сортировать по константе».
// Работать как задумано не будет. А склейка открывает дыру, причём blind-типа:
// злоумышленник читает данные посимвольно через CASE в ORDER BY,
// даже не видя текста ошибок.

var allowed = map[string]string{
    "date_desc": "created_at DESC, id DESC",
    "date_asc":  "created_at ASC, id ASC",
    "name":      "name ASC",
}
order, ok := allowed[req.Sort]
if !ok { order = "created_at DESC, id DESC" }
q := fmt.Sprintf(`SELECT id, name FROM users ORDER BY %s LIMIT $1 OFFSET $2`, order)

// Динамическое имя схемы (мультитенантность): квотируем идентификатор
tbl := pgx.Identifier{tenantSchema, "orders"}.Sanitize()
q := fmt.Sprintf(`SELECT id FROM %s WHERE created_at > $1`, tbl)

func (r *Repo) Do(ctx context.Context) (err error) {
    tx, err := r.db.BeginTx(ctx, nil)
    if err != nil { return fmt.Errorf("begin: %w", err) }
    defer func() {
        if p := recover(); p != nil { _ = tx.Rollback(); panic(p) }
        if err != nil { _ = tx.Rollback() }     // err здесь именованный результат
    }()

    if _, err = tx.ExecContext(ctx, q1, a...); err != nil { return err }
    if _, err = tx.ExecContext(ctx, q2, b...); err != nil { return err }

    if err = tx.Commit(); err != nil { return fmt.Errorf("commit: %w", err) }
    return nil
}

// SAVEPOINT: когда часть работы допустимо потерять, не теряя всю транзакцию
if _, err := tx.ExecContext(ctx, "SAVEPOINT sp1"); err != nil { return err }
if _, err := tx.ExecContext(ctx, riskyQuery); err != nil {
    _, _ = tx.ExecContext(ctx, "ROLLBACK TO SAVEPOINT sp1")   // транзакция снова рабочая
} else {
    _, _ = tx.ExecContext(ctx, "RELEASE SAVEPOINT sp1")
}

Разбор деталей

• Именованный возврат (err error) остаётся единственным способом дать defer увидеть ошибку, с которой функция выходит. Без него откат придётся ставить на каждом return, и однажды его забудут.
• Rollback после Commit вернёт sql.ErrTxDone. Это нормально, ошибку явно игнорируем.
• recover в defer нужен, чтобы паника не оставила транзакцию открытой (соединение зависнет в состоянии idle in transaction до таймаута). После отката панику пробрасываем дальше - глотать её нельзя.
• Только tx. Случайный вызов r.db.Exec внутри транзакции уйдёт по другому соединению: изменения окажутся вне транзакции, а при неудаче ещё и заблокируются на строке, которую держит собственная транзакция. Такую самоблокировку диагностируют часами.
• Isolation. &sql.TxOptions{Isolation: sql.LevelRepeatableRead} - и не забыть, что на Repeatable Read и Serializable нужен ретрай при 40001 (serialization failure).

Почему это вообще проблема

Транзакция принадлежит сценарию (создать заказ, списать со склада, положить событие в outbox), а репозитории пишутся по одной сущности. Значит, границей транзакции управляет слой выше репозитория, а репозитории должны уметь работать как внутри неё, так и вне. Если этого не решить, получается либо репозиторий, который сам открывает транзакцию (и тогда атомарности между сущностями нет), либо tx в каждой сигнатуре.

Аргументы против tx в context

• По сигнатуре Insert(ctx, user) error невозможно понять, участвует ли вызов в транзакции. Код перестаёт читаться локально.
• WithinTx легко забыть, и код будет работать, просто без атомарности. Такой баг находят в проде.
• context по соглашению Go отвечает за отмену, дедлайны и request-scoped данные, а не за внедрение зависимостей. Это прямо написано в документации context.WithValue.
• Тесты сложнее: для репозитория «в транзакции» нужно собрать правильный контекст.
• Вложенность: если WithinTx вызвать внутри WithinTx, наивная реализация откроет вторую транзакцию на другом соединении и заблокируется сама на себе. Нужно уметь распознать существующую и сделать savepoint.

Что важно понимать

• Отмена ≠ откат. Прерванный UPDATE откатывается не потому, что его отменили, а потому что транзакция не была зафиксирована. Если автокоммит и оператор успел завершиться до прихода отмены, изменения останутся.
• Задержка. Тяжёлая сортировка, длинный COPY и ожидание блокировки реагируют на отмену каждое в свой момент. Некоторые операции (например, fsync при коммите) вообще не прерываются.
• Соединение считается грязным. Go после отмены обычно закрывает соединение, а не возвращает в пул: неизвестно, в каком оно состоянии. При массовых таймаутах это даёт шторм переподключений, который добивает базу - типичная вторая волна инцидента.
• Отмена HTTP-запроса пользователем тоже отменяет контекст, а с ним и запрос в БД. Это хорошо для чтения и опасно для записи: сценарий «пользователь нажал Escape в середине оформления заказа» должен работать предсказуемо, поэтому для записи часто берут context.WithoutCancel (Go 1.21+) или отдельный контекст с собственным таймаутом.

rows, err := db.QueryContext(ctx, q, args...)
if err != nil { return nil, err }
defer rows.Close()          // (1) обязательно и сразу

var out []User
for rows.Next() {
    var u User
    if err := rows.Scan(&u.ID, &u.Name); err != nil { return nil, err }
    out = append(out, u)
}
if err := rows.Err(); err != nil {   // (2) обязательно после цикла
    return nil, fmt.Errorf("iterate rows: %w", err)
}
return out, nil

Детали, которые проверяют

• rows.Next() возвращает false в двух разных случаях: строки закончились или произошла ошибка (обрыв сети, серверная ошибка в середине выдачи, истёкший контекст, отвалившаяся реплика). Различить их можно только через rows.Err().
• Next(), дойдя до конца, сам вызывает Close(). Но при раннем return из цикла этого не произойдёт, поэтому defer rows.Close() нужен всегда.
• Повторный Close() безопасен, он идемпотентен.
• QueryRow не требует Close: Scan закрывает набор сам. Но именно поэтому QueryRow нельзя «отложить» - ошибка запроса приезжает только в Scan.
• Nested query trap: открыть rows и внутри цикла делать другой запрос через тот же *sql.DB значит занять два соединения на горутину одновременно. При пуле в 25 и 25 параллельных обработчиках получается дедлок на пуле: все держат по одному соединению и ждут второго. Лечится так: сначала вычитать результат в память, потом делать вложенные запросы (а обычно вложенный запрос вообще не нужен - это N+1).
• В pgx rows.Close() ничего не возвращает, а ошибку отдаёт rows.Err(); сегодня проще взять pgx.CollectRows с RowToStructByName, он сделает всё правильно за тебя.

Практический подход

• В слое репозитория живут sql.Null* или pgtype.*, в доменной модели - указатели или отдельное значение по умолчанию. Конвертирует маппер, и домен про SQL не знает.
• Часто чище всего убрать NULL в запросе: SELECT coalesce(middle_name, '') FROM users. Годится, когда пустая строка и NULL семантически неразличимы. Не годится, когда различимы: NULL «телефон не указан» и пустая строка «указан пустым» означают разные факты.
• Ещё лучше не заводить NULL в схеме там, где он не несёт смысла: NOT NULL DEFAULT ''. Каждый nullable-столбец навсегда добавляет ветвление в код.
• Помнить про агрегаты: sum() по пустому набору вернёт NULL, а не 0. Классический баг: SELECT sum(amount) FROM orders WHERE ... с приёмником int64 падает, когда заказов не нашлось. Лечится coalesce(sum(amount), 0).

// domain
var ErrNotFound = errors.New("not found")

// repository
func (r *Repo) GetUser(ctx context.Context, id int64) (*User, error) {
    var u User
    err := r.db.QueryRowContext(ctx,
        `SELECT id, email FROM users WHERE id = $1`, id).Scan(&u.ID, &u.Email)
    switch {
    case errors.Is(err, sql.ErrNoRows):       // pgx: errors.Is(err, pgx.ErrNoRows)
        return nil, fmt.Errorf("user %d: %w", id, domain.ErrNotFound)
    case err != nil:
        return nil, fmt.Errorf("get user %d: %w", id, err)
    }
    return &u, nil
}

// transport
if errors.Is(err, domain.ErrNotFound) {
    http.Error(w, "not found", http.StatusNotFound)
    return
}

Почему именно так

• Слои не должны знать про драйвер. Если хендлер проверяет sql.ErrNoRows, то при замене database/sql на pgx или переезде в другое хранилище придётся править транспорт.
• 404 против 500. Проброшенная как есть ошибка почти всегда превращается в 500 и в алерт, хотя ничего нештатного в «пользователь не найден» нет.
• errors.Is, а не ==. Ошибка почти всегда обёрнута через %w; сравнение на равенство перестанет работать при первом же добавлении контекста.
• У pgx своя pgx.ErrNoRows. С pgx v5.7 она оборачивает sql.ErrNoRows, и errors.Is(err, sql.ErrNoRows) срабатывает и на неё, а в pgx v4 и ранних v5 это разные ошибки - типичная ловушка при миграции с lib/pq.
• Не для всех случаев это ошибка. Для «есть ли такой email» правильнее вернуть (bool, error) или (*User, error) с nil, nil, чем заставлять вызывающего ловить ошибку ради нормального ответа. Ошибка уместна там, где отсутствие записи действительно нарушает ожидания.

Что важно знать про инструменты

• goose: файлы с секциями -- +goose Up / -- +goose Down; поддерживает Go-миграции для сложной логики; есть -- +goose NO TRANSACTION - обязательно для CREATE INDEX CONCURRENTLY, который не работает внутри транзакции.
• golang-migrate: пары файлов *.up.sql / *.down.sql; понятие dirty state - если миграция упала посередине, база помечается грязной и дальнейшие запуски отказываются работать до force.
• Каждая миграция по умолчанию выполняется в транзакции. В PostgreSQL DDL транзакционен, и это большое преимущество: неудачная миграция откатывается целиком. Исключения - CREATE INDEX CONCURRENTLY, ALTER TYPE ... ADD VALUE (до PG 12), VACUUM.

Конфликты версий и как их гасить

• Одинаковые номера из двух веток лечатся переходом на timestamp-именование.
• Порядок при мерже. Даже с timestamp бывает так: ветку с более ранним timestamp смёржили позже. На проде она применится, а у разработчика, у которого более поздняя версия уже записана, - нет. goose умеет -allow-missing, у migrate этого нет; универсальное решение - перед мержем переименовать миграцию, чтобы она стала последней.
• Гонка при старте. Десять подов одновременно запускают миграции. Правильно - отдельная джоба или шаг деплоя, которые запускаются один раз; init-контейнер не годится, он стартует в каждом поде. golang-migrate берёт advisory lock сам, goose - только если его явно включить (WithSessionLocker в Provider API), и осознанно полагаться на это не стоит.
• Долгая миграция блокирует деплой. Тяжёлый backfill выносится из миграции в отдельную фоновую задачу, миграция остаётся быстрой и только меняет схему.
• Ревью миграций обязательно. Отдельным глазом смотреть на любой ALTER, на отсутствующий CONCURRENTLY и на lock_timeout.

-- Шаг 1 (мгновенно): nullable-колонка меняет только системный каталог
ALTER TABLE users ADD COLUMN phone text;

-- Шаг 2: релиз кода, который пишет phone. Старая версия кода тоже работает.

-- Шаг 3: backfill батчами, а не одним UPDATE
UPDATE users SET phone = derive(...)
WHERE phone IS NULL AND id BETWEEN $1 AND $2;   -- по 10k, с паузой, следя за lag

-- Шаг 4: NOT NULL без ACCESS EXCLUSIVE на весь скан
ALTER TABLE users ADD CONSTRAINT users_phone_nn CHECK (phone IS NOT NULL) NOT VALID;
ALTER TABLE users VALIDATE CONSTRAINT users_phone_nn;   -- SHARE UPDATE EXCLUSIVE
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;      -- мгновенно (PG 12+)
ALTER TABLE users DROP CONSTRAINT users_phone_nn;       -- опционально

-- Индекс
CREATE INDEX CONCURRENTLY users_phone_idx ON users (phone);
SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;  -- проверить успех

Что именно ломается при «прямом» подходе

• ADD COLUMN ... NOT NULL DEFAULT 'x' до PostgreSQL 11 переписывал всю таблицу под ACCESS EXCLUSIVE. С PG 11 значение по умолчанию хранится в каталоге и операция мгновенна, но знать историю надо: на PG 10 это десятки минут простоя.
• ALTER COLUMN ... SET NOT NULL напрямую запускает полный скан таблицы под ACCESS EXCLUSIVE, который блокирует даже SELECT.
• CREATE INDEX без CONCURRENTLY блокирует запись на всё время построения.
• Очередь блокировок. Самое коварное: ALTER, ожидающий ACCESS EXCLUSIVE, встаёт в очередь за долгим SELECT, а все запросы, пришедшие после него, встают уже за ним. Одна миграция при одном долгом отчёте кладёт весь сервис. Лечится SET lock_timeout = '3s' и ретраями.