Содержание статьи
- 1. Почему вам, скорее всего, не нужен составной PK у entity
- 2. Что рекомендуют Doctrine, Eloquent, Prisma и Hibernate
- 3. Один ID не отменяет бизнес-уникальность
- 4. Где составной идентификатор усложняет приложение
- 5. Когда составной ключ стоит оставить
- 6. Что делает --schema-rekey в ModernORMBundle
- 7. Пример: клиенты с составным PK и их заказы
- 8. Сначала проверить схему и сохранить план
- 9. Проверить значения и выбрать преобразования
- 10. Репетиция и финальная загрузка
- 11. Почему одинакового количества строк недостаточно
- 12. Какие схемы пока не пройдут
- 13. Что остаётся сделать после переноса
- 14. Версия, источники и проверка примеров
1. Почему вам, скорее всего, не нужен составной PK у entity
Составной PRIMARY KEY объединяет несколько колонок: например, организацию и номер клиента. База гарантирует уникальность пары, а все ссылки на эту запись должны учитывать обе части. Это корректная реляционная модель, но не всегда удобная идентичность объекта приложения.
Наш выбор для обычных entity — один стабильный технический ID, а бизнес-уникальность — отдельным UNIQUE. Клиент остаётся тем же объектом, даже когда меняется его номер в учётной системе. Для ссылок, событий, кеша и ORM используется один идентификатор.
Это рекомендация по устройству прикладной модели, а не запрет составных ключей в SQL. Таблицы связей, требования изоляции tenant и некоторые специализированные схемы требуют отдельного решения. Ниже разберём компромиссы и покажем, как перенести существующие составные ключи из MySQL в PostgreSQL через ModernORMBundle.
2. Что рекомендуют Doctrine, Eloquent, Prisma и Hibernate
У популярных ORM разная позиция: одна библиотека поддерживает составные ID, другая исключает их из модели. Нельзя превращать эти различия в утверждение «все ORM запрещают composite PK». В официальных документах на дату подготовки статьи указано следующее:
| ORM | Официальная позиция | Источник |
|---|---|---|
| Doctrine ORM | Поддерживает составные ключи, но рекомендует по возможности избегать их: они требуют дополнительной работы со стороны ORM. Это рекомендация для Doctrine, не универсальный закон проектирования БД. | Best Practices · Avoid composite keys |
| Laravel Eloquent | Составные PK у моделей не поддерживаются. Дополнительные составные уникальные индексы разрешены. Это ограничение Eloquent, а не SQL-возможностей Laravel. | Eloquent · Composite Primary Keys |
| Prisma ORM | Поддерживает составные ключи через @@id. В разделе Data modeling рекомендует избегать их у обычных моделей: все ссылающиеся записи должны хранить все компоненты. Типичный подходящий случай — модель связи. | Data modeling · Composite keys |
| Hibernate ORM | Поддерживает составные идентификаторы. Если выбранный естественный ключ может изменяться, рекомендует natural ID для бизнес-значения и surrogate ID для PK. Это условная рекомендация, не отказ от всех составных ключей. | User Guide · Identifiers |
Наш инженерный вывод из этих рекомендаций: бизнес-ключ полезен для проверки данных, но не обязан определять идентичность entity. Один ID уменьшает число компонентов, которые нужно согласованно передавать через слои приложения.
3. Один ID не отменяет бизнес-уникальность
Допустим, номер клиента уникален внутри организации. Добавление id не должно разрешать двух клиентов с одинаковой парой organization_id/customer_no. Ограничение сохраняется в базе:
-- Целевая PostgreSQL-таблица: пример для новой модели.
CREATE TABLE customers (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
organization_id INTEGER NOT NULL,
customer_no INTEGER NOT NULL,
name VARCHAR(100) NOT NULL,
UNIQUE (organization_id, customer_no)
);
PRIMARY KEY отвечает за адрес записи, UNIQUE — за правило предметной области. Проверка только в PHP не заменяет ограничение БД: параллельные запросы могут одновременно пройти предварительную проверку.
Цена такого решения тоже есть: новая колонка и дополнительный уникальный индекс. Это не бесплатная оптимизация хранения и не гарантия ускорения любого запроса. Выбор делается ради более простой идентичности и связей, а производительность измеряется на своих данных.
4. Где составной идентификатор усложняет приложение
- Связи. Дочерняя запись несёт все компоненты родительского ключа. В JOIN и FK нужно соблюдать их соответствие и порядок.
- API и сообщения. Идентификатор приходится передавать как структурированное значение. Неявная склейка строк добавляет риск неоднозначной сериализации.
- Identity Map и кеш. ORM должна приводить несколько значений к единому представлению идентичности. Технически это решаемо, но увеличивает поверхность поведения.
- Изменение бизнес-номера. Если он входит в PK, затрагиваются ссылки и семантика идентичности. Surrogate ID отделяет изменение реквизита от замены объекта.
- Инструменты. Не каждая ORM, административная панель или библиотека фоновых задач поддерживает одинаковый контракт составных ID.
При этом составной ключ из двух небольших чисел не обязательно хуже по размеру любого UUID. Добавление BIGINT не исправляет медленный SQL автоматически. В этой статье нет сравнительного бенчмарка индексов или ORM.
5. Когда составной ключ стоит оставить
Чистая ManyToMany-таблица часто идентифицирует именно пару: пользователь и роль, товар и категория. У неё нет самостоятельного жизненного цикла, а дубликат пары не имеет смысла. PRIMARY KEY (user_id, role_id) здесь естественен.
Если связь приобретает собственные документы, историю, внешние ссылки или состояние согласования, её стоит заново оценить как самостоятельную entity. Но наличие двух FK само по себе не обязывает вводить третий столбец id.
Есть и другие случаи: составной FK с tenant_id может обеспечивать запрет межорганизационных ссылок на уровне БД. Один глобальный ID не заменяет такую проверку. При переустройстве схемы нужно отдельно сохранить правила изоляции, авторизацию и ограничения ссылочной целостности.
Для существующей аналитической или предметно обоснованной схемы цена миграции может быть выше пользы. Сначала сформулируйте проблему, которую решает смена PK.
6. Что делает --schema-rekey в ModernORMBundle
Раньше таблица entity с составным PK блокировала обычный перенос. В unreleased добавлен независимый путь: modernorm:data:transfer --schema-rekey. Это стратегия внутри существующей команды.
Команда читает физические схемы MySQL и PostgreSQL, временно размещает исходные данные в PostgreSQL staging, назначает BIGINT ID и переносит связи на новые FK. Она не использует entity metadata для построения этого плана. Runtime ModernORM по-прежнему работает с одноколоночными ID: преобразование готовит схему под такую модель.
- Обычные entity с одним PK сохраняют исходные ID.
- Entity с составным PK получают новый BIGINT identity; исходные колонки сохраняются с полным UNIQUE в прежнем порядке.
- Ссылки на преобразованного родителя получают новый BIGINT FK; исходные FK-колонки также остаются.
- Чистые таблицы связей распознаются отдельно, а их итоговый PK строится из результирующих FK. Полные пары ManyToMany проверяются.
Важно: команда не создаёт финальные таблицы, не переписывает mapping и PHP-код и не переключает DATABASE_URL приложения. Целевая схема и новая модель готовятся до загрузки.
7. Пример: клиенты с составным PK и их заказы
Учебная MySQL-схема. У клиента ключ из организации и локального номера, заказ ссылается на всю пару:
-- MySQL: исходная схема.
CREATE TABLE customers (
organization_id INT NOT NULL,
customer_no INT NOT NULL,
name VARCHAR(100) NOT NULL,
PRIMARY KEY (organization_id, customer_no)
) ENGINE=InnoDB;
CREATE TABLE orders (
id BIGINT NOT NULL PRIMARY KEY,
organization_id INT NOT NULL,
customer_no INT NOT NULL,
FOREIGN KEY (organization_id, customer_no)
REFERENCES customers (organization_id, customer_no)
) ENGINE=InnoDB;
В PostgreSQL customers создаём как в главе 3. Для orders заранее готовим новую колонку customer_id, но сохраняем исходные поля:
-- PostgreSQL: после создания customers из главы 3.
CREATE TABLE orders (
id BIGINT NOT NULL PRIMARY KEY,
organization_id INTEGER NOT NULL,
customer_no INTEGER NOT NULL,
customer_id BIGINT NOT NULL,
FOREIGN KEY (customer_id) REFERENCES customers (id)
);
Например, пара (10, 501) получает customers.id = 1. Каждый её заказ получает customer_id = 1; поля organization_id/customer_no не удаляются. Новые ID выделяются как 1..N в точном порядке исходного PK, независимо от batch-size. Это внутренние идентификаторы, а не обещание сохранить их между разными составами источника.
Наличие старых колонок и нового FK не означает, что любое последующее изменение старой пары в orders автоматически синхронизируется с customer_id. После cutover прикладная модель должна определить, кто заполняет эти реквизиты и как поддерживается их согласованность. Rekey проверяет результат переноса, но не генерирует эту бизнес-логику.
8. Сначала проверить схему и сохранить план
Нужна сборка ModernORMBundle с commit 0f58c96 или последующий релиз с этой возможностью. На дату статьи режим находится в unreleased; установка beta.6 сама по себе его не добавляет. Источник — MySQL/InnoDB, цель — PostgreSQL 17+ для проверки значений.
php bin/console modernorm:data:transfer \
--schema-rekey \
--source-url-env=MYSQL_DATABASE_URL \
--target-url-env=REHEARSAL_POSTGRES_DATABASE_URL \
--dry-run --plan-output=rekey-rehearsal.yaml
URL-параметры принимают имена переменных окружения, не строки подключения. PostgreSQL-таблицы уже должны существовать и быть пустыми. Dry-run без --validate-data проверяет каталоги и структуру, а не все значения строк.
YAML-план необязателен: без --plan он строится в памяти при каждом запуске. --plan-output создаёт новый файл и не сохраняет заблокированный план для исполнения. План связывает цель, отпечатки схем, политику выполнения и хеш правил. Он не содержит паролей или снимка исходных строк.
Не редактируйте план как произвольный YAML: неизвестные поля, дубли ключей, aliases, tags и изменённый хеш отвергаются. После изменения схемы или содержимого правил нужен новый проверенный план. Для финальной базы создаётся отдельный план — файл для rehearsal нельзя просто направить на другой сервер.
9. Проверить значения и выбрать преобразования
php bin/console modernorm:data:transfer \
--schema-rekey \
--source-url-env=MYSQL_DATABASE_URL \
--target-url-env=REHEARSAL_POSTGRES_DATABASE_URL \
--dry-run --validate-data \
--rules=rules.json \
--change-log=rekey-validation.jsonl
Здесь rules.json — заранее подготовленный файл по контракту обычного data:transfer. Используются те же trim, replace и null_to. Они исправляют значения, но не назначают ID и не переписывают ключи. PK, FK и UNIQUE бизнес-колонки защищены; для UNIQUE expression index защита консервативно распространяется на все исходные поля таблицы.
php bin/console modernorm:data:transfer \
--schema-rekey \
--source-url-env=MYSQL_DATABASE_URL \
--target-url-env=REHEARSAL_POSTGRES_DATABASE_URL \
--dry-run --suggest-rules \
--rules-output=rules.proposed.json \
--plan-output=rekey-reviewed.yaml
Интерактивный режим сканирует источник, предлагает варианты с исходным выбором Skip, сохраняет принятые правила после просмотра и повторно проверяет данные. Он требует текстового dry-run без --change-log и не начинает загрузку. Если ошибки остаются, исполняемый план не сохраняется.
При использовании сохранённого плана передавайте тот же набор --rules: сверяется содержимое файла, а не только путь. JSONL фиксирует этапы validation/load и исходные ключи без значений полей. Записи о попытках загрузки могут остаться после rollback; журнал не является checkpoint для продолжения.
10. Репетиция и финальная загрузка
# Реальная загрузка в отдельную подготовленную rehearsal-базу.
php bin/console modernorm:data:transfer \
--schema-rekey --plan=rekey-reviewed.yaml \
--rules=rules.proposed.json \
--rehearsal --batch-size=1000 \
--change-log=rekey-rehearsal.jsonl --format=json
# Отдельный план, проверенный для финальной цели.
php bin/console modernorm:data:transfer \
--schema-rekey --plan=rekey-production.yaml \
--rules=rules.proposed.json \
--execute --batch-size=1000 \
--change-log=rekey-production.jsonl --format=json
Примеры — последовательность с заранее подготовленными файлами, не сценарий для запуска на случайной базе. Выбирается ровно один режим: --dry-run, --rehearsal или --execute. Rehearsal требует отдельную несистемную базу с именем, отличным от базы приложения.
Оба режима записи требуют офлайн-окна. Команда берёт FLUSH TABLES WITH READ LOCK на весь экземпляр MySQL, затем открывает read-only InnoDB snapshot. Блокировка держится до выяснения результата транзакции PostgreSQL. Это влияет и на другие базы того же MySQL-инстанса. Нужны права global SELECT и FLUSH_TABLES/RELOAD; ожидание блокировки ограничено 30 секундами, обхода без неё нет.
До запуска остановите запись в источник и трафик целевого приложения и workers. На PostgreSQL необходимы права на pg_control_system() для определения экземпляра, каталоги, временные таблицы, блокировку и загрузку финальных таблиц, owned sequences.
Цель использует одну READ COMMITTED транзакцию. Финальные таблицы блокируются от записи, их пустота и структура проверяются повторно. Raw/typed staging и таблицы соответствия ID временные. --batch-size ограничивает порции чтения и параметры, но не разбивает операцию на короткие транзакции.
11. Почему одинакового количества строк недостаточно
Если два заказа перепутали клиентов, общий COUNT(*) останется верным. Поэтому rekey проверяет не только объём, но и смысл каждой преобразованной ссылки:
- Повторно читает каждую строку источника и сравнивает её с raw staging.
- Заново применяет неизменные rules и проверяет typed-значения.
- Проверяет взаимно однозначное соответствие исходного ключа и нового ID.
- Проверяет конечные ключи и значения в обе стороны, а каждую новую связь — относительно исходного ключа родителя.
- Проверяет полные ManyToMany-пары, принудительно проверяет deferred constraints и синхронизирует sequences перед COMMIT.
Полный проход увеличивает стоимость переноса по времени и ресурсам. Это сознательная плата за проверяемый результат, а не обещание самой быстрой миграции.
| Поле target_data_committed | Как читать результат |
|---|---|
| true | COMMIT подтверждён. Дополнительно проверьте validation_complete и blockers. |
| false | Успешный COMMIT не подтверждён; транзакционные изменения откатываются. |
| null | Результат COMMIT неопределён. Проверьте цель до повторного запуска. |
В JSON также есть schema_rekey, stage, plan_hash, результат source fence и проверки таблиц/связей. Resume нет. После rollback операция повторяется целиком с пустой целью; sequences могут продвинуться даже при откате.
12. Какие схемы пока не пройдут
- Компоненты преобразуемых PK и переназначаемых FK должны быть ненулевыми целыми числами. Строковые natural keys этим режимом не преобразуются. Новый ID — signed BIGINT; исходные unsigned-значения при необходимости сохраняются в явно подготовленном NUMERIC(...,0).
- Ссылки за пределы исходной БД, ссылки на альтернативный UNIQUE вместо PK, nullable composite FK, self-reference и циклы блокируют операцию.
- Не поддерживаются входящие ссылки на чистую join table и цепочки rekey через идентификаторы или referenced keys дочерних таблиц.
- Все исходные таблицы и колонки должны быть покрыты. Нет переименования, выборочного переноса и автоматического удаления старых ключей.
- Дополнительные целевые колонки допускаются только как запланированные новые ID/FK. RLS, partitioning/inheritance, пользовательские triggers, rewrite rules и некорректные indexes/constraints блокируют перенос.
- Нет генерации финального DDL, UUID-аллокатора, переписывания entity, CDC, resume и автоматического cutover.
Сравнивайте возможности с обычным data:transfer: это отдельная стратегия с более строгими требованиями. Сценарий с произвольными бизнес-триггерами, допустимый в одном режиме, нельзя автоматически считать поддерживаемым в rekey.
13. Что остаётся сделать после переноса
После выхода команды MySQL read fence освобождается. Ответственный за переключение должен удерживать остановку записи до смены подключений: автоматического догоняющего переноса нет. Успешный COMMIT PostgreSQL не означает, что приложение уже работает на новой базе.
- Адаптировать entity и связи к одному ID, сохранив UNIQUE и нужные бизнес-ограничения.
- Проверить документы, права, суммы, поиск, отчёты и изоляцию организаций.
- Согласовать новые ID с внешними системами, событиями и кешами: внутренний rekey не переписывает чужие ссылки.
- Определить поведение исходных колонок после cutover и только отдельно планировать их очистку.
- Зафиксировать переключение приложения, проверку результата и порядок отката.
В новом проекте зачастую проще сразу отделить техническую идентичность от бизнес-реквизитов. В существующем PostgreSQL-проекте с простыми ID можно оценить ModernORM по возможностям ORM. Для MySQL-проекта с composite PK новый режим снимает часть ручной работы: назначения ID, загрузки и восстановления связей в пределах поддерживаемого контракта.
Подробный маршрут обычного переезда разобран в статье о миграции MySQL → PostgreSQL; runtime и mapping — в обзоре ModernORM.
14. Версия, источники и проверка примеров
Материал подготовлен 21 ноября 2026 года. Поведение rekey сверено с документацией и реализацией ModernORMBundle на commit 0f58c96. Это unreleased после beta.6. SQL и CLI-примеры учебные; реальную миграцию с блокировкой MySQL при подготовке статьи мы не запускали. Проверка статей не заменяет репетицию на копии вашей схемы.