Мультибазовость: диалекты — один код для Postgres, MySQL и SQLite в GORM

GORM разделена на ядро и драйверы, и это разделение — не украшение архитектуры, а точка, где принимается всё диалектное. Ядро собирает запрос не как строку, а как Statement со списком clause-ов: INSERT, VALUES, ON CONFLICT, WHERE, ORDER BY, LIMIT — и каждый clause умеет писать себя в буфер. Кто ведёт этот буфер в текст конкретной базы? Dialector. Это интерфейс из gorm.go с обязательными методами Name() (имя диалектора: postgres, mysql, sqlite), Initialize (поднять соединение и зарегистрировать колбэки), DataTypeOf (перевод типа поля модели в тип колонки), BindVarTo (как рисуется плейсхолдер), QuoteTo (как цитируются имена), Explain (красивый SQL-след для лога) — плюс необязательные расширения: ClauseBuilders (подмена поведения отдельных clause-ов) и Translate из интерфейса ErrorTranslator (нормализация ошибок, до неё дойдём в середине урока). Три официальных диалектора живут в трёх модулях: gorm.io/driver/postgres построен поверх pgx от Джека Кристенсена — того самого драйвера, чью семью pgtype мы упоминали в разговоре о массивах; gorm.io/driver/mysql — поверх классического go-sql-driver/mysql; gorm.io/driver/sqlite — поверх mattn/go-sqlite3, а это байндинг к C-библиотеке, то есть честное требование CGO. Каждый диалектор при Initialize дописывает свой набор колбэков: именно там PostgreSQL включает RETURNING, SQLite — своё, MySQL — своё. Отсюда рабочее правило урока: ваш прикладной код обращается к gorm.DB, диалектное — спрятано в Dialector, и перенос базы — это замена одного аргумента Open плюс аудит того, чем вы всё-таки воспользовались из знаний конкретной СУБД.

Чтобы спорить о диалектах предметно, посмотрим, чем диалекторы отличаются в исходниках. В ядре, в callbacks/callbacks.go, объявлены базовые clause-списки: createClauses = []string{"INSERT", "VALUES", "ON CONFLICT"}, updateClauses = []string{"UPDATE", "SET", "WHERE"}, deleteClauses = []string{"DELETE", "FROM", "WHERE"} — из них колбэки собирают каждый запрос. Диалектор получает право дописать или подменить этот список при регистрации колбэков, и вот что делают трое. PostgreSQL-диалектор в postgres.go добавляет "RETURNING" ко всем трём спискам: CreateClauses, UpdateClauses и DeleteClauses — то есть RETURNING есть не только у вставки, но и у UPDATE и DELETE, где Postgres умеет возвращать старые и новые значения колонок. SQLite-диалектор просто объявляет свои списки с RETURNING на борту: CreateClauses: []string{"INSERT", "VALUES", "ON CONFLICT", "RETURNING"}, а в UpdateClauses у него даже появляется FROM — SQLite с версии 3.33 умеет UPDATE ... FROM, и драйвер этим пользуется. MySQL-диалектор делает противоположное: он расширяет UpdateClauses и DeleteClauses парой "ORDER BY", "LIMIT" — записями вроде UpdateClauses = []string{"UPDATE", "SET", "WHERE", "ORDER BY", "LIMIT"} из mysql.go. Это не прихоть, а документированная способность MySQL: у него ORDER BY и LIMIT допустимы прямо в UPDATE и DELETE. Читая эти списки, вы читаете фактическую карту возможностей: что диалектор дописал — то база умеет, чего не дописал — того не обещано. Пятый урок уже показал, как clause.OnConflict превращается в SQL; сегодня смотрим на конвейер шире — как на таблицу отличий, записанную прямо в коде драйверов.

Мост из пятого урока: ID свежевставленной строки возвращается в структуру двумя механизмами — урок о Create разбирал этот выбор с прикладной стороны, а здесь смотрим, кто его делает. Решает не вы, а диалектор. PostgreSQL добавляет RETURNING к clause-спискам всегда — строка postgres.go «callbackConfig.CreateClauses = append(callbackConfig.CreateClauses, "RETURNING")» — и заодно получает назад значения полей с default-выражениями: база прислала их в той же команде. SQLite-диалектор держит RETURNING в своих списках сразу: отдельная СУБД-версия не опрашивается, а сам SQLite поддерживает RETURNING начиная с 3.35, и современные байндинги его дают. MySQL — самая интересная история, потому что у классического MySQL RETURNING нет вовсе, и mysql.go включает его условно: в Initialize драйвер выполняет SELECT VERSION(), и только если в ответе обнаружена MariaDB версии 10.5 и новее — условие checkVersion(dialector.ServerVersion, "10.5") внутри ветки с "MariaDB" — к спискам добавляется RETURNING. Две оговорки исходников: опция DisableWithReturning: true отключает механизм принудительно, а SkipInitializeWithVersion: true пропускает запрос версии — и тогда withReturning остаётся false даже на MariaDB, молча. На классическом MySQL остаётся второй путь: GORM читает result.LastInsertId() у драйвера и раздаёт значения; на срезах — первый ключ плюс шаг автоинкремента. Практическая цена та же, что в пятом уроке: поле с default-выражением после Create на MySQL останется нулём в структуре — RETURNING читать некому, и никаких Translate-подмен это не лечит. Проверяйте версию — драйвер делает это за вас, но только если вы ему не запретили.

