Модуль Postgres: настоящая база в тесте

GenericContainer из второго урока умеет поднять что угодно, но про Postgres не знает ничего: образ, переменные POSTGRES_USER и POSTGRES_PASSWORD, проброс порта 5432, ожидание готовности — всё руками. Хуже того, готовность у этой базы хитрая: образ после первичной инициализации перезапускает сервер, и лог о готовности появляется дважды; наивное ожидание одного вхождения пропускает опасный момент, а ожидание только открытого порта ловит соединения с ещё не готовым сервером. Модуль закрывает это разом. Он выставляет переменные окружения по умолчанию, открывает порт 5432, стартует сервер с отключённым fsync ради скорости тестов и даёт готовую сборку ожиданий BasicWaitStrategies: двойной лог готовности плюс слушающий порт. Взамен вы получаете типизированный PostgresContainer — с методом DSN, снимками состояния и учтёнными именами базы и пользователя внутри, а не россыпью строк, которую вы собираете и синхронизируете сами в каждом пакете. Ничего магического здесь нет: внутри модуль пользуется теми же GenericContainer и кастомайзерами, но этот код написан и обкатан один раз в исходниках, а не в каждом вашем тесте.

Вход в модуль — функция postgres.Run(ctx, образ, opts ...testcontainers.ContainerCustomizer): тот же принцип кастомайзеров, что у ядра testcontainers, плюс собственные опции модуля. WithDatabase задаёт имя начальной базы, WithUsername и WithPassword — суперпользователя и его пароль; ничего не передали — получите postgres и postgres на всё. Схему и справочные данные кладут init-скриптами: WithInitScripts монтирует файлы в каталог /docker-entrypoint-initdb.d/, и entrypoint образа исполняет их при первой инициализации пустого каталога данных — в порядке сортировки имён. Когда порядок критичен — сначала схема, потом справочники, — берите WithOrderedInitScripts: она переименовывает файлы числовыми префиксами и исполняет строго в заданном вами порядке. Классическая пара — schema.sql со схемой и seed.sql со справочниками: страны, роли, тарифы — всё то, что тесты читают, но не меняют. Для нестандартной конфигурации сервера есть WithConfigFile: файл монтируется в /etc/postgresql.conf и передаётся серверу ключом config_file — лимиты соединений, локаль, всё, что обычно живёт в конфиге. Миграции внутрь init-скриптов или отдельным шагом теста — решать вам, но к первому соединению схема обязана уже существовать.

PostgresContainer.ConnectionString(ctx, args ...string) возвращает DSN вида postgres://пользователь:пароль@хост:порт/база?аргументы — хост и порт берутся из PortEndpoint по порту 5432/tcp, то есть из маппированного порта Docker. Выбирать порт руками не нужно и вредно: на занятой машине тест упадёт, а так Docker отдаёт свободный порт каждому контейнеру, и параллельные прогоны не дерутся. Дополнительные аргументы дописываются в query-строку: sslmode=disable, application_name=myapp. Контейнер по умолчанию не настроен на TLS, поэтому sslmode=disable задают явно: дефолты у драйверов разные — lib/pq требует шифрования, pgx предпочитает и откатывается, — и сюрпризы тут никому не нравятся. Аргументы склеиваются амперсандами, поэтому передать можно сколько нужно: connect_timeout=10 или application_name=myapp — формат тот же, что в query-строке на проде. Для фикстур есть MustConnectionString: паника вместо ошибки — удобно, когда старт уже проверен и ручная проверка ошибки только шумит. Подключайтесь чем угодно: pgx.Connect, database/sql с драйвером pgx — postgres тесты go проходят на честном SQL, а тонкости самого драйвера — тема отдельного курса pgx.

После миграций и справочных данных состояние базы хочется зафиксировать и откатывать. Для этого у контейнера есть методы Snapshot и Restore: Snapshot копирует текущую базу в базу-шаблон — по умолчанию она называется migrated_template, имя меняется опцией WithSnapshotName, — а Restore удаляет рабочую базу и пересоздаёт её из шаблона. Это дешевле, чем новый контейнер на каждый тест: восстановление — несколько SQL-команд, а не запуск ещё одного Postgres. На больших схемах снимок берут один раз на пакет и откатывают в каждом тесте: секунды на восстановление против минут на пересоздание с миграциями. Механика честная: под капотом sql.Open с драйвером, зарегистрированным в программе; по умолчанию это database/sql-драйвер postgres, но если приложение импортирует pgx, скажите об этом модулю через WithSQLDriver — лишний драйвер ради снимков тянуть не придётся. Одна ловушка из исходников: базу с именем postgres восстановить нельзя — Restore дропает рабочую базу, и системную трогать запрещено, модуль вернёт ошибку. К переиспользованию контейнера между запусками вернёмся в уроке 16 — там эта механика выстрелит в полную силу.

Первая грабля — долгий старт. Первый запуск тянет образ, делает initdb и перезапускает сервер; на холодной CI-машине это минуты. Короткий context.WithTimeout вокруг Run убьёт контейнер посреди инициализации — потолок ставят на весь прогон или не ставят вовсе, а образ кешируют. Без wait-стратегии Run вообще вернётся мгновенно: контейнер стартовал, но первые запросы упадут в отказ. Вторая грабля — sslmode. Без явного sslmode=disable драйвер пытается договориться о TLS, которого в контейнере нет, и тест падает загадочной ошибкой про отказ в соединении — ошибка всплывает не в Run, а на первом запросе, и выглядит как проблема базы, хотя дело в настройке соединения. Третья — init-скрипты. Права модуль берёт на себя: монтирует файлы с режимом 0755, и chmod на хосте не нужен. Ловятся на другом: скрипты исполняются только при первой инициализации пустого каталога данных — на переиспользуемом контейнере они молча пропустятся; сортировка по именам запустит seed.sql раньше schema.sql, если имена не продуманы; а сломанный скрипт валит entrypoint, и wait-стратегия честно истекает по дедлайну.