Строка подключения и DSN

Формат — URL: postgres://user:password@host:port/dbname?param=value. Разберём по частям. user и password — креденшалы; если пароля нет, часть с двоеточием просто опускается. host — имя хоста, IP или путь к Unix-сокету, если начинается со слэша: localhost для локальной базы, доменное имя для облака. port — по умолчанию 5432, и это чуть ли не единственное поле, которое можно смело опускать; IPv6-адреса пишутся в квадратных скобках, как в любом URL. У user тоже есть дефолт — имя пользователя операционной системы: подключение без user иногда падает с неожиданным role does not exist, потому что pgx подставил вашего системного пользователя, а такой роли в базе нет. dbname — имя базы; если его не указать, сервер попробует базу с именем пользователя, и новичок ловит ошибку database app does not exist, потому что назвал базу как пользователя. После вопросительного знака живут параметры: sslmode, connect_timeout, application_name и параметры пула. pgx понимает и второй формат — пары key=value в стиле libpq: host=localhost user=app password=secret dbname=app. Оба формата принимают pgx.Connect, pgxpool.New и pgx.ParseConfig; выбирайте один на проект и не смешивайте — половина путаницы в чужом коде растёт из того, что человек читает URL, а пишет key=value. Отдельная приятность: pgx принимает несколько хостов через запятую — host=primary,replica — и при недоступности первого пробует второй; для чтения с резервной реплики это готовый механизм без внешних балансировщиков.

Режимов шесть, но решение сводится к одному вопросу: насколько вы параноик по поводу канала между приложением и базой. disable — чистый TCP без шифрования: годится, когда соединение не покидает машину или идёт внутри доверенной приватной сети. allow и prefer — полумеры: prefer, дефолтный режим, пытается шифровать, а при неудаче тихо откатывается к открытому каналу; именно эта гибкость мешает поймать ошибку конфигурации на стейджинге — всё выглядит работающим, пока в трафик не заглянет кто-то чужой. require — шифрует обязательно, но не проверяет сертификат: канал защищён от подглядывания, а вот посредник с любым валидным сертификатом перехватит соединение незаметно. Для verify-full сертификат сервера должен подписываться доверенным CA, либо путь к корневому сертификату передаётся параметром sslrootcert — в облаках его обычно скачивают вместе с креденшалами. verify-ca добавляет проверку цепочки сертификатов, verify-full — ещё и сверку имени хоста, и это единственный режим, который действительно стоит против man-in-the-middle. Моя конвенция простая: локально disable, на проде verify-full и никаких prefer в продовых DSN — тихий откат к открытому каналу это не надёжность, а её имитация. Промежуточный вариант для внутреннего контура — verify-ca с собственным корневым сертификатом: канал шифруется, цепочка проверяется, а сверка имени хоста остаётся на совести доверенной сети. Если облачный провайдер подписал сертификат на внутреннее имя и verify-full ругается, честное решение — sslrootcert с его CA, а не откат к require. Проверить фактический режим легко: в pg_stat_ssl видно, шифруется ли каждое соединение, — без этой проверки require в конфиге остаётся благим пожеланием.

pgx читает переменные окружения по конвенции libpq — так называют набор настроек, который поддерживают официальные клиенты Postgres на всех языках. PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGSSLMODE, PGAPPNAME — полный список живёт в документации PostgreSQL, а имена стабильны годами, потому что их читают десятки утилит, не только pgx. Механика такая: любой параметр, который явно не указан в строке, pgx берёт из окружения, а если и там пусто — применяет дефолт. Пустая строка в качестве DSN — легальный способ сказать «всё из env»: так собраны многие двенадцатифакторные сервисы, где код приложения вообще не знает, где живёт база. Приоритет важный: явный параметр в строке бьёт переменную окружения, поэтому фрагмент ?sslmode=disable в DSN перебьёт PGSSLMODE=verify-full — и это источник незаметных багов при переносе конфигов между средами. Отладить приоритет легко: соберите конфиг через pgx.ParseConfig и напечатайте итоговые поля — сразу видно, что приехало из переменных окружения, а что из дефолтов. В Kubernetes и docker-compose переменные задаются в манифесте, и один и тот же образ работает в dev и prod без пересборки. Одна оговорка: PGPASSWORD удобна для локальных скриптов, но пароль в окружении виден в выводе ps и дампах /proc — прод-секреты живут в секрет-менеджерах и короткоживущих токенах, а не в открытом env.

Рабочий приём, который я копирую из проекта в проект: приложение читает переменные окружения с дефолтами и собирает строку подключения при старте. os.Getenv для хоста, порта и имени базы, при пустом значении — дефолт для локальной разработки; пароль — без дефолта, его отсутствие падает явно. Дальше два пути: собрать строку через fmt.Sprintf или сконструировать url.URL и не думать об экранировании. Второй путь надёжнее: спецсимволы в пароле — классика, из-за которой подключение падает на сервере, работая на ноутбуке. Обязательный шаг — валидация: pgx.ParseConfig возвращает ошибку для битой строки, и вызывать его на старте стоит всегда — это дешёвый fail fast: сервис упадёт через секунду после запуска с понятным текстом, а не через час после деплоя с загадочным таймаутом. Код урока, как и весь курс, исполняется локально: песочница сайта не умеет сеть и Postgres — вам понадобится Go и контейнер из второго урока. Собранная в переменной DATABASE_URL, строка подключения поедет и в миграции, и в тесты — одна конфигурация на весь проект. В docker-compose она передаётся через environment, в Kubernetes — через ConfigMap и Secret: один и тот же бинарник меняет среду без пересборки, меняются только значения окружения.

У pgxpool нет отдельной строки подключения — пул принимает тот же DSN, и его параметры живут после вопросительного знака: pool_max_conns, pool_min_conns, pool_max_conn_lifetime, pool_max_conn_idle_time, pool_health_check_period. Синтаксис единый, читается одна строка — удобно, когда конфигурация хранится в одной переменной окружения DATABASE_URL и раздаётся всему приложению. Подробная настройка лимитов, жизненный цикл коннектов и расчёт под max_connections сервера — тема четвёртого урока; пока достаточно знать, что такие параметры существуют и работают без отдельного кода конфигурации.