Модуль 12 ⏱ ~33 мин чтения 📐 2 Mermaid диаграмм

1. Работа с БД в Go. database/sql

Архитектура database/sql, жизненный цикл соединений и Mechanical Sympathy

Введение: Почему database/sql — это фундамент

Пакет database/sql — это не просто обертка над драйверами баз данных. Это продуманная до мелочей абстракция, которая предоставляет унифицированный интерфейс для работы с реляционными СУБД, скрывая за собой сложную механику управления соединениями, пуллинга, транзакций и обработки ошибок.

Для бэкенд-инженера уровня Senior/Lead понимание того, как работает database/sql «под капотом», критически важно. Не зная внутренней механики, легко допустить утечку соединений, создать скрытый бутылнек в конкурентном коде или неправильно настроить таймауты, что в продакшене выльется в connection pool exhausted и падение сервиса под нагрузкой.

В этой статье мы разберем:

Архитектуру пакета database/sql и его взаимодействие с драйверами через интерфейс driver.Connector.
Внутреннее устройство пула соединений: как работают счетчики, каналы и синхронизация.
Жизненный цикл запроса: от вызова db.QueryContext до системного вызова read/write в сокете.
Идиоматические паттерны работы с rows, транзакциями и подготовленными выражениями.
Влияние на производительность: аллокации, Escape Analysis и взаимодействие с GC.

Архитектура: Интерфейсы и реализация

Ключевой принцип работы пакета — разделение ответственности. Ваша бизнес-логика работает с высокоуровневыми типами *sql.DB, *sql.Tx, *sql.Rows, в то время как драйвер работает с низкоуровневыми примитивами.

flowchart LR
    App["Ваш код (Business Logic)"] --> DB["*sql.DB (Pool Manager)"]
    DB --> Runtime["sql/driver Interfaces"]
    Runtime --> Driver["Драйвер (pgx / mysql)"]
    Driver --> Net["Network / Syscalls"]
    Net --> DBServer["PostgreSQL / MySQL"]

    classDef default fill:#1e293b,stroke:#334155,color:#f8fafc;
    classDef pool fill:#312e81,stroke:#6366f1,color:#ffffff;
    class DB pool;

Роль *sql.DB

Тип *sql.DB — это не одно соединение с базой данных. Это абстракция пула соединений (pool of connections). Она потокобезопасна и предназначена для длительного использования в течение всего времени жизни приложения.

Ловушка / Gotcha

Никогда не создавайте *sql.DB внутри обработчика запроса или функции.

// ❌ НЕПРАВИЛЬНО: Утечка ресурсов, отсутствие пуллинга
func handler(w http.ResponseWriter, r *http.Request) {
    db, err := sql.Open("postgres", dsn)
    // ...
}

sql.Open не устанавливает физическое соединение сразу, но создает объект, который начинает управлять ресурсами. Многократный вызов приведет к быстрому исчерпанию файловых дескрипторов и портов ОС.
Правильный подход: Создайте *sql.DB один раз при старте приложения (например, в main или через DI-контейнер) и передавайте ссылку на неё туда, где она нужна.

Инициализация и драйверы

Для регистрации драйвера используется механизм init() и глобальный реестр в database/sql.

package main

import (
    "database/sql"
    "log"
    "time"

    _ "github.com/jackc/pgx/v5/stdlib" // Side-effect import для регистрации драйвера
)

func main() {
    // При старте приложения
    db, err := sql.Open("pgx", "postgres://user:pass@localhost:5432/dbname")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // Настройка пула ОБЯЗАТЕЛЬНА для продакшена
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(5)
    db.SetConnMaxLifetime(5 * time.Minute)
}

Собеседование

Вопрос: Что делает sql.Open? Устанавливает ли он соединение с БД?
Ответ: Нет, sql.Open только валидирует аргументы и инициализирует структуру *sql.DB (пустой пул). Физическое соединение (TCP handshake, auth) происходит лениво (lazy), при первом вызове метода, требующего доступа к БД (например, Ping, Query). Именно поэтому ошибки сети или авторизации часто «всплывают» не при старте, а уже во время работы. Для явной проверки доступности БД сразу после старта нужно вызвать db.Ping() или db.PingContext().