Второй слой отличий — то, что видно в каждой строке SQL-следа. Плейсхолдеры: метод BindVarTo у postgres-диалектора пишет '$' и номер — $1, $2, $3; у mysql- и sqlite-диалекторов он умещается в одну строку — writer.WriteByte('?'). Поэтому SQL-след с нумерованными долларами выдаёт PostgreSQL с pgx мгновенно. Цитирование имён: QuoteTo postgres-диалектора оборачивает идентификаторы в двойные кавычки — это стандарт SQL; mysql-диалектор пишет бэктики; а вот sqlite-диалектор GORM, вопреки ожиданию, тоже пишет бэктики — и это легально, потому что SQLite принимает бэктики ради совместимости с MySQL. Регистр: здесь GORM не помощник, он передаёт условие базе как есть — седьмой урок уже разбирал ILIKE как регистрозависимую компенсацию Like-а у Postgres, а это материал седьмого урока; MySQL при коллациях *_ci ищет без регистра сам, SQLite не различает регистр для ASCII. То же с датами и булевыми: timestamptz у Postgres, datetime с точностью у MySQL, у которого parseTime=True в DSN не опция, а условие чтения time.Time. Никакой магии в этих отличиях нет — каждое сидит в конкретном методе конкретного диалектора, и когда «на другом диалекте сломался поиск по подстроке», ответ ищите не в логах GORM, а в этой карте: чем пользователь воспользовался — ILIKE, бэктиками или коллацией — и есть ли аналог там, куда переезжают.

Пришло время отдать долг прошлого урока: jsonb, GIN и оператор @> были названы знанием диалекта — теперь разбираем их целиком. PostgreSQL хранит jsonb в распарсенном бинарном виде: ключи дедуплицированы, порядок не сохраняется, зато доступны операторы — прежде всего @> «содержит», который проверяет вложенность документа. На jsonb строится GIN-индекс, и план запроса с WHERE data @> '{"city":"Пенза"}' показывает Bitmap Index Scan по GIN: выборка мгновенная, потому что индекс организован под поиск по элементам, а не по строке. Индексы — материал восемнадцатого урока: он показывал, как GORM строит их тегами, но GIN на jsonb-колонке — уже SQL-знание: CREATE INDEX ... USING gin (data), исполняемый миграцией или db.Exec. MySQL отвечает своим типом json (с версии 5.7.8): тоже распарсенное хранение, но оператора @> нет — поиск по элементу идёт функциями, а индекс строят функциональным: CREATE INDEX ... ((CAST(data->'$.city' AS CHAR(64)))) по выражению пути. SQLite — третий мир: «JSON-колонка» у него обычный TEXT, разбора на стороне хранилища нет, поиск — функциями вроде json_extract из семейства json1, а индекс, если нужен, — тоже по выражению. Отсюда честная иерархия для переезда: jsonb+GIN+@> — максимум скорости поиска и максимум привязки к диалекту; json с функциями — середина; текст с сериализацией на границе модели — медленный на фильтре, но переносимый везде. Один тег type:jsonb в модели — и вы уже в первом мире со всеми его преимуществами и ограничениями.

Прогноз выше опирается на метод, который стоит разобрать до строчек. DataTypeOf — это перевод типа поля модели в SQL-тип колонки, и у каждого диалектора он свой. Разберём три показательные ветки. Строка: postgres.go при Size 0 возвращает text, а при заданном размере varchar(n); mysql.go без размера берёт DefaultStringSize — конфиг-поле со значением 256 по умолчанию — и делает varchar(256), но в ветке есть ещё одна деталь с комментарием «// utf8mb4»: если поле ключевое, имеет default или под ним индекс, размер ужимается до 191 — классическое наследие ограничения длины индексного ключа в старых utf8mb4-индексах MySQL. SQLite пишет text всегда — в SQLite VARCHAR(255) это просто тип с аффинностью TEXT. Булев тип: Postgres даёт честный boolean, MySQL тоже пишет boolean, хотя хранит его как tinyint(1); sqlite-диалектор возвращает numeric — и таблица создаётся с numeric-колонкой, которую SQLite, благодаря аффинностям, держит как хочет. Автоинкремент: bigserial у Postgres, int auto_increment у MySQL, а sqlite.go возвращает целую формулу — «integer PRIMARY KEY AUTOINCREMENT». Время: timestamptz против datetime(3) — mysql-диалектор подставляет DefaultDatetimePrecision, равное трём знакам после запятой. Вывод для практики: миграция из четвёртого урока не «создаёт одну и ту же таблицу в разных базах» — она создаёт три разных таблицы из одной модели, и сравнение d в psql с SHOW CREATE TABLE в MySQL — лучший способ увидеть диалект вживую. Отсюда и правило: не полагайтесь на дефолтные типы там, где важна точность, — задавайте size и type явно.

