Массивы Postgres: []string и pgtype.Array

Список типов, для которых pgx собирает и разбирает массивы без ваших усилий, короткий и покрывает почти всё: []string, []int16, []int32, []int64, []float32, []float64, []time.Time — и те же срезы с указателями []string для NULL-элементов. Драйвер регистрирует их заранее: срез []T при кодировании согласуется с массивом _T, то есть []string едет в text[], []int32 — в int4[], []time.Time — в timestamptz[]. Запись: INSERT INTO products (title, tags) VALUES ($1, $2) с тегами в переменной — колонка получит честный массив, а не строку с запятыми. Чтение: Scan в []string заполняет срез элементами строки. Ограничение простого пути — метаданные размерностей: plain срез получает элементы, но ничего не знает о нижних границах и форме массива. Ещё одна честная оговорка — элементы: простой []string требует, чтобы все элементы были значениями; как только в колонке появляется SQL NULL среди элементов, скан падает ошибкой на конкретном индексе — механика у ошибки прозрачная, «failed to scan array element 0» и дальше причина cannot scan NULL into string. Лечится это переходом на []*string, и это следующий блок. Кстати, varchar[] и name[] обслуживаются тем же текстовым кодеком, что и text[], — отдельного типа Go для них не нужно. Многомерные массивы при этом не исключение из простого пути: срез срезов [][]string читается и пишется сам, если он не рваный — все строки одной длины; риск простого среза в этом деле один: нижние границы из чужого дампа показать негде. Для хранения самих размерностей нужна обёртка pgtype.Array — до неё дойдём после самых ходовых приёмов.

Здесь спрятаны самые дорогие недопонимания, поэтому растолкуем по слоям. SQL NULL в колонке целиком — «массива нет вообще»: такой NULL сканируется в nil-срез без ошибки, и симметрично nil-срез из Go записывается как NULL — драйвер отправляет нулевые размерности, сервер видит NULL. Пустой массив '{}' — другое состояние: массив существует, элементов в нём ноль; пустой ненулевой срез []string{} записывается именно так, и Scan вернёт пустой ненулевой срез. Третье состояние — NULL среди элементов: {"new", NULL, "sale"}; простой []string его не выдержит — элемент-NULL нечем представить в строке, и скан падает на первом же таком элементе с ошибкой cannot scan NULL into string. Приёмник []string решает задачу: nil-указатель в срезе — честный NULL, запись тоже симметрична. Нужна ли вам различимость трёх состояний — вопрос модели: для тегов обычно достаточно «нет тегов = пустой массив или NULL, обработка одна», и код с len(loaded) == 0 закрывает оба случая сразу. Запутаться в этом проще всего в тестах: nil-срез и пустой срез дают разные значения в базе — начните домашнее задание с проверки обеих вставок. На стороне SQL эти три состояния различаются честными функциями: tags IS NULL отделяет NULL от всего остального, cardinality(tags) считает элементы и для NULL вернёт NULL, а array_length(tags, 1) — длину первой размерности; пары «IS NULL плюс cardinality» хватает для любых ветвлений в запросах.

Когда простых срезов перестаёт хватать, включаются две обёртки из pgtype. FlatArray[T] — обобщённый тип, который превращает любой срез T в массив Postgres: []netip.Addr, []uuid.UUID, собственный тип — всё, для чего элемент уже умеет кодироваться. Он одномерный и невнимательный к размерностям: лишнюю информацию о нижних границах Postgres он отбрасывает — за это и назван плоским. Array[T] — полная форма: поля Elements и Dims []ArrayDimension с длиной и нижней границей каждой размерности плюс флаг Valid — обёртка хранит и отдаёт драйверу саму форму массива, включая «массив начинается с нулевого индекса» вместо привычной единицы. Разница между нативным срезом срезов и Array[T] теперь читается точно: обе дороги перевезут многомерные данные, но срез срезов не сообщит, какой была нижняя граница, а Array[T] сохранит. В прикладном коде эти вещи нужны реже, чем кажется: многомерность обычно признак того, что данные просятся в отдельную таблицу, но читать чужие дампы и админские выгрузки Array[T] спасает регулярно. Практический расклад такой: строки, числа, время — простой срез; экзотический элементный тип — FlatArray[T]; размерности и нижние границы — Array[T]; NULL-элементы — указатели внутри любого из вариантов. Обёртки из десятого урока с полем Valid тут соседствуют: у Array[T] Valid есть, у FlatArray — нет, его роль играет nil.

Силёнка массивов — SQL-операторы, и они же — причина выбрать массив вместо JOIN. Проверка вхождения: WHERE 'sale' = ANY(tags) — правый операнд колонка, левый значение; аккуратно с направлением, новички путают его с ANY-подзапросами. Передавать список значений параметром — тоже ANY: WHERE tags && $1 — оператор пересечения, вернёт строки, где массивы делят хотя бы один элемент; параметр — тот же []string из Go. Контейнмент @> спрашивает, содержит ли массив все элементы правого: WHERE tags @> $1 со срезом из двух тегов найдёт товары с обоими сразу. Всё это работает и в обратную сторону — на колонках int[] для идентификаторов. Скорость: обычное b-дерево по массиву не строится, поэтому для && и @> нужен GIN-индекс — CREATE INDEX ON products USING gin (tags); без него операторы честно сканируют таблицу, что на сотнях строк незаметно, а на сотнях тысяч — больно, и об этом расскажет план из двадцать второго урока. Развернуть массив в строки для агрегации — unnest(tags) в FROM: получили строки — посчитали, сгруппировали, вернули. У unnest есть продолжение WITH ORDINALITY: он добавляет колонку с исходной позицией элемента — то, чего массив в таблице без него не отдаёт. Направление «список идентификаторов в IN» решается тем же ANY: WHERE id = ANY($1) со срезом []int64 из Go — классика, экономящая склейку плейсхолдеров.

Сведём критерии в один разговор, потому что выбор этот переживает не один рефакторинг. Массив выигрывает, когда список короткий и ограниченный по смыслу — телефоны, роли, флаги; когда элементы не ссылаются на другие таблицы; когда читается и пишется список всегда целиком; и когда порядок элементов — часть данных, потому что массив его сохраняет. Таблица выигрывает, когда элементов может стать много; когда нужна ссылочная целостность и каскады; когда по элементам ищут с подсчётами и сортировками; когда каждый элемент обрастает своими полями — тег с автором и датой уже не элемент, а строка. Переезд из массива в таблицу потом возможен, но стоит неприятно: unnest на миграции, переписывание всех запросов — дешевле решить до продакшена. Сама миграция пишется один раз: INSERT INTO tags SELECT product_id, unnest(tags) FROM products с последующим дропом колонки, — боль не в SQL, а в разъехавшихся вызовах по всему коду. Замечу и скорость записи: сотни однотипных массивов через цикл Exec — путь в восемнадцатый урок с Batch, а не самостоятельная проблема массивов. И последнее: массив не заменяет jsonb из одиннадцатого урока — массив держит однотипные значения без имён, jsonb — разнотипные с ключами; путаница между ними в ревью чаще всего означает, что автор просто не сформулировал структуру.