Внутреннее устройство пула соединений

Понимание механики пула — это ключ к настройке производительности. Пул в database/sql — это сложная структура, управляющая состоянием множества горутин и сетевых соединений.

Состояния соединения (connState)

Каждое физическое соединение (driver.Conn) в пуле может находиться в одном из состояний:

idle: Свободно, ожидает запроса в пуле.
inUse: Выдано горутине для выполнения запроса.
closed: Закрыто (ошибка или таймаут), ожидает удаления.

Под капотом

Внутри *sql.DB используется структура db.connOpener — отдельная горутина, которая асинхронно создает новые соединения, если пул пуст и лимиты не достигнуты. Это позволяет не блокировать вызывающую горутину на этапе dial (установки соединения), если есть свободные idle соединения.

Синхронизация доступа к пулу осуществляется через мьютексы и атомарные счетчики. В современных версиях Go (1.11+) используется оптимистичная блокировка для повышения конкурентности при выдаче соединений.

Стратегия выдачи соединений

Когда вы вызываете db.QueryContext, происходит следующее:

Проверка idle: Если в пуле есть свободное соединение, оно помечается как inUse и выдается вам.
Создание нового: Если idle пусты, но open < maxOpen, запускается создание нового (или оно берется из кэша созданных).
Ожидание: Если лимит maxOpen достигнут, горутина блокируется (через канал db.openerCh или аналогичный механизм ожидания), пока другое соединение не вернется в пул.

flowchart TD
    Start["Запрос: QueryContext"] --> CheckIdle{"Есть idle соединения?"}
    CheckIdle -- "Да" --> MarkInUse["Пометить InUse"]
    CheckIdle -- "Нет" --> CheckLimit{"Open < MaxOpen?"}
    CheckLimit -- "Да" --> CreateNew["Создать новое (dial)"]
    CheckLimit -- "Нет" --> WaitPool["Блокировка: ожидание в пуле"]
    CreateNew --> MarkInUse
    WaitPool --> MarkInUse
    MarkInUse --> DriverExec["Вызов driver.Conn.Query"]

    classDef default fill:#1e293b,stroke:#334155,color:#f8fafc;
    classDef wait fill:#312e81,stroke:#6366f1,color:#ffffff;
    class WaitPool wait;

Жизненный цикл запроса: От кода до Syscall

Разберем путь данных при выполнении простого SELECT. Это важно для понимания задержек (latency) и накладных расходов.

1. Подготовка и Контекст

Всегда используйте Context. Это стандарт де-факто для управления временем жизни запроса и отмены операций.

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

rows, err := db.QueryContext(ctx, "SELECT id, name FROM users WHERE active = $1", true)
if err != nil {
    // Обработка ошибки на уровне запроса
    return err
}
// rows.Close() обязателен! (см. ниже)

2. Чтение данных и итерация

defer rows.Close() // <--- КРИТИЧЕСКИ ВАЖНО

for rows.Next() {
    var id int
    var name string
    if err := rows.Scan(&id, &name); err != nil {
        return err
    }
    // Обработка строки
}
// Проверка ошибки после завершения итерации
if err := rows.Err(); err != nil {
    return err
}

3. Сканирование и аллокации (Escape Analysis)

Метод rows.Scan принимает указатели &var. Почему? Потому что драйвер должен записать данные, полученные из сети, в вашу память.

Под капотом: Escape Analysis

Когда вы передаете &name (где name — локальная переменная) в rows.Scan, компилятор видит, что ссылка на эту переменную "убегает" (escapes) за пределы текущей функции/стека, так как драйвер (находящийся в другом пакете) сохраняет этот указатель или работает с ним.
В результате переменная name аллоцируется не на стеке, а в куче (heap).