Три режима clause.OnConflict из пятого урока вы уже знаете как готовый приём; сейчас интересна механика, как один clause живёт в разных базах. Имя clause-а всегда «ON CONFLICT» — его возвращает метод Name() структуры clause.OnConflict, и в clause-списках вставки у всех диалекторов стоит именно ON CONFLICT, унаследованный от ядра. Но перед записью в буфер каждый диалектор имеет право перехватить clause через ClauseBuilders — карту подмен, которую Initialize передаёт ядру. MySQL этим правом пользуется полноценно: в mysql.go карта содержит ClauseOnConflict, и её функция пишет в буфер не стандартную форму, а строку builder.WriteString("ON DUPLICATE KEY UPDATE ") — дальше идут присваивания, которые GORM собрала из полей clause-а: перечисленные колонки или обновление всех сразу. Дока формулирует совместимость дословно: GORM provides compatible Upsert support for different databases — совместимый upsert для разных баз, то есть API один, а SQL подставляется по диалекту. Самая неочевидная деталь — DoNothing на MySQL: у MySQL нет DO NOTHING, поэтому диалектор в той же функции превращает «ничего не делать» в фиктивное присваивание ключа самому себе — INSERT ... ON DUPLICATE KEY UPDATE id=id: строка-дубль найдена, ничего не изменено, RowsAffected ноль. Второе отличие — цель конфликта: PostgreSQL требует сказать, по какому ограничению конфликт, а MySQL цели не принимает вовсе — Columns игнорируются, потому что ON DUPLICATE KEY срабатывает по любому уникальному ключу. SQL Server, упомянутый в доке, решает задачу совсем другим statement-ом — MERGE INTO; но он за рамками тройки урока. Мораль: clause.OnConflict — это абстракция над тремя разными SQL-мирами, и при отладке смотрите итоговый SQL, а не API.

Пятый урок показал, что вставка с уникальным Slug рано или поздно упрётся в констрейнт, и назвал коды: 23505 у Postgres, 1062 у MySQL. Теперь смотрим, как с этим работать на трёх базах одним кодом. Без помощи GORM вы классифицируете тексты и типы драйверов: доки советуют switch по mysql.MySQLError с веткой case 1062 — «MySQL code for duplicate entry»; у Postgres ошибка — pgconn.PgError с полем Code; SQLite отвечает текстом «UNIQUE constraint failed», а численно — расширенными кодами 1555 и 2067 (нарушение первичного ключа и уникального индекса). Три базы — три разных типа — три switch-а в вашем коде. GORM предлагает второй путь: в errors.go объявлены gorm.ErrDuplicatedKey = errors.New("duplicated key not allowed") и gorm.ErrForeignKeyViolated, а конфиг gorm.Open принимает TranslateError: true — доки объясняют: когда TranslateError включён, GORM converts database-specific errors into its own generalized errors — и добавляют: By enabling TranslateError, GORM provides a more unified way of handling errors across different databases. Механика честно локализована в драйверах: у каждого свой файл error_translator.go с картой кодов — postgres.go-фамилия кодов: «23505»: gorm.ErrDuplicatedKey, «23503»: ErrForeignKeyViolated, «42703»: ErrInvalidField, «23514»: check-constraint; mysql-карта — 1062: gorm.ErrDuplicatedKey и пара 1451/1452 на внешние ключи; sqlite-карта — 1555, 2067 и 787. Метод Translate сверяет код и оборачивает: postgres-версия делает fmt.Errorf("%w: %w", translatedErr, pgErr) — двойное заворачивание, поэтому errors.Is находит и gorm-ошибку, и оригинал драйвера. После этого один if errors.Is(err, gorm.ErrDuplicatedKey) работает на трёх базах — то, что в ent-курсе вы называли UniqueConstraintError, здесь носит имя ErrDuplicatedKey, а при выключенном TranslateError не сработает никогда.

