database/sql — это пул: ручки, арифметика размера и утечка rows.Close, которая его душит

Пул, который набирает лениво

sql.DB — не соединение. Это потокобезопасный пул соединений, который создают один раз и делят между всеми горутинами на всю жизнь процесса — один на базу, никогда не по одному на запрос. И он ленив:

db, err := sql.Open("pgx", dsn)
if err != nil {
	return err // сюда приходят только ошибки DSN/драйвера — ничего ещё не набрано
}
db.SetMaxOpenConns(25)                 // жёсткий потолок одновременных соединений
db.SetMaxIdleConns(25)                 // сколько переживает паузы между всплесками
db.SetConnMaxLifetime(5 * time.Minute) // ротация: переживает failover и перенацеливание LB
db.SetConnMaxIdleTime(2 * time.Minute) // ужать простаивающий пул без шторма редиалов

if err := db.PingContext(ctx); err != nil { // ПЕРВЫЙ настоящий дозвон происходит здесь
	return err // падаем быстро на старте, а не на первом запросе пользователя
}

Каждый запрос одалживает соединение у пула по одному и тому же пути: переиспользовать свободное, если есть; набрать новое, если пул ниже MaxOpenConns; иначе встать в очередь ожидания, пока кто-то не освободит. Каждая ручка существует потому, что её отсутствие — конкретная производственная авария:

• MaxOpenConns не задан — значит безлимит. Каждое соединение Postgres — это форкнутый backend-процесс, держащий несколько мегабайт ещё до полезной работы, а сверху work_mem (4 МБ по умолчанию) может выделяться на каждый узел сортировки или хеша. Всплеск трафика без потолка превращается в сотни backend-процессов, нехватку памяти на сервере и FATAL: sorry, too many clients already для всех остальных сервисов, делящих базу. Потолок переводит перегрузку в ограниченную очередь внутри вашего процесса, где с ней справится дедлайн контекста.
• MaxIdleConns слишком мал — а дефолт равен 2. При стабильной нагрузке в 25 одновременных запросов и 2 idle-слотах пул постоянно закрывает и заново набирает соединения: TCP плюс TLS плюс аутентификация — пара сетевых раундтрипов, миллисекунды поверх запросов, которые должны занимать сотни микросекунд, и видимая текучка в pg_stat_activity. Для стабильных сервисов idle ставят равным open.
• ConnMaxLifetime не задан — это история из крючка. Установленные соединения не перечитывают DNS, поэтому после failover или перенацеливания балансировщика они продолжают говорить со старым узлом, пока тот отвечает. Ограниченный lifetime гарантирует, что каждое соединение передоберётся за считаные минуты — заодно это перебалансирует нагрузку после масштабирования базы за прокси.
• ConnMaxIdleTime позволяет пулу, рассчитанному на дневной пик, ужаться за ночь, вместо того чтобы держать в заложниках восемьдесят серверных backend-процессов без дела.

Арифметика размера

Когда выставляешь размер пула в изоляции — «положим, 25 соединений на под» — ты даёшь обещание, которое придётся держать всему флоту. Бюджет общий на весь флот, и платит по нему база. Ограничение: поды × MaxOpenConns, плюс джобы миграций, кроны и коллеги с psql, должны умещаться в max_connections минус superuser_reserved_connections (по умолчанию 3). Postgres из коробки даёт max_connections = 100; у managed-провайдеров дефолт обычно пара сотен. Теперь прогоните сценарий всплеска: 30 подов с потолком 25 на каждом легитимно хотят 750 соединений против сервера на 200. Это не план мощностей, это самострел: каждый дозвон сверх серверного лимита падает с sorry, too many clients already, и ошибки случайным образом ложатся на все сервисы, делящие базу. Примерно после десяти подов делайте деление честно (200 минус резерв, делённое на 60 подов на максимуме HPA (Horizontal Pod Autoscaler), — это 3 соединения на под) — или признайте, что серверный пулер вроде PgBouncer стал инфраструктурой, а не оптимизацией.

Rows: утечка и полупрочитанный результат

Спроси себя: что держит соединение открытым между первой и последней строкой результата? Итератор *Rows — и каждый ранний выход без Close это соединение, которое пул никогда не получит обратно. Это самый распространённый способ, которым Go-сервисы исчерпывают пулы — по одному утёкшему итератору за раз:

rows, err := db.QueryContext(ctx, `SELECT id, email FROM users WHERE org_id = $1`, org)
if err != nil {
	return nil, err
}
defer rows.Close() // возвращает соединение в пул; без него ранний return утекает соединение

var users []User
for rows.Next() {
	var u User
	if err := rows.Scan(&u.ID, &u.Email); err != nil {
		return nil, err
	}
	users = append(users, u)
}
return users, rows.Err() // цикл завершается одинаково и при успехе, и при обрыве соединения

Утечка коварна: Next сам закрывает rows, когда итерация доходит до естественного конца, — поэтому код без defer rows.Close() проходит любой тест, читающий все строки. Добавьте один ранний return или break внутри цикла — и это соединение больше не вернётся. Ничего не падает; db.Stats().InUse просто прирастает на единицу, пока в один день пул не упрётся в MaxOpenConns и каждый запрос в процессе не повиснет навсегда — или до дедлайна контекста, если вы его дали. Пара defer rows.Close() плюс rows.Err() не обсуждается: цикл for rows.Next() завершается одинаково и когда результат кончился, и когда соединение умерло на полпути, и только rows.Err() скажет, получили вы всё или половину результата, которую собираетесь выдать за целое.

Три глагола делятся чисто. QueryRowContext — для чтения ровно одной строки: все ошибки он откладывает до Scan, где ноль строк приходит как sql.ErrNoRows (проверяйте через errors.Is; это результат, а не сбой). QueryContext — для наборов строк, с обязательствами Close/Err выше. ExecContext — для команд без результата, возвращает RowsAffected: UPDATE, не нашедший ни одной строки, ошибкой не является, и коду обычно нужно это заметить. Для nullable-колонок голый string уронит Scan: берите sql.NullString (явно, некрасиво, ищется грепом) или *string (тише, но в одном nil-чеке от паники) — работают оба, но выберите одну конвенцию на кодовую базу. И используйте Context-варианты везде: формы без контекста — доконтекстное наследие, а запрос без дедлайна держит соединение ровно столько, сколько вздумается медленному серверу.