Запросы INSERT и RETURNING

Четыре формы возврата из таблицы третьего урока при вставке работают неравномерно. Немую вставку обслуживают две: sqlc exec — в аннотации :exec — когда ответ не нужен, и :execrows, когда важно число задетых строк. Как только в запросе появляется RETURNING, выбор расширяется: :one вернёт одну строку, :many — срез. CreateTodo из третьего урока был :exec, и для трекера это перестало устраивать: новая задача обязана отвечать своим номером.

Сгенерированный метод ляжет в тот же db/queries/todos.sql.go — правило «один файл запросов — один .sql.go» никуда не делось. Помнить надо другое: sqlc переписывает файл целиком при каждой генерации, поэтому старая сигнатура CreateTodo(ctx, title string) error исчезнет без предупреждений, и компилятор подсветит все места, где вызов пора обновить. Это не побочный эффект, а рабочая страховка: между запросами и кодом не остаётся ни одного расхождения — сломался компилятор, а не прод.

RETURNING — часть самого INSERT-оператора: в конец запроса дописывается список колонок, и база возвращает те значения, которые получила именно эта вставка. id здесь не «последний в таблице», а конкретный номер, который sequence выдал вашей строке в момент INSERT; created_at — настоящее серверное время now(), а не часы приложения: серверы могут жить в разных часовых поясах, и база остаётся единственным источником правды. Сюда же попадают DEFAULT-значения: не указали priority — вернётся дефолт, проставленный базой, done станет false из миграции. Сокращение RETURNING * тоже работает — sqlc раскроет звёздочку, как и в SELECT из первого урока.

returning sqlc превращает вставку в чтение: набор колонок после RETURNING определяет и Go-тип. Перечислили подмножество полей Todo — метод вернёт Todo с заполненной частью полей; перечислили всё — структуру целиком. А добавив RETURNING к UPDATE или DELETE, вы получите назад изменённые и удалённые строки — этому посвящён шестой урок.

Гуглите «как получить id после вставки» — и самые залежавшиеся советы будут одинаково плохи: вставьте строку, потом SELECT max(id). На пустой тестовой базе приём работает, и именно в этом его опасность. Разложим гонку по шагам: вы вставили задачу — база выдала ей id 42; пока ваш INSERT доехал до сервера, а SELECT ещё не отправился, второй экземпляр приложения вставил свою строку с id 43; ваш max(id) возвращает 43 — чужую задачу. Дальше по накатанной: CompleteTodo(43) закрывает не вашу задачу, ответ уходит не тому пользователю, и заметят это только люди.

При READ COMMITTED — дефолтном уровне изоляции PostgreSQL — чужие закоммиченные строки видны каждому новому SELECT, так что гонка не теоретическая: два параллельных клиента — уже два участника. RETURNING закрывает вопрос по определению: он выполняется внутри самого INSERT и возвращает значения строк, которые вставил именно этот оператор, атомарно и за одну поездку в базу вместо двух. Побочный бонус — производительность: на нагруженной вставке это вдвое меньше обращений к сети.

Пачка задач через цикл с одиночными INSERT — это N поездок в базу и N отдельных операторов: на локальной базе незаметно, на удалённой — уже заметно на каждом чеке. PostgreSQL умеет вставлять целый срез одной командой через unnest: функция разворачивает массив в колонку строк, и запрос выглядит как INSERT ... SELECT * FROM unnest($1::text[], $2::boolean[]) — два массива становятся двумя колонками. Касты ::text[] и ::boolean[] обязательны: без них парсер не определит тип параметра и генерация упадёт с сообщением о неопределённом типе.

Параметры в Go — обычные срезы: pgx превращает их в массивы PostgreSQL нативно; с database/sql и lib/pq срезы пришлось бы заворачивать в pq.Array — ещё один довод в копилку pgx/v5 из четвёртого урока. Нюанс сигнатуры: пока у параметров типы разные ([]string и []bool), sqlc отдаёт плоские аргументы; сделайте массивы одного типа — и параметры свернутся в структуру вида BulkCreateTodosParams, имена полей sqlc возьмёт из колонок. Массовая вставка sqlc этим не ограничена: для сотен тысяч строк существует CopyFrom — он есть в интерфейсе DBTX, живёт в pgx и работает мимо sqlc, но быстрее всего на свете; unnest-пачки хватает на порядки меньших объёмов.

Вставка — первое место, где типы четвёртого урока выходят из Scan и становятся параметрами. Nullable колонка deadline timestamptz в параметре CreateTodo живёт той же жизнью, что и в структуре: с database/sql это sql.NullTime, в чистом pgx/v5 — pgtype.Timestamptz, где NULL — нулевая структура с Valid: false, а после pointer-override — *time.Time, где NULL — nil. Для вставки указатели даже удобнее обёрток: «срока нет» выражается буквально nil. Паттерн тот же, что у SetNillable-мутаторов в ent: передали nil — колонка пуста, передали значение — записалось; выбор между Valid-флагом и указателем делает один и тот же override и для чтения, и для записи.

Главное — не изобретать магических значений. Нулевое time.Time{} — это вполне себе дата 1 января первого года, и колонка с ней не «пустая», а заполненная хламом, который потом придётся отфильтровывать. «Срока нет» в таблице со nullable-колонкой кодируется ровно одним способом — NULL, и RETURNING честно привезёт его обратно в поле-указатель.

У INSERT больше способов упасть, чем у SELECT: NULL в NOT NULL-колонке, нарушение уникальности, ссылка на отсутствующую строку соседней таблицы. И тут честная оговорка: sqlc в классификации ошибок не участвует. Он генерирует вызов и возвращает err как есть — вся разница между «дубль» и «авария» живёт в слое драйвера. В pgx ошибка базы — это структура *pgconn.PgError с полями Code, Message, ConstraintName; достаётся она из цепочки обёрток через errors.As стандартной библиотеки, причём и через database/sql-обёртку stdlib-драйвера из третьего урока тоже.

Код 23505 — unique_violation из официального каталога кодов PostgreSQL. Заучивать числа не обязательно: в пакете github.com/jackc/pgerrcode есть именованные константы на все коды, и pgerrcode.UniqueViolation читается лучше, чем строковый литерал. Поле ConstraintName подскажет, какой именно индекс воспротивился — полезно, когда ограничений в таблице несколько.

Теперь у трекера вставка с ответом: методы возвращают строки, которые база создала сама, — с номером, серверным временем и дефолтами. Шестой урок — UPDATE и DELETE: условия, число затронутых строк и мягкое удаление руками; там :execrows встретится уже в своей основной роли. Весь план из 25 уроков — на странице курса.

Для контраста: в курсе GORM вставка устроена наоборот — вызов Create() сам дописывает сгенерированный id в поля структуры. В sqlc за этим стоит явный RETURNING, который вы пишете и читаете руками. Обе модели имеют право на жизнь, но sqlc хотя бы не прячет SQL, который выполняется в вашей базе.