Семнадцатый урок научил вас Limit и Offset как методам GORM; на диалектном уровне выясняется, что LIMIT — не везде такой одинаковый, каким кажется. В SELECT тройка урока совпадает: LIMIT n OFFSET m понимают PostgreSQL, MySQL и SQLite, так что пагинация — самая переносимая часть языка. Методы GORM собирают именно эту форму, и сюрпризов здесь нет. Дальше начинается интересное: LIMIT и ORDER BY в модифицирующих командах. MySQL разрешает их прямо в UPDATE и DELETE — и мы уже видели доказательство в исходниках: mysql.go объявляет UpdateClauses и DeleteClauses с "ORDER BY", "LIMIT" на хвосте, то есть диалектор честно разрешит db.Limit(10).Delete(&TodoItem{}), и это будет легальный MySQL-запрос «удалить не больше десяти». PostgreSQL в UPDATE и DELETE прямого LIMIT не имеет: чтобы ограничить затронутые строки, пишут подзапрос по ctid или по первичному ключу — либо оставляют задачу WHERE-условию. SQLite поддерживает UPDATE/DELETE с LIMIT только как опцию сборки — флаг SQLITE_ENABLE_UPDATE_DELETE_LIMIT при компиляции библиотеки; в стандартных сборках go-sqlite3 этой опции нет, и запрос упадёт с синтаксической ошибкой. Практический вывод двоякий. Первый: пакетная обработка через «LIMIT в DELETE» пишется только под MySQL — под две другие базы делайте это SELECT-ом по ключам и DELETE WHERE id IN. Второй: GORM пропустит .Limit() в запросе изменения на любом диалекторе — проверка синтаксиса происходит в базе, и ошибка приедет из неё, а не из библиотеки. Диалект-знание экономит отладку: вы знаете, чья это поддержка, ещё до запуска.

Из трёх диалекторов SQLite единственный не требует сервера, и именно поэтому он стал любимцем тестов: база живёт в памяти процесса, поднимается за миллисекунды, умирает вместе с ним, не оставляя мусора. DSN-правила приносит mattn/go-sqlite3: классический «:memory:» создаёт частную базу на каждое соединение, а строка file:test.db?cache=shared&mode=memory из README — общую именованную память. Ловушка, о которую бьются все: GORM по умолчанию держит пул соединений, и второе соединение к «:memory:» увидит пустую базу — отсюда классический вопрос «почему no such table, ведь таблица создавалась». Лечится двумя способами: DSN с cache=shared — тогда все соединения пула смотрят на одну память — или db.DB() и SetMaxOpenConns(1), что честнее для теста: одна память, один писатель, никаких сюрпризов блокировок. Вторая особенность — сборка: официальный sqlite-драйвер основан на C-библиотеке и требует CGO, о чём README говорит прямо, а рядом перечисляет чисто-Go альтернативы — glebarez/sqlite и другие — с фразой Usage is identical — simply swap the import path: импорт меняется, диалектный код нет. В cross-compilation без CGO официальный драйвер не соберётся вовсе, и альтернатива — не роскошь, а необходимость. В sqlc-курсе SQLite-для-тестов посвящён отдельный урок; здесь зафиксируем границу: in-memory — это про скорость и изоляцию лаборатории, а инструменты вокруг тестов — транзакционные тесты, фабрики данных — тема двадцать четвёртого урока, который начинается ровно с этого моста. Память — не уменьшенная база, а настоящая SQLite: все диалектные отличия этого урока в ней присутствуют целиком.

Соберём правило портативности, которое урок прошёл по всем слоям. Уровень первый — код: db.Create, db.Where, ассоциации, транзакции одинаковы на трёх базах, потому что диалект-знание спрятано в Dialector — вы платите одним аргументом Open. Уровень второй — типы колонок: DataTypeOf переводит одну модель в три таблицы, и varchar(256) против text против numeric — это не ошибки, а переводы; проверяйте их SHOW CREATE TABLE-ом и задавайте size/type явно, когда точность важна. Уровень третий — SQL в строках условий: регистрозависимый ILIKE-поиск, jsonb-оператор @>, json_extract, бэктики — вы выехали за границу GORM, и переносить такое придётся руками; держите эти строки в скопах и репозиториях запросов, чтобы их было видно. Уровень четвёртый — ошибки: TranslateError превращает три карты кодов в один errors.Is, и это дешёвая страховка при переезде. Куда двигаться дальше: двадцать четвёртый урок — тестирование с GORM, и он начинается с того, что этот урок оставил в наследство — SQLite in-memory как полигон, на котором все диалектные правила всё ещё честные. Возьмите канон этого урока и прогоните свой домашний проект на всех трёх базах: список упавших мест — это и есть ваш личный портрет диалект-знания, и лучше узнать его до продакшена, чем после.