Exec и Query: первые запросы

Сигнатура: Exec(ctx, sql, args...) возвращает pgconn.CommandTag и ошибку. CommandTag — отчёт сервера о том, что произошло: главное поле — RowsAffected, число затронутых строк. INSERT одной строки даст единицу, UPDATE по пяти строкам — пятёрку, DELETE по несуществующему идентификатору — ноль, и это не ошибка, а честный ответ базы. Значение RowsAffected — не украшение: это способ узнать, сколько строк реально изменилось, не делая лишний SELECT COUNT перед или после. DDL — тоже Exec: CREATE TABLE и CREATE INDEX идут тем же вызовом, потому что схемы возвращают строк не больше, чем данные. У CommandTag есть и текстовое лицо — метод String(): для INSERT одной строки это что-то вроде INSERT 0 1, где ноль — наследие устаревшего поля oid, а единица — затронутые строки; отчёт UPDATE выглядит как UPDATE 5. В логах и тестах такой текст удобнее числа: сразу видно, какая команда и сколько строк за ней стоит. Плейсхолдеры $1 и $2 в аргументах защищают от SQL-инъекций — тема настолько важная, что восьмой урок полностью посвящён аргументам запроса; здесь достаточно правила: значения едут через аргументы, никогда через склейку строк. И про типы: pgx не чинит несовместимости молча — аргумент уезжает на сервер в родном для своего типа виде, а несовпадение ловится ошибкой кодирования или сканирования, а не сюрпризом в данных. Текст у такой ошибки дружелюбный: pgx называет и колонку, и тип, который не смог закодировать — читайте её целиком, прежде чем менять структуру.

Когда по смыслу ожидается ровно одна строка — профиль пользователя по идентификатору, текущий курс валюты, итог счётчика — короче всего QueryRow: row := conn.QueryRow(ctx, sql, args...), затем row.Scan(&переменные). Scan распаковывает колонки в переменные Go по порядку. Отдельный контракт: если SELECT не нашёл ни строки, Scan вернёт pgx.ErrNoRows. Это не сбой — штатный ответ на вопрос «такого нет», и код обрабатывает его явно: if errors.Is(err, pgx.ErrNoRows) — отдать 404, создать запись или вернуть дефолт. Ошибки сканирования приходят, когда типы колонок и приёмников не совпали: скан текста в int упадёт с внятным текстом, а не паникой. Тонкость, о которую бьются новички: QueryRow возвращает объект сразу, без ошибки — ошибка живёт в Scan и доставается в момент вызова, поэтому проверить её нужно там, а не в строке QueryRow. ErrNoRows живёт и под именем pgconn.ErrNoRows — это одно и то же значение с двумя алиасами, так что чужой код может проверять любой из них, а errors.Is различит без ошибок. И помните: Scan распаковывает колонки строго по порядку SELECT, а не по именам — переставили поля в запросе, переставьте и приёмники.

Самый частый вопрос после первого INSERT: как узнать сгенерированный идентификатор? Ответ Postgres — конструкция RETURNING: INSERT INTO notes (title) VALUES ($1) RETURNING id возвращает строки, а значит для него нужен не Exec, а QueryRow. row := conn.QueryRow(ctx, insertSQL, title); затем row.Scan(&id) — и в руках у вас свежий идентификатор, без лишнего SELECT и без гонок с параллельными вставками. Exec здесь потерял бы результат: он для команд без возвращаемых строк. RETURNING умеет отдавать несколько колонок и работает с UPDATE и DELETE тоже — так за одну поездку по сети забирают и изменённые данные. Умеет он и вычисленные значения: UPDATE ... RETURNING updated_at вернёт метку времени, поставленную сервером по своим часам, — для аудит-логов это разница между «примерно когда» и «точно когда». С клиентской точки зрения разница в выборе вызова тривиальна, но она расставляет границу между двумя контрактами: есть строки — QueryRow или Query, строк нет — Exec. Запомните это правило, и половина путаницы с pgx исчезнет. И да, RETURNING — не только про id: им удобно забирать обновлённые счётчики или версии строк, чтобы не ходить повторным SELECT за данными, которые сервер уже держит в руках.

Query возвращает pgx.Rows — курсор по результату выборки. Канонический цикл: for rows.Next() { err := rows.Scan(&a, &b); ... }, а после цикла — rows.Err(). Next тянет следующую строку с сервера и возвращает false на конце выборки или при ошибке; Scan распаковывает текущую строку в переменные; Err докладывает, была ли ошибка по дороге. Про Close честно: в нативном pgx курсор закрывается сам при полном проходе, но при раннем выходе — return внутри цикла — закрытие остаётся за вами, поэтому defer rows.Close() сразу после Query — дешёвая страховка, особенно с пулом: незакрытый курсор держит коннект занятым. Ещё одна тонкость одиночного Conn: двух открытых курсоров он не терпит — пока первый не пройден, второй Query на том же соединении будет ждать. Конкурентные запросы делят соединение через пул из четвёртого урока, а не напрямую через один Conn. Механика выборки предсказуемая: на Query сервер отправляет описание колонок, и после каждого Next pgx тянет очередную строку протокола — буфера «на всю выборку» нет, миллионная таблица не съест память приложения, но и быстрее сети не будет. Весь результат сразу собирается в срез обобщениями — это тема седьмого урока.

Exec без аргументов умеет выполнять несколько SQL-команд одной поездкой: conn.Exec(ctx, "CREATE TABLE a (...); CREATE INDEX ...;") — pgx переключается на простой протокол и отдаёт стейтменты пакетом. Только не путайте пачку с транзакцией: если второй стейтмент упадёт, первый останется выполненным — атомарность приедет отдельно, тринадцатым уроком. Удобно для инициализации схемы в тестах и демо-скриптах. Как только появляются аргументы, правило меняется: один вызов — одна команда с плейсхолдерами, потому что расширенный протокол принимает по одному стейтменту за раз. Сотни однотипных INSERT идут не через цикл Exec, а через Batch и COPY FROM — восемнадцатый и девятнадцатый уроки покажут разницу в разы на реальных цифрах. Пока же запомните порядок: одна команда с аргументами — Exec, пачка однотипных — Batch, тонны строк — COPY. И напомню про формат курса: песочница сайта не умеет сеть и Postgres, поэтому эти программы исполняются локально — Go и команда docker run из второго урока; в песочнице урока откроется тематическая программа на чистом Go, а типизация аргументов и защита от инъекций — тема восьмого урока, до которого — никаких склеек строк в SQL.