Последствие: При сканировании миллионов строк в цикле вы можете создать огромное давление на Garbage Collector, так как каждая итерация создает новые объекты в куче.
Оптимизация: Для высоконагруженных SELECT без сложной логики иногда эффективнее сканировать в переиспользуемые буферы или использовать специализированные методы драйверов (например, pgx.CopyFrom для вставки или низкоуровневый режим pgx.Rows для чтения), которые минимизируют аллокации.

Транзакции: Управление состоянием

Транзакция в database/sql привязывается к одному конкретному физическому соединению на все время своей жизни.

tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
if err != nil {
    return err
}
// Важно: если случится паника или ошибка, транзакция должна быть отменена
defer func() {
    if p := recover(); p != nil {
        tx.Rollback()
        panic(p)
    } else if err != nil {
        tx.Rollback()
    }
}()

_, err = tx.ExecContext(ctx, "UPDATE accounts SET balance = balance - 100 WHERE id = $1", 1)
if err != nil {
    return err // defer выполнит Rollback
}

_, err = tx.ExecContext(ctx, "UPDATE accounts SET balance = balance + 100 WHERE id = $2", 2)
if err != nil {
    return err
}

err = tx.Commit() // Фиксация изменений

Ловушка / Gotcha

Долгие транзакции блокируют соединения
Поскольку *sql.Tx удерживает одно физическое соединение (driver.Conn), это соединение не может быть использовано для других запросов, пока транзакция не завершится (Commit/Rollback).
Если вы начнете транзакцию, а затем сделаете долгий внешний HTTP-запрос или сложную вычислительную операцию до коммита, вы фактически "выбиваете" одно соединение из пула на все это время. При высокой конкурентности это приведет к тому, что пул быстро исчерпается, даже если сами запросы к БД быстрые.
Правило: Держите транзакции максимально короткими. Вся подготовка данных должна идти до BeginTx, а обработка результатов — после Commit.

Prepared Statements: Переиспользование планов

Подготовленные выражения (Prepare) полезны для безопасности (защита от SQL Injection) и производительности (БД парсит и планирует запрос один раз).

stmt, err := db.PrepareContext(ctx, "SELECT name FROM users WHERE id = $1")
if err != nil {
    return err
}
defer stmt.Close() // Освобождение ресурсов на стороне БД и клиента

var name string
err = stmt.QueryRowContext(ctx, 123).Scan(&name)

Под капотом

В некоторых драйверах (например, старый lib/pq) подготовленные выражения хранились на стороне сервера (server-side prepared statements). Это требовало отправки специальных сообщений протокола и занимало память в pg_catalog PostgreSQL.
В современных драйверах (например, pgx) по умолчанию часто используется режим "описания запроса" (describe) или эмуляция подготовленных выражений на клиенте, если это эффективнее.

Важно: Не забывайте stmt.Close(). Если вы создаете подготовленное выражение внутри цикла или частого хендлера и не закрываете его, вы можете исчерпать лимит серверных ресурсов (например, max_prepared_stmt_count в MySQL).

Обработка ошибок: Идиоматический подход

В Go ошибки — это значения. В контексте БД важно различать типы ошибок.

package main

import (
    "context"
    "database/sql"
    "errors"
    "fmt"

    "github.com/jackc/pgx/v5/pgconn"
)

var (
    ErrUserNotFound = errors.New("пользователь не найден")
    ErrDuplicate    = errors.New("дубликат записи")
)

type User struct {
    Name string
}

func GetUser(ctx context.Context, db *sql.DB, id int) (*User, error) {
    var u User
    err := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id=$1", id).Scan(&u.Name)

    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            // Логика "не найдено"
            return nil, ErrUserNotFound
        }
        // Проверка на ошибки драйвера (например, нарушение уникальности)
        var pgErr *pgconn.PgError
        if errors.As(err, &pgErr) {
            if pgErr.Code == "23505" { // unique_violation
                return nil, ErrDuplicate
            }
        }
        // Любая другая ошибка — логгируем и прокидываем выше
        return nil, fmt.Errorf("db query failed: %w", err)
    }
    return &u, nil
}

