Несколько схем и организация

Схема в Postgres — это пространство имён внутри одной базы: в ней живут таблицы, перечисления, представления и функции. Иерархия выглядит так: кластер содержит базы, база содержит схемы, схема содержит таблицы. В каждой базе есть схема по умолчанию — public, и шестнадцать уроков трекер честно прожил в ней: CREATE TABLE без квалификатора создаёт таблицу именно там. Схема — не база: это самая частая путаница темы. Разделение доменов по схемам не разводит данные по разным серверам и даже по разным файлам на диске — оно разводит имена и правила внутри одной базы.

Зачем домену собственное пространство имён. Первое — границы видны в самом SQL: запрос к billing.spendings сам объявляет, что трогает бухгалтерию, и в ревью это видно без знания контекста. Второе — права: Postgres выдаёт доступы на уровне схемы, и можно завести роль, которой разрешено читать billing и запрещено менять public — segregated доступ без единой строчки кода приложения. Третье — имена: у схемы свой словарь, и таблица журнала может называться просто spendings, не споря с будущими сущностями задач. Четвёртое — жизненный цикл: домен можно выгрузить одной командой DROP SCHEMA, не выписывая по таблице.

Применяем к трекеру: журнал списаний из одиннадцатого урока переезжает в схему billing — выделенное пространство бухгалтерии. Важная деталь, о которой часто спотыкаются: внешний ключ через схемы законен. billing.spendings может ссылаться на todos из public — обе таблицы живут в одной базе, и ссылочная целостность не знает о наших доменных границах. Домены — договор людей; база продолжает видеть одно пространство данных.

В живой базе за короткие имена отвечает search_path — список схем, в которых Postgres ищет неквалифицированные ссылки: SET search_path TO billing, public, и запрос FROM spendings найдёт таблицу в billing, если там она есть. Удобно, но именно на этом месте генератор и база расходятся в поведении, и урок обязан сказать это прямо: search_path sqlc не эмулирует. Каталог генератора собирается из schema-файлов, и неквалифицированное имя в запросе разрешается только в схеме по умолчанию — public. Настройки search_path в конфиге не существует: вопрос о ней в репозитории sqlc открыт как enhancement (Configure search_path), а оператор SET генератор не исполняет вовсе.

Практическое следствие одно, но железное: в проекте с несколькими схемами всё, что лежит вне public, пишется квалифицированно — и в DDL, и в запросах. Короткое FROM spendings при таблице billing.spendings не «не найдётся тихо» — генерация честно упадёт с ошибкой вида relation "spendings" (код 42P01, неопределённая таблица); падение здесь — лучший исход, потому что оно ловится на ноутбуке.

Есть у схем и подарочная сторона — имена в Go. Для таблиц вне схемы по умолчанию sqlc строит имя по шаблону схема_таблица: billing.spendings превращается в структуру BillingSpending, а перечисление billing.payment_status — в тип BillingPaymentStatus с константами вида BillingPaymentStatusCaptured. В public всё остаётся как прежде — канонический Todo без префиксов. Границы домена таким образом читаются прямо в коде приложения: один взгляд на сигнатуру, и видно, чью таблицу вы держите в руках.

Теперь сторона конфига. Ключ sql в sqlc.yaml — не объект, а список: каждая запись — самостоятельный набор генерации со своим движком, своей схемой, своими запросами и своим генератором кода. Доки прямо показывают конфиг из двух записей с разными движками; у каждой записи набор ключей один: name — необязательный человекочитаемый идентификатор набора, engine, schema — папка миграций или файл, queries — папка запросов или список путей, gen — генератор, плюс database и rules для проверок. Ключ name при одном пакете бесполезен, при двух-трёх уже помогает читать конфиг: записи перестают быть безымянными блоками yaml.

Главное следствие списка: на каждую запись — свой Go-пакет. В gen.go пишутся package — имя пакета на языке Go, и out — каталог, куда ляжет сгенерированный код; разные out — разные каталоги — разные пакеты с независимыми импортами. Кто-то ищет это под словами sqlc.yaml multiple packages, и поисковик приводит ровно сюда: список sql — штатный, документированный способ держать в одном файле конфигурации сколько угодно наборов генерации.

И второе следствие, менее очевидное: записей можно сколько угодно, а команда одна. sqlc generate обходит весь список за один запуск — каждый пакет обновляется сам. Так прячется ещё и ответ на вопрос об организации sqlc: один файл конфигурации, несколько точек выхода, границы домена видны и в конфиге, и в импортах. Соседняя запись может отличаться даже движком: в доках это postgresql рядом с mysql; для трекера обе записи — postgresql, но дорога к восемнадцатому уроку про MySQL уже лежит в этой конструкции — конфиг к смене движка готов, останется выучить отличия синтаксиса.

Конвенция курса «одна тема выборок — один файл» выросла в правило уровнем выше: один домен — папка. В db/queries/todos живут todos.sql — списки, фильтры и джойны задач — и users.sql — домен исполнителей, который задачами пользуется, но владеет своими таблицами; сюда же переезжают панель фильтров и страницы. В db/queries/spendings — spendings.sql, журнал списаний со своей схемой billing. Ключ queries у записи принимает папку — или список путей, если домену нужно собрать файлы из нескольких мест; ни один файл не принадлежит двум пакетам, и это не ограничение, а граница: запрос можно найти по домену, домен — по пакету.

Каждый пакет получает полный набор сгенерированных файлов: свой db.go с конструктором и интерфейсом соединения, свои модели, свой Querier — интерфейс, в котором только методы этого домена. Граница становится компиляторной: сервис задач принимает *tododb.Queries и физически не может вызвать CreateSpending — такого метода в его типе нет.

