Типы Postgres: UUID, TIMESTAMPTZ, NUMERIC

Пакет pgtype — это набор обёрток и кодеков: для каждой колонки Postgres есть понимание, какие байты по протоколу во что превращать в обе стороны. Обёртки устроены однотипно: значение плюс поле Valid из шестого урока — UUID{Bytes, Valid}, Timestamptz{Time, Valid}, Numeric{Int, Exp, Valid}, Text{String, Valid}. Простые случаи в обёртках не нуждаются: text сканируется в string, bigint — в int64, bool — в bool, date и timestamptz — в time.Time, и это самый частый путь в прикладном коде. Обёртка нужна тогда, когда у колонки есть второе состояние или точность, которую базовый тип Go не выдержит: NULL, бесконечность, произвольный масштаб числа. Все pgtype-типы реализуют и sql.Scanner, и driver.Valuer, поэтому работают и через адаптер stdlib из девятого урока — там, правда, без адаптера NewMap().SQLScanner не обойтись. Отдельная суперспособность pgtype — кодеки для сложных типов: массивы, JSONB, диапазоны, составные типы, — но это темы одиннадцатого и двенадцатого уроков; здесь держимся тройки UUID, TIMESTAMPTZ, NUMERIC и правил выбора между простым типом Go и обёрткой.

pgtype.UUID — это структура с массивом Bytes [16]byte и флагом Valid. Колонка uuid в Postgres хранит те же 16 байт, и приёмник-обёртка делает сравнение и запись тривиальными: никаких разговоров о дифисах и регистре — байты либо равны, либо нет. Строка тоже работает: Scan в обычный string вернёт UUID в стандартной форме с дифисами и строчными буквами — у pgtype.UUID для этого есть и метод String(), появившийся в 5.7, — а INSERT со строкой-значением сервер сам превратит в байты: для прототипов этого хватает. Единственная ловушка строковой формы — регистр: сервер хранит и отдаёт байты, но до превращения в них две строки с заглавными и строчными буквами в Go не равны — та самая история из начала урока. Два практических источника UUID. Серверный: колонка с DEFAULT gen_random_uuid(), встроенным в Postgres с тринадцатой версии, — идентификатор рождается в базе вместе со строкой и приезжает через RETURNING. Клиентский: пакет github.com/google/uuid генерирует uuid.New() до вставки, что удобно для распределённых систем — объект знает свой id ещё до записи. Конвертация между библиотеками — одна строка в обе стороны: uuid.UUID — это тот же [16]byte, поэтому pgtype.UUID{Bytes: gID, Valid: true} едет в базу, а pgtype.UUID обратно — через uuid.UUID(pgID.Bytes). Копирование массива здесь по значению, никаких аллокаций, — и это главный аргумент против хранения UUID строками везде, кроме границы API, где строка удобна пользователю.

Колонка timestamptz хранит момент времени — микросекунды относительно UTC, — а при чтении сервер предъявляет его в таймзоне сессии. В Go простым приёмником служит time.Time: конечные значения сканируются напрямую, и это ещё один случай, когда обёртка не нужна. Чего time.Time не выдерживает, так это трёх исключений. Первое — NULL: без обёртки это знакомая ошибка сканирования. Второе — значения infinity и -infinity, легальные в Postgres: у бессрочной подписки expired_at может быть infinity, и попытка сканировать его в time.Time принесёт ошибку cannot scan Infinity into *time.Time — обёртка pgtype.Timestamptz возвращает такое значение через поле InfinityModifier. Третье — контроль таймзоны чтения: поле ScanLocation у кодека (появилось в 5.6) умеет предъявлять момент в заданной локации, что спасает отчёты, которые должны считаться в одной зоне независимо от сервера. Отдельная предосторожность — колонка timestamp без таймзоны: она хранит «стенные часы» без привязки к точке на оси времени, и после чтения в time.Time нулевая таймзона Go честно сигнализирует, что контекста нет; с ней нельзя считать интервалы через вычитание, если записи писались из разных зон. Правило по умолчанию простое: new таблицы — timestamptz, приёмник — time.Time, обёртка — по исключениям из этого абзаца.

NUMERIC — единственный правильный дом для денег: numeric(12,2) хранит ровно двенадцать значащих цифр с двумя после точки, без бинарных сюрпризов. Float64 — двоичная дробь, и десятичные значения вроде 0.1 в ней не помещаются; складывая копейки, вы накапливаете погрешность, которая однажды проявится в отчёте. В Go выбор приёмника для numeric — развилка из трёх путей. Строка: Scan в string возвращает число в текстовой форме базы — точность сохраняется, но арифметику придётся делать самому. Обёртка pgtype.Numeric: Int *big.Int, порядок Exp, флаги NaN, Valid и InfinityModifier — полная точность и готовность к экзотике вроде бесконечности, а Float64Value() отдаёт Float8, когда нужен вывод в график. Обычный float64: работает и для агрегатов, где точность копеек не критична. Моё правило: суммы, балансы и тарифы — Numeric или целые копейки в bigint; метрики, коэффициенты и проценты — float64 без угрызений. Кстати о целых копейках: альтернативная школа вообще не использует numeric, храня суммы в bigint — спор об этом решается бюджетом проекта, но ни один из двух честных вариантов не называется float64.

pgtype не заканчивается тройкой из заголовка, но остальное заслуживает отдельных экскурсий. JSONB — тема одиннадцатого урока: там структуры и карты Go сканируются прямо в jsonb-колонки, а запросы по JSON-полям разбираются на живых примерах. Массивы Postgres — тема двенадцатого: []string и числовые срезы без ручных конвертаций, когда массив честнее отдельной таблицы. Из мелочи, что пригодится сразу: enum сканируется в string — собственные константы Go с проверкой на границе делают его безопасным; bytea приезжает в []byte; inet умеет в netip-адреса. Составные типы и диапазоны лежат в том же pgtype — они ждут вас в итоговом проекте двадцать пятого урока, где типы из этого урока встретятся с транзакциями и Batch. Пока же закрепите главный навык: перед новой колонкой открыть таблицу соответствий и выбрать приёмник сознательно, а не по привычке от предыдущего проекта.