Производительность: Тюнинг и Mechanical Sympathy

Настройка пула (Tuning)

Параметры по умолчанию (0 — безлимит) опасны для продакшена.

// Пример для сервиса с умеренной нагрузкой
db.SetMaxOpenConns(50)                  // Максимум одновременных соединений с БД
db.SetMaxIdleConns(10)                  // Сколько держать "теплыми" в простое
db.SetConnMaxLifetime(30 * time.Minute) // Чтобы убивать старые коннекты (важно для балансировщиков)
db.SetConnMaxIdleTime(10 * time.Minute) // Как долго держать idle соединение

Под капотом: Почему ConnMaxLifetime важен?

Если ваше приложение работает за облачным прокси (например, AWS RDS Proxy или Cloud SQL Proxy) или балансировщиком, старые соединения могут быть невалидны с точки зрения инфраструктуры, даже если приложение этого не знает. Установка ConnMaxLifetime гарантирует, что приложение будет периодически "ротировать" соединения, устанавливая новые, что предотвращает ошибки broken pipe или connection reset при долгой работе.

Влияние на GC и аллокации

Каждый вызов Query и Scan создает аллокации:

Слайс аргументов []driver.NamedValue.
Буферы для чтения из сети.
Объекты строк при сканировании.

Совет: Используйте rows.ColumnTypes() для предсказуемого выделения памяти под сканирование, если вы знаете схему заранее и работаете в очень высоконагруженном контуре (хотя обычно это излишняя оптимизация).

Сравнение: database/sql vs ORM (GORM, sqlc)

Характеристика	database/sql (Raw SQL)	ORM (GORM, XORM)	Codegen (sqlc)
Контроль	Полный контроль над каждым байтом запроса	Абстракция, возможны "магические" запросы	Полный контроль, типобезопасность
Производительность	Максимальная (нет оверхеда рефлексии)	Ниже (reflection, лишние аллокации)	Максимальная (как raw)
Поддержка	Стандартная библиотека	Сторонние библиотеки	Генерация кода
Сложность	Высокая (ручной маппинг)	Низкая (быстрый старт)	Средняя (нужен билд-степ)

Собеседование

Вопрос: Когда стоит использовать ORM, а когда database/sql?
Ответ: Для сложных аналитических запросов, высоконагруженных систем или миграции легаси лучше использовать database/sql или sqlc, чтобы явно видеть и контролировать генерируемый SQL. ORM удобен для типичных CRUD-операций в стартапах или внутренних инструментах, где скорость разработки важнее микро-оптимизаций. Однако опытный инженер должен уметь писать чистый и безопасный код на database/sql, так как это фундамент, на котором строятся все остальные абстракции.

Чеклист: Готовность к продакшену

[ ] Используется context.Context во всех методах БД.
[ ] *sql.DB создается один раз и передается через зависимости.
[ ] Настроены лимиты пула (SetMaxOpenConns и др.).
[ ] Все rows.Close() и tx.Rollback() вызываются через defer.
[ ] Ошибки ErrNoRows обрабатываются явно.
[ ] Таймауты настроены и на уровне приложения (context), и на уровне драйвера/БД, если нужно.
[ ] Используются подготовленные выражения для часто повторяющихся запросов.

Итог

Пакет database/sql предоставляет мощный и гибкий инструмент, но он требует уважения к своей механике. Понимание того, как управляются соединения, как контекст прерывает выполнение и как происходят аллокации памяти, отличает разработчика, который просто "пишет запросы", от инженера, способного построить надежную и масштабируемую систему хранения данных.

В следующей статье мы углубимся в тему, которую лишь затронули здесь: детально разберем, как именно работает механизм пуллинга, какие стратегии существуют для управления idle и inUse соединениями, и как диагностировать проблемы с пулом с помощью метрик. Читайте далее: 2. Connection pool.