Где жить запросам на стыке? Правило владельца: запрос принадлежит домену главного данных. ListTodosWithUser — джойн задач с исполнителями — живёт в todos.sql: задачу показывает пользовательский интерфейс, пользователь здесь деталь задачи. Транзакция из одиннадцатого урока — закрыть задачу и записать списание — затрагивает оба домена, и с двумя пакетами сценарий не ломается: оба пакета построены над одним контрактом соединения, на одном транзакционном соединении можно держать по объекту Queries от каждого домена; подробности механики — в том уроке, здесь важна фактура: разветвление пакетов не ломает транзакции, потому что делит методы, а не соединения.

Раз оба пакета смотрят на одну папку миграций, честный вопрос — что окажется в моделях каждого. Ответ генератора прост до грубости: models.go каждого пакета строится по всему входу схемы. Раз в db/migrations описаны todos, users и billing.spendings, то и Todo, и User, и BillingSpending появятся в обоих пакетах — независимо от того, чьи запросы лежат в папке. Это не баг, а следствие устройства: генератор печатает модели по каталогу, а не по упоминаниям в запросах.

Дубль — не всегда зло: пакеты независимы, их можно версировать и переписывать порознь, и для среднего проекта две копии структур — приемлемая плата за простоту. Но у конструкции есть три ручки настройки, и урок перечисляет все три. Первая — omit_unused_structs: включённая, она оставляет в пакете только те структуры таблиц и перечислений, которые реально встречаются в его запросах; spendingdb перестаёт таскать Todo, если его запросы не касаются задач. Вторая — имена файлов: output_models_file_name меняет models.go на что угодно — например, billing_models.go; рядом живут output_db_file_name и output_querier_file_name для db.go и querier.go. Третья — само входное множество: schema может быть списком путей, и можно было бы развести миграции по доменам; но тогда внешний ключ billing.spendings → todos перестанет проверяться генератором в пакете spendings, потому что todos уйдёт из его поля зрения. Общая папка — компромисс, при котором границы проверяются целиком; усечение моделей дешевле усечения схемы.

Остаётся стык, который не решается ни схемами, ни пакетами: один и тот же смысл в двух доменах. Суммы в копейках хранятся BIGINT и в задачах (стоимость), и в журнале (списания); в Go хочется видеть их не голым int64, а типом Money из общего пакета types, с методами и гарантиями. Если настраивать переопределение в каждой записи отдельно, рано или поздно записи разъедутся: одна получит обновление, вторая — забудет.

Для этого у конфига есть верхний этаж — глобальные overrides. Блок overrides размещается на верхнем уровне sqlc.yaml, вне списка sql, и документируется фразой, которая почти дословно описывает наш случай: иногда одна и та же конфигурация нужна сразу нескольким наборам генерации. Внутри — два раздела: rename переименовывает поля структур по имени колонки во всех пакетах разом (классика — id в Identifier), а overrides задаёт отображение типов: db_type указывает тип базы, go_type — куда его спроецировать, вплоть до import, package и type в чужом модуле. У каждого правила глобального блока есть и ключ engine — он нужен только в конфигах, где определения различаются движками; в однодвижковом проекте его можно не писать, значение возьмётся из текущей записи.

Правило выбора этажа простое. Одинаковое для всех пакетов — наверх, в глобальный overrides: один источник, ноль расхождений. Различающееся — внутрь gen.go конкретной записи, где у каждого пакета свои локальные настройки. И аккуратность с go_type: тип из вашего модуля должен быть совместим со сканированием колонки — это уже ваш контракт с драйвером, генератор только вставляет имя.

Настройки gen.go, которые второй и четвёртый уроки разбирали по одному, живут на пакет — и теперь это перестаёт быть деталью. Краткий словарь тем урока. emit_json_tags добавляет структурам json-теги: включайте там, где структуры едут в HTTP-ответы, а не во всём подряд. emit_interface печатает интерфейс Querier поверх структуры — граница для подмены реализации; пакет задач с панелью фильтров выигрывает от неё больше, чем журнал. emit_exact_table_names заставляет имена структур точно повторять имена таблиц без единения множественного числа. emit_empty_slices возвращает пустой срез вместо nil из выборок-списков. emit_pointers_for_null_types проецирует nullable-колонки в указатели — для pgx/v5 это текущий канон курса. Здесь важен не словарь, а принцип: значение каждой настройки по умолчанию одинаково во всех пакетах, но включать их можно по-разному — домены настраиваются порознь, и это осознанное решение, а не расхождение версий конфига.

Трекер разветвился по всем этажам сразу. В базе журнал списаний получил собственную схему billing, и SQL-запросы читаются как объявления домена. В конфиге ключ sql стал списком из двух записей: schema у них общая — папка миграций остаётся единственной правдой о структуре, — queries делятся по доменам, а gen.go выдаёт два независимых пакета с собственными моделями и интерфейсами. Дубль моделей усекается omit_unused_structs, имена файлов настраиваются, а смыслы, общие для доменов, живут на верхнем этаже глобальных overrides. Так и собирается организация sqlc: граница домена — в схеме, в папке queries и в импорте пакета одновременно.

Следующий шаг — другой движок: восемнадцатый урок расскажет про MySQL — чем отличается синтаксис, как меняются типы и что из привычных конструкций не переносится; конструкция «две записи в одном конфиге» — та самая дверь, в которую MySQL входит без переписывания проекта. Конфиг с путями и базовыми настройками — во втором уроке; папка миграций как источник схемы — в шестнадцатом; план остальных тем — на странице курса sqlc.