Download the PHP package timbrs/database-dumps without Composer

Database Dumps Package

[]() []() []()

English

Русский язык

PHP-пакет для экспорта и импорта дампов баз данных в SQL. Поддерживает PostgreSQL, MySQL и Oracle (12c+). Работает с Symfony, Laravel и любым PHP-проектом.

Оглавление

• Описание
• Возможности
• Установка
• Быстрый запуск (LLM + OPENCODE)
• Быстрый старт
  • Symfony
  • Laravel
• Конфигурация
  • Полный экспорт (full_export)
  • Частичный экспорт (partial_export)
  • Каскадные зависимости (cascade_from)
  • Замена персональных данных (faker)
  • Разделение конфига по схемам (includes)
  • Несколько подключений
  • Настройки (settings)
  • Автогенерация конфигурации
• Углублённый анализ (LLM + OPENCODE)
  • Настройка LLM (интерактивно)
  • LLM-детекция ПД и профилирование
  • Анализ кода через OPENCODE
• Проверка конфига без БД (validate)
• Настройка Symfony
  • Регистрация бандла
  • Структура каталогов (Symfony)
  • Команды Symfony
• Настройка Laravel
  • Регистрация провайдера
  • Публикация конфигурации
  • Команды Laravel
• Скрипты before/after
• Поддержка IDE (JSON Schema)
• Архитектура
  • Как работает экспорт
  • Как работает импорт
  • Различия платформ
  • Структура исходного кода
• Безопасность
• Тестирование
• Локальная разработка
• Требования
• Лицензия

Описание

Database Dumps — это PHP-пакет, который помогает разработчикам создавать и разворачивать дампы базы данных для локальной и тестовой среды.

Какую проблему решает? На проекте с большой боевой базой разработчику нужно иметь актуальные тестовые данные — но копировать всю базу долго, а персональные данные клиентов нельзя использовать в dev-окружении. Этот пакет позволяет настроить правила экспорта один раз: какие таблицы забирать целиком, какие — частично, и забыть о ручной подготовке дампов.

Как работает? Вы описываете в YAML-файле, какие таблицы и как экспортировать. Пакет сам:

• генерирует SQL-дампы из боевой (или staging) базы с учётом FK-зависимостей между таблицами
• заменяет персональные данные (ФИО, email, телефоны) на сгенерированные, чтобы дампы были безопасны
• разворачивает дампы в нужную базу одной командой, с защитой от случайного запуска на продакшене

Где применим? В любом PHP-проекте на Symfony или Laravel (или без фреймворка), где нужно:

• быстро разворачивать тестовую базу для разработчиков
• передавать дампы между командами без утечки персональных данных
• держать seed-данные в репозитории и обновлять их из реальной базы
• работать с несколькими базами данных одновременно

Возможности

• Не привязан к фреймворку — работает с Symfony, Laravel и любым PHP-проектом
• PostgreSQL, MySQL и Oracle — автоматически генерирует правильный SQL для каждой СУБД
• Несколько подключений — экспорт/импорт сразу из нескольких баз данных
• Пакетные INSERT — автоматическая группировка по 1000 строк на выражение
• Откат при ошибках — импорт выполняется в транзакции
• Защита от продакшена — импорт заблокирован при APP_ENV=prod
• Скрипты до/после — свои SQL-скрипты до и после импорта
• Гибкая настройка — YAML-файл с правилами полного и частичного экспорта
• Сброс счётчиков — автоматический сброс sequence / auto-increment после импорта
• Автогенерация конфига — команда prepare-config создаёт YAML по структуре БД
• FK-сортировка — автоматическая топологическая сортировка таблиц при экспорте и импорте (родители первыми)
• Каскадные зависимости — cascade_from генерирует WHERE-подзапросы для связности данных через FK
• Замена ПД (faker) — автоматическое обнаружение и замена персональных данных (ФИО, email, телефон, пол) при экспорте
• Разделение конфига — автоматическое разбиение конфигурации на отдельные файлы по схемам
• Smart Cycle Breaking — автоматический разрыв циклических FK-зависимостей (двухфазный INSERT NULL → UPDATE) вместо fallback на алфавитный порядок
• Self-referential FK — поддержка таблиц со ссылками на себя (деревья категорий, оргструктуры, комментарии)
• Валидация схемы при импорте — предупреждение при расхождении столбцов дампа и БД, опция --ignore-schema-mismatch
• Настройки в конфиге — секция settings: для batch_size, sample_size, max_cascade_depth
• Dry-run экспорт — опция --dry-run для просмотра плана экспорта без выполнения
• ИИ-анализ данных (LLM) — точная классификация ПД, профилирование колонок и подсказки по выборке через OpenAI-совместимый LLM; при первом запуске пакет интерактивно спрашивает URL/модель/token и запоминает их
• ИИ-анализ кода (OPENCODE) — обнаружение связей без FK и бизнес-сегментов в коде хост-приложения (Eloquent/Doctrine/сырые JOIN) → авто-обогащение cascade_from и sample.criteria
• Выборка по критериям (sample) — набор именованных «корзин» (red/new/inactive/vip…) с дедупом по PK — «все фломастеры»

Установка

Быстрый запуск (LLM + OPENCODE)

Рекомендуемый, основной сценарий — анализ с участием ИИ. Пакет использует два источника:

• Прямой LLM (OpenAI-совместимый API, например openai/gpt-oss-120b) — для анализа данных: точная классификация ПД (faker), профилирование колонок, подсказки по выборке.
• OPENCODE (внешний агент) — для анализа кода хост-приложения: связи без FK, бизнес-сегменты (scopes/репозитории) → sample.criteria, карта «колонка → код».

Без настроенного LLM пакет тоже работает — анализ деградирует на regex-эвристики. Но рекомендуется именно LLM-сценарий.

Шаг 1. Сгенерировать конфиг (при первом запуске пакет сам спросит про LLM)

При первом запуске, если настройки LLM ещё не заданы, команда спросит:

1. Настроить LLM сейчас? — да/нет (по умолчанию да);
2. API URL — базовый адрес OpenAI-совместимого API (например https://gpt.example.com/v1);
3. Модель — имя модели (по умолчанию openai/gpt-oss-120b);
4. Token — Bearer-токен; можно оставить пустым (Enter).

Несекретные ответы (URL/модель) сохраняются в файл настроек — config/packages/database_dumps.yaml (Symfony) / config/database-dumps.php (Laravel), а Token — в .env.local (DBDUMP_LLM_TOKEN, при отсутствии — в .env); настройки применяются сразу в этом же запуске. Повторно спрашивать не будет. Если откажетесь — выбор тоже запомнится (анализ пойдёт на regex); включить позже — командой configure-llm (см. ниже).

ℹ️ Токен в файл настроек не пишется — он хранится в .env.local, поэтому файл настроек безопасно коммитить. В Symfony бандл регистрируется только вне prod.

Результат: dump_config.yaml (+ per-schema файлы) с автоопределёнными full_export/partial_export, секцией faker (LLM-детекция ПД) и каскадами по FK.

Шаг 2 (опционально). Обогатить конфиг анализом кода через OPENCODE

Нужен установленный opencode в PATH и настроенный в нём провайдер LLM (~/.config/opencode/opencode.json).

Команда сгенерирует в хост-проект всё необходимое для внешнего агента:

• docker/database/analysis/schema_inventory.json + schema_inventory.<schema>.json — инвентарь БД для агента (без значений данных — PII не выгружается);
• docker/database/analysis/output_schema.json — контракт JSON-вывода;
• docker/database/analysis/out/ — куда агент кладёт результат.

Документацию инструмента (рабочий цикл, команды, коды находок) генерирует app:dbdump:docs в docker/database/analysis/docs/ — она собирается из самого кода и потому не устаревает отдельно от него.

Команда собирает пакет и печатает, где он лежит; агента она не запускает — это делается снаружи (см. Анализ кода через OPENCODE). Результат агента (связи из кода → cascade_from: source: code, бизнес-сегменты → sample.criteria) применяет apply-analysis; отчёт — в {data_dir}/analysis/REPORT.md. Пользовательские правки в YAML в приоритете.

Шаг 3. Экспортировать и импортировать дампы

Переконфигурировать LLM в любой момент

Интерактивно меняет URL/модель/token, умеет проверить соединение и пересохранить настройки: несекретное — в файл настроек config/packages/database_dumps.yaml (Symfony) / config/database-dumps.php (Laravel), токен — в .env.local (DBDUMP_LLM_TOKEN).

Быстрый старт

Symfony

1. Зарегистрируйте бандл вручную в config/bundles.php (Flex-рецепта нет):

2. Создайте файл docker/database/dump_config.yaml (путь по умолчанию; переопределяется ключом config_path):

3. Экспортируйте дампы:

4. Импортируйте дампы:

Laravel

1. Сервис-провайдер подключается автоматически. Файл docker/database/dump_config.yaml создаётся при первом запуске.

2. Отредактируйте docker/database/dump_config.yaml (формат тот же, что и для Symfony).

3. Экспортируйте дампы:

4. Импортируйте дампы:

Конфигурация

Экспорт настраивается через YAML-файл. В нём две секции: full_export (все строки) и partial_export (с ограничениями).

Полный экспорт (full_export)

Экспортирует все строки из указанных таблиц:

Частичный экспорт (partial_export)

Экспортирует часть строк с фильтрацией:

Доступные опции:

Каскадные зависимости (cascade_from)

При частичном экспорте связанных таблиц данные могут стать несогласованными: дочерняя таблица может ссылаться на строки, которые не попали в дамп родителя. Опция cascade_from решает эту проблему — она автоматически генерирует WHERE-подзапрос, ограничивающий выборку только теми строками, чей FK-родитель присутствует в дампе.

В этом примере:

• orders экспортирует только те заказы, чей user_id есть среди экспортированных users
• order_items экспортирует только позиции заказов, попавших в дамп orders
• Подзапросы вложенные: order_items → orders → users (глубина до 10 уровней)

Команда prepare-config автоматически определяет FK-зависимости и генерирует cascade_from. Чтобы отключить: --no-cascade.

Выборка по именованным критериям (sample)

Иногда нужно набрать «все фломастеры» — по 10–100 строк каждого бизнес-сегмента (красные/жёлтые/зелёные по статусу, новые/старые по дате, неактивные, VIP…), часто по разным колонкам и кросс-таблично. Опция sample задаёт набор именованных «корзин», каждая со своим WHERE и квотой; итоговая выборка — объединение всех корзин без дублей (дедуп по первичному ключу).

Как это работает:

• Фаза 1 — по каждой корзине выбираются первичный ключ и колонки, на которые ссылаются дети: SELECT <pk>[, <parent_column>…] FROM clients WHERE (<where>) AND (<cascade_from>) AND (<crit.where>) [ORDER BY ...] LIMIT <crit.limit>. stratify_by (колонка или список колонок) разворачивается в по-корзине на каждое DISTINCT-значение: значения берутся из статистики планировщика (pg_stats), когда она полная, иначе SELECT DISTINCT … LIMIT 51 — потолок 50 корзин, лишнее значение выдаёт усечение. На большой таблице без каскада и без статистики DISTINCT был бы полным сканом — корзины пропускаются с предупреждением.
• Квота под limit — если per_value × корзин > limit, квота корзины заранее ужимается до ⌊limit/корзин⌋ (но не ниже 5): покрытие видов данных важнее объёма.
• Дедуп и слияние — строки всех корзин объединяются без повторов. Если объединение больше limit, корзины сливаются round-robin (по строке из каждой по кругу): ни одна корзина не теряется целиком.
• Фаза 2 — финальный SELECT * FROM clients WHERE <pk> IN (...) (для составного PK — дизъюнкция равенств; список длиннее 1000 значений режется на несколько IN через OR).

Требования и поведение:

• У таблицы должен быть первичный ключ (нужен для дедупа). criteria[].where проходит ту же проверку, что и обычный where (запрет ; и SQL-комментариев, баланс кавычек/скобок) — корректные EXISTS (...) допускаются. name — идентификатор, limit — целое ≥ 1.
• Cascade-консистентность: если у родителя задан sample, дочерние таблицы (cascade_from) ссылаются на фактически выбранные значения родителя — в реестр попадают и PK, и колонки, по которым на родителя ссылаются дети (parent_column: core_id у версионных таблиц), — а не повторяют критерии подзапросом.
• sample и cascade_from на одной таблице совместимы: каскад входит в базовое условие каждой корзины, и «все виды» набираются среди строк, связанных с выгруженным родителем. Пустая корзина у такого ребёнка значит, что родитель не дал связанных строк этого вида (G-6 — заметка валидатора об этом).
• После export all в {data_dir}/analysis/sample-report.json лежит ход выборки: по таблице — корзины (квота, строк, миллисекунды, ошибка), источник и усечение значений stratify_by, потолок и усечение объединения. Значения корзин показываются только если похожи на код (^[A-Za-z0-9_.\-]{1,32}$) и колонка не выглядит как ПД; остальные корзины именуются <колонка>#<номер>.

Вложенная и обратная стратификация

«Сто зелёных закрытых» — корзина на пару значений двух колонок, и «цвет клиента», который живёт не в clients, а в clients_attrs.value_string при attr_id = 4, — обе задачи решаются в той же секции sample:

• stratify[].then — один уровень вложенности (глубже число корзин растёт как произведение, и квота ужмётся в ноль). Значения второго уровня берутся SELECT DISTINCT <then.column> … WHERE (<base>) AND <column> = V LIMIT max_values + 1 — фильтр по первому уровню делает запрос выборочным. Корзина именуется attr_id#0/value_int#3; если второго уровня у значения нет, остаётся корзина первого уровня с его квотой.
• stratify_via[] — значения column читаются на дочерней таблице (SELECT DISTINCT … WHERE (<where>) LIMIT 51, обычно по индексу attr_id), а корзины у родителя строятся условием EXISTS (SELECT 1 FROM <table> _via WHERE _via.<k> = <родитель>.<k> AND (<where>) AND _via.<column> = V) с квотой per_value. Так «сто красных, сто зелёных» из атрибутов попадают в выборку clients, а clients_attrs подтягивается каскадом.
• Квоты обоих видов ужимаются под limit так же, как у stratify_by; строковые значения в sample-report.json показываются только для кодов, для ПД-колонок — номер корзины.

Авто-генерация: с флагом --criteria (или --deep) prepare-config профилирует категориальные колонки и сам предлагает sample.criteria (по корзине на топ-значение). Бизнес-сегменты из кода (Eloquent scopes, методы репозиториев) добавляются через ветку OPENCODE — см. Углублённый анализ.

Замена персональных данных (faker)

Пакет может автоматически обнаруживать и заменять персональные данные при экспорте. Это позволяет безопасно использовать дампы в dev/staging окружениях.

Поддерживаемые паттерны:

Секция faker в конфигурации:

Паттерны firstname, lastname и patronymic детектируются через кросс-корреляцию: если в таблице уже найдена составная колонка (fio, fio_short, name), а рядом есть колонка с отдельными именами/фамилиями/отчествами — она будет обнаружена автоматически.

Паттерны inn, ogrn, digits, birth_date, doc_series и doc_number выводятся из значения: одинаковый вход даёт одинаковый выход в любой таблице и в любом прогоне. Иначе один и тот же ИНН превратился бы в clients в одно число, а в leads — в другое, и связь между записями в дампе разошлась бы. Длина, разделители и формат даты сохраняются, поэтому такой faker годится и для числовых колонок (bigint), и для date/timestamp.

Паттерн gender определяется по совпадению имени колонки (gender, sex, пол) и содержимого (допустимые значения: male/female, m/f, м/ж, мужской/женский, муж/жен, мужчина/женщина). Регистр и формат оригинала сохраняются при замене.

Команда prepare-config автоматически анализирует содержимое таблиц и генерирует секцию faker, если в колонках обнаруживаются паттерны ПД (порог совпадения: 80% из 200 случайных строк). Чтобы отключить: --no-faker.

Замена детерминирована — seed основан на хеше значения ФИО (колонка с паттерном fio), если такая колонка есть в конфигурации таблицы. Если колонки fio нет — seed берётся от хеша комбинации всех faker-значений строки. Это гарантирует, что одна и та же персона всегда получает одинаковую замену независимо от таблицы и запуска.

Разделение конфига по схемам (includes)

При большом количестве таблиц конфигурация может стать громоздкой. Команда prepare-config по умолчанию разбивает конфиг на отдельные файлы по схемам. Главный dump_config.yaml лежит в docker/database/, а пер-схемные файлы — в подкаталоге docker/database/dump-settings/:

Главный файл (docker/database/dump_config.yaml):

💡 Пути к include пишутся с префиксом ./ — так PhpStorm/IDE распознают их как ссылки на файлы: Ctrl+B / Cmd+B (или Ctrl+клик) на пути прыгает прямо в нужный *.yaml. На резолв путей загрузчиком префикс не влияет (работают оба варианта — с ./ и без).

Файл схемы (docker/database/dump-settings/public.yaml):

Чтобы генерировать единый файл без разделения: --no-split.

Несколько подключений

Если нужно работать с несколькими базами данных, добавьте секцию connections:

Куда сохраняются дампы:

• Основное подключение: {data_dir}/dumps/{schema}/{table}.sql
• Именованное подключение: {data_dir}/dumps/{connection}/{schema}/{table}.sql

data_dir — базовый каталог данных (по умолчанию docker/database), от него считается всё, что порождает пакет: главный конфиг ({data_dir}/dump_config.yaml), пер-схемные файлы ({data_dir}/dump-settings), дампы ({data_dir}/dumps), анализ ({data_dir}/analysis) и хуки ({data_dir}/before_exec, {data_dir}/after_exec). Изменить можно ключом data_dir в файле настроек — config/packages/database_dumps.yaml (Symfony) / config/database-dumps.php (Laravel) — или через env DBDUMP_DATA_DIR. В prod всегда используется дефолт docker/database.

Смена дефолта в 1.1.23. Раньше дефолтом был database, а путь к dump_config.yaml был зашит отдельной константой и не следовал за data_dir. Теперь дефолт — docker/database, и конфиг живёт внутри data_dir вместе с дампами. Установка, которая полагалась на прежний дефолт (ключ data_dir не задан), после обновления перестанет видеть свои файлы — пропишите data_dir: 'database' либо перенесите каталог.

Опция --connection:

Настройки (settings)

Секция settings позволяет изменять внутренние параметры пакета:

Автогенерация конфигурации

Команда prepare-config смотрит на структуру БД и создаёт или обновляет dump_config.yaml. Обязательный аргумент mode определяет область действия:

Режимы:

Режим all собирает конфиг заново и существующий файл не читает: настроенные вручную sample.criteria, cascade_from, limit и faker он заменяет машинной догадкой. Поэтому при существующем dump_config.yaml команда отказывается работать и называет режимы, которые мёржат, а не затирают (new, schema=, table=), а также check-criteria и validate. Осознанная пересборка с нуля — prepare-config all --force.

Опции:

Как распределяются таблицы:

• Строк <= порога — full_export
• Строк > порога — partial_export (с limit, автоопределённой сортировкой и шаблоном where: "1=1" для удобства редактирования)
• Пустые таблицы — пропускаются
• Служебные таблицы (migrations, sessions, cache*, telescope, oauth_, audit_*) — пропускаются

Углублённый анализ (--deep / --ai / --criteria)

Анализ с участием ИИ — основной сценарий пакета. Опирается на два источника:

• Прямой LLM (openai/gpt-oss-120b по OpenAI-совместимому API) — анализ данных: PII-классификация точнее regex, профилирование, подсказки по выборке. Запросы ограничены по размеру.
• OPENCODE (внешний агент) — анализ кода целиком: связи без FK (Eloquent belongsTo/hasMany, Doctrine-ассоциации, сырые JOIN), карта «колонка → код», ключевые поля и бизнес-сегменты. Пакет готовит вход и инструкции, агент возвращает JSON, который пакет поглощает.

Если LLM не настроен, анализ мягко деградирует на regex-эвристики — пакет остаётся работоспособным. См. также Быстрый запуск.

Настройка LLM (интерактивно)

При первом запуске prepare-config (если настройки LLM ещё не заданы и сессия интерактивна) пакет сам предложит настроить LLM — спросит API URL, Модель и Token (token можно оставить пустым), сохранит несекретное в файл настроек, токен — в .env.local (DBDUMP_LLM_TOKEN), и применит настройки немедленно в этом же запуске. Отказ тоже запоминается, чтобы не спрашивать снова. Авто-запрос подавляется флагом --no-ai и в неинтерактивном режиме (--no-interaction, CI).

Настроить или изменить LLM в любой момент можно явной командой — она дополнительно умеет проверить соединение:

После настройки --ai/--deep и prepare-analysis подхватывают параметры автоматически. Приоритет источников: переменные окружения DBDUMP_LLM_* (если задан URL) перекрывают файл настроек config/packages/database_dumps.yaml (Symfony) / config/database-dumps.php (Laravel); токен всегда берётся из окружения (.env.local → .env) и в файл настроек не пишется.

LLM-детекция ПД и профилирование

• --ai использует LLM для классификации ПД (regex-результаты подаются как hints; принимаются типы с уверенностью выше порога, маппятся на fio/email/phone/...). При недоступном LLM — тихий fallback на regex + предупреждение.
• --criteria профилирует категориальные колонки и предлагает sample.criteria (по корзине на топ-значение).
• --deep включает всё перечисленное + пишет отчёт docker/database/analysis/REPORT.md (+ машинный analysis_result.json): режим экспорта, предложенные критерии с SQL и обоснованием, ПД (regex vs LLM), профиль колонок.

Переменные окружения LLM:

HTTP-запросы выполняются через ext-curl (без guzzle). Данные PII в промптах ограничены примерами значений колонок.

Анализ кода через OPENCODE

Пакет не запускает агента. До 1.1.26 prepare-analysis --run дёргал opencode через exec() из PHP — и это оказалось неверным слоем. Агент сам решает, чем и в каком порядке пользоваться, и умеет вызвать prepare-analysis, validate и check-criteria куда осмысленнее, чем PHP умеет вызвать агента. За пакетом осталась детерминированная часть: собрать факты (инвентарь схемы, находки валидатора, падающие criteria с ошибкой СУБД) и применить готовый результат (apply-analysis). Решения — эвристики, починка, выбор режима выгрузки — снаружи. В пакете не осталось ни одного вызова внешнего процесса.

Самый простой путь — одной командой (нужен opencode в PATH):

Команда собирает пакет (инвентарь схемы, пер-схемные инвентари, контракт вывода) и печатает, где он лежит. Прогон агента — снаружи; применение результата — apply-analysis.

Ручной путь (3 шага) — если хотите контролировать прогон агента:

Что провижинит prepare-analysis в хост-проект:

• docker/database/analysis/schema_inventory.json — полный инвентарь + schema_inventory.<schema>.json по каждой схеме (для прогона по чанку без переполнения контекста 128k), без значений данных (PII агенту не выгружается);
• docker/database/analysis/dossier.<schema>.json — досье по каждой таблице и колонке: слепок, оценка строк, связи (db_fk + cascade_from), enum'ы из кода с доказательствами, миграции, вьюхи, признаки SCD2/словаря/EAV и пометки ambiguous — именно с ними идут к агенту по коду;
• docker/database/analysis/decisions.<schema>.json — предложения по конфигу (правила R1…R11): что менять, на что и почему, со ссылками на доказательства;
• docker/database/analysis/decisions_schema.json — контракт этого файла;
• docker/database/analysis/output_schema.json — JSON-контракт ответа агента (старый формат);
• docker/database/analysis/out/ — каталог для результата агента.

Решения (decisions.<schema>.json)

Правила читают досье и предлагают правки. Тулза применяет сама только механическое — записи с auto: true:

Значений данных в решениях нет: только имена таблиц, колонок и case'ов enum'ов. id записи считается от адреса и предложения, поэтому отметка accepted переживает повторный analyze, а изменившееся предложение придётся принимать заново.

Изменено в 1.1.32. Пакет больше не кладёт .opencode/agents/dbdump-mapper.md, .opencode/commands/dbdump-map.md и analysis/RUN.md: инструкция устаревала отдельно от кода. Её место заняли app:dbdump:docs (документация из самого инструмента) и политика запуска агента в проекте.

Применение: apply

Записывает решения в dump_config.yaml. Три правила, которые не обойти:

• auto применяется само — маскирование колонки с ПД-именем, связь по внешнему ключу БД, удаление таблицы, которой в базе нет, замена заведомо неподходящего паттерна. Всё, что меняет состав выборки, ждёт отметки accepted от агента по коду или от человека. accepted: false — отказ, он сильнее auto.
• Существующее значение в YAML побеждает без override: конфиг правят руками, и затирать ручную настройку молча нельзя. criteria и cascade_from при этом накапливаются — новое ребро или сегмент дописывается, совпадение по имени (или по паре parent+fk_column) пропускается.
• Решение из устаревшего конфига не применяется. Если current записи разошёлся с тем, что сейчас в YAML, значит между анализом и применением конфиг поправили: запись помечается stale и пропускается. Перезапустите prepare-analysis.

Предложение проверяется через TableConfig::fromArray() до мутации, поэтому битая запись не оставляет конфиг полуприменённым. Итог с провенансом (правило, обоснование, доказательства, статус) — в docker/database/analysis/apply-report.json; изменённый YAML пишется только если хоть одно решение применилось.

Старый вывод агента (analysis/out/*.json) тот же вызов применяет по-прежнему: cascade_from из кода и sample.criteria из бизнес-сегментов, пользовательские правки в приоритете, провенанс в docker/database/analysis/REPORT.md. Кроме того, prepare-analysis показывает его в новом виде — связи и сегменты как решения с rule: legacy (всегда требуют отметки), а columns[] как заметки агента в досье: раньше они просто выбрасывались.

Для больших схем дробите прогон по чанку на схему — пер-схемные инвентари для того и пишутся.

Одна команда проверки: check

check прогоняет все проверки и складывает находки в одно пространство кодов. Стадии выбираются по тому, что доступно, и каждая честно докладывает, почему пропущена:

Опции: --stage (повторяемая; по умолчанию все, кроме plan), -s|--schema, --tables-from (файл со списком schema.table или dirty.json), --config, --inventory, -c|--connection, --import-connection, --fail-on=error|warning|note (порог кода возврата 1), --fix, --format=text|json, --out.

Отчёт — один JSON: {generated_at, run_id, stages:{ran, why_skipped, ms, queries, …}, summary, coverage, findings[]}, у каждой находки есть stage. Узкие команды validate, check-criteria и verify-dump остаются рабочими: это подмножества check с прежними опциями.

Документация из инструмента: docs

docs пишет четыре файла: WORKFLOW.md (рабочий цикл), DOSSIER.md (что лежит в dossier.<schema>.json и что означают пометки ambiguous), COMMANDS.md (собран из определений команд — те же опции, что в --help), FINDINGS.md (реестр кодов: стадия, уровень, смысл, чинится ли --fix, кто решает). Это же кладут в проект для агента, чтобы он не гадал по устаревшему мануалу.

Паритет мостов Symfony и Laravel

Ядро пакета общее, различаются только консольные мосты. Восемь исходных команд работают в обоих; новые — только Symfony, и Laravel-мост заморожен: новые зависимости в нём nullable, код PHP 7.2-совместимый.

Laravel-команда dbdump:apply-analysis применяет только старый вывод агента (analysis/out/*.json); решения decisions.<schema>.json читает Symfony-мост.

Инкремент: checkpoint и грязный набор

Первый прогон — полный, дальше перепроверять всё незачем. Отметка docker/database/analysis/checkpoint.json хранит самую новую миграцию, время слепка, коммит и хеши по каждой таблице: настройки, состав колонок, набор кодов, внешние ключи. Времени мало — конфиг могли поправить и вернуть, а в базе за неделю мог появиться новый status_id без единой миграции; хеш это ловит, время нет.

Четыре сенсора:

Результат — docker/database/analysis/dirty.json с причиной по каждой таблице; он подаётся дальше как есть (check --tables-from=…/dirty.json), а --since-checkpoint делает то же одним флагом. Отдельно в отчёте видно таблицы, которые миграция завела, а конфиг не знает (повод дозапустить prepare-config), и те, что исчезли из конфига после отметки.

Границы честности сенсоров. На схлопнутой истории (clone --depth=1, а в закрытом контуре это норма) git diff по старому коммиту невозможен: сенсор докладывает, что отключён, и работают остальные три — молча объявлять всё чистым он не станет. Слепок сравнивается тем же кодом, что считает хеши для новой отметки, поэтому расхождение формул не превратится в вечно грязный набор. Отметки нет — грязное всё, и это значит «нужен полный цикл», а не «изменений не найдено».

--save — отдельный флаг: случайно перезаписать отметку нельзя, а посмотреть грязный набор можно в любой момент.

Проверка конфига без БД (validate)

validate проверяет dump_config.yaml и пер-схемные dump-settings/*.yaml, не подключаясь к базе. Схему берёт из замороженного слепка {data_dir}/analysis/schema_inventory.json (и пер-схемных schema_inventory.<schema>.json), который кладёт prepare-analysis. Поэтому команда работает в CI, в закрытом контуре и до подъёма стенда — в отличие от check-criteria, который гоняет каждый criterion по живой БД.

Опции: --config и --inventory (пути, по умолчанию — {data_dir}/dump_config.yaml и {data_dir}/analysis/schema_inventory.json), -s|--schema (повторяемая, только эти схемы), --format=text|json, --out=PATH, --severity=error|warning|note (порог вывода), --fix (применить механически однозначные правки).

Код возврата — 1, если есть находки уровня error, иначе 0. Этого достаточно, чтобы скрипт или агент решил «готов конфиг к снятию дампа или нет», не разбирая текст вывода.

Что проверяется

G-4 заслуживает отдельного слова. Порядок экспорта строит TopologicalSorter по FK из слепка; в базе без FK-констрейнтов рёбер нет вовсе, и порядок вырождается в алфавитный. Тогда родитель, чьё имя идёт позже имени ребёнка, попадает в дамп уже после него, реестр выбранных id (SelectedPkRegistry) пуст, и CascadeWhereResolver откатывается к подзапросу, который не повторяет sample.criteria — набор строк родителя в дампе и в подзапросе расходится.

Что делает --fix

Только то, где правка однозначна и не меняет состав выборки: снимает faker-маппинг с нетекстовой колонки (F-1) и с неизвестным паттерном (F-2), убирает маппинг несуществующей колонки (L-6) и мёртвую запись cascade_from (L-3), переименовывает дубль критерия (Q-4), удаляет пустую секцию (S-4). Всё остальное остаётся находкой с подсказкой — решение за человеком.

Правки пишутся в тот файл, откуда пришла схема (dump-settings/<schema>.yaml или общий конфиг); тронутый файл переписывается целиком, поэтому его форматирование становится каноническим (записи cascade_from разворачиваются из однострочной формы в блочную). Файлы, где чинить нечего, не трогаются. После правок содержимое перепроверяется тем же TableConfig, что и на экспорте: если правка сделала конфиг хуже, файл не записывается.

Проверяется только основное подключение; секция connections: в аудит не входит.

Проверка выгруженных дампов (verify-dump) и отчёт импорта

verify-dump смотрит на то, что реально легло в {data_dir}/dumps/, — validate и check-criteria туда не заглядывают. К БД не подключается; каждый файл читается один раз для всех проверок, наружу уходят только счётчики и имена колонок — значений данных в отчёте нет.

Опции: -s|--schema, -c|--connection, --inventory (слепок схемы, по умолчанию {data_dir}/analysis/schema_inventory.json; без слепка проверки по нему пропускаются с пометкой в отчёте), --format=text|json, --out=PATH. Код возврата — 1 при ошибках.

Рёбра для V-1 — объединение cascade_from и внешних ключей из слепка (foreign_keys): сегодня в базе без констрейнтов второй список пуст, но появись FK — связь проверяется без правки конфига.

import возвращает отчёт с теми же правилами игры: ошибки в нём дают код возврата 1, даже если транзакция прошла; --out=PATH пишет отчёт в JSON.

Настройка Symfony

Регистрация бандла

Flex-рецепта у пакета нет, поэтому бандл нужно зарегистрировать вручную. Добавьте в config/bundles.php:

Регистрация в dev/test соответствует установке через composer require --dev. Если пакет ставится в prod (без --dev), регистрируйте бандл как ['all' => true].

Настройки бандла

Все настройки живут в одном файле config/packages/database_dumps.yaml под корневым ключом database_dumps:. Файл необязателен — без него работают дефолты.

⚠️ Если бандл зарегистрирован как ['dev' => true, 'test' => true] (рекомендованный вариант выше), секцию ОБЯЗАТЕЛЬНО оборачивать в when@dev: / when@test:. Файлы config/packages/*.yaml грузятся во всех окружениях, а расширения database_dumps в prod нет — голый корневой ключ уронит сборку контейнера: There is no extension able to load the configuration for "database_dumps". Так же устроены штатные web_profiler.yaml и debug.yaml. При регистрации ['all' => true] обёртка не нужна.

Полный список ключей (здесь без обёртки, для случая ['all' => true]):

jobs больше не служебная (1.1.34). Раньше это имя было в жёстком списке, и вместе с очередью Laravel из инвентаря молча пропадала бизнес-таблица с тем же именем. Очередь по-прежнему ловится по failed_jobs/job_batches; если в вашем проекте jobs — это действительно очередь, добавьте её в service_tables.exact. Указанный ключ заменяет умолчание целиком, а не дополняет его: перечисляйте полный список.

Токен сюда не кладётся. Он живёт в .env.local (DBDUMP_LLM_TOKEN), поэтому файл безопасно коммитить. Переменные окружения DBDUMP_* перекрывают значения из этого файла. Работают и оверрайды по окружениям — config/packages/dev/database_dumps.yaml.

Переезд конфига в 1.1.24. Раньше data_dir, llm и opencode лежали отдельным PHP-файлом config/database-dumps.php, а бандл читал его в обход DI. Теперь это обычный конфиг бандла. При обновлении перенесите значения из старого файла в config/packages/database_dumps.yaml под ключ database_dumps: и удалите старый — Symfony-бридж его больше не читает. В Laravel формат не изменился: там по-прежнему публикуемый config/database-dumps.php.

Бережный доступ к БД (db)

Разведка (prepare-config, prepare-analysis, check-criteria) работает и на боевой базе, поэтому пакет не читает данные там, где хватает статистики планировщика, и ограничивает всё остальное. В Laravel те же ключи — секция db в config/database-dumps.php (env DBDUMP_DB_*).

• Профили сессии. При первом обращении к подключению в сессию уходят SET statement_timeout, lock_timeout, idle_in_transaction_session_timeout (PostgreSQL; MySQL/MariaDB — max_execution_time / max_statement_time; Oracle — без таймаутов). Профиль analyze — короткий таймаут и бюджет запросов; export включает дампер (долгий таймаут, без бюджета); import — импортёр (без ограничений). Команда list БД не открывает: SET применяется лениво.
• Размер таблиц — из pg_class.reltuples / pg_stat_user_tables.n_live_tup (MySQL — information_schema.tables.table_rows, Oracle — all_tables.num_rows), одним запросом на подключение. Точный COUNT(*) — только если оценка не превышает max_scan_rows, либо с --exact-counts (полный проход по каждой таблице — не для боевой БД). Таблица без статистики получает находку P-1 («размер неизвестен, выполните ANALYZE на стороне БД») и точно не считается никогда — именно она может оказаться самой большой; prepare-config кладёт её в partial_export.
• Профили колонок на PostgreSQL берутся из pg_stats (null_frac, n_distinct, самые частые значения) — таблица не читается вовсе. Выборка строк делается только для колонок, которых в статистике нет (добавлены после последнего ANALYZE), и никогда не сортирует таблицу целиком: TABLESAMPLE BERNOULLI в пределах max_scan_rows, SYSTEM — на больших; таблица неизвестного размера — голова.
• Права. Колонка без права SELECT — находка P-2: SELECT * при выгрузке упадёт, а в pg_stats такой колонки нет, и без этой проверки «нет прав» неотличимо от «нет статистики».
• Коды. Инвентарь для агента по-прежнему без значений данных; единственное исключение — codes колонки: короткие ASCII-идентификаторы (1, -4, RED), не более 50 различных, повторяющиеся, не из колонки с ПД-именем и не дата. Они нужны, чтобы сверить enum из кода с тем, что реально лежит в базе. codes_complete: false — most_common_vals хранит только частые значения.
• Бюджет. Профиль analyze считает запросы; при превышении query_budget прогон останавливается с QueryBudgetExceededException — сузьте анализ до схемы или поднимите бюджет.
• Таймаут критерия. check-criteria отличает критерий, упавший по statement_timeout (префикс timeout:), от синтаксически неверного: первый нужно не чинить, а индексировать или сужать.

Инвентарь получает row_count_estimated, row_count_source и список warnings (P-1/P-2).

pgbouncer в режиме transaction pooling не сохраняет сессионный SET между транзакциями — задайте таймауты на стороне пула.

Структура каталогов (Symfony)

Команды Symfony

Настройка Laravel

Регистрация провайдера

Сервис-провайдер подключается автоматически. Если нет — зарегистрируйте в config/app.php:

Публикация конфигурации

Чтобы изменить пути, опубликуйте PHP-конфигурацию:

Появится файл config/database-dumps.php:

Команды Laravel

Скрипты before/after

Можно выполнять свои SQL-скрипты до и после импорта.

Скрипты выполняются в алфавитном порядке. Используйте числовые префиксы для управления очерёдностью:

Чтобы пропустить скрипты, используйте --skip-before и --skip-after:

Поддержка IDE (JSON Schema)

В пакете есть JSON Schema для dump_config.yaml — файл resources/dump_config.schema.json. Он даёт автодополнение и валидацию в PHPStorm и других IDE.

Вариант 1: YAML-комментарий (рекомендуется)

Добавьте в начало dump_config.yaml:

Путь указывается относительно файла: для Symfony — относительно config/, для Laravel — относительно docker/database/.

Вариант 2: Настройка PHPStorm вручную

1. Откройте Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings
2. Добавьте маппинг:
   • Schema file: vendor/timbrs/database-dumps/resources/dump_config.schema.json
   • File path pattern: dump_config.yaml

Архитектура

Как работает экспорт

1. TableConfigResolver — читает YAML и собирает список таблиц для экспорта
2. DatabaseDumper — управляет процессом экспорта
3. TableDependencyResolver — топологическая сортировка таблиц по FK (родители экспортируются первыми). При обнаружении циклов — автоматический разрыв через nullable-рёбра
4. DataFetcher — получает данные из БД через ConnectionRegistry
5. CascadeWhereResolver — генерирует WHERE-подзапросы из cascade_from для связности данных
6. RussianFaker — заменяет персональные данные (ФИО, email, телефон, пол) на сгенерированные
7. SqlGenerator — генерирует SQL: TRUNCATE + INSERT (с NULL для разорванных FK) + сброс счётчиков + UPDATE (восстановление FK)
8. Результат сохраняется в docker/database/dumps/{schema}/{table}.sql

Как работает импорт

1. ProductionGuard — проверяет, что мы не на продакшене
2. TransactionManager — оборачивает всё в транзакцию
3. TableDependencyResolver — топологическая сортировка файлов по FK (родители импортируются первыми), с автоматическим разрывом циклов
4. SchemaValidator — сравнивает столбцы дампа со столбцами в БД, предупреждает о расхождениях
5. ScriptExecutor — выполняет скрипты из before_exec/
6. SqlParser / StatementSplitter — разбирает .sql файлы на отдельные выражения
7. Выражения выполняются в БД
8. ScriptExecutor — выполняет скрипты из after_exec/

Различия платформ

Пакет сам генерирует правильный SQL в зависимости от СУБД:

Платформа определяется автоматически по подключению к БД.

Oracle: используется DELETE FROM вместо TRUNCATE TABLE, т.к. Oracle TRUNCATE не поддерживает CASCADE и блокируется FK constraints. Сброс sequences требует PL/SQL — используйте скрипты в docker/database/after_exec/.

Структура исходного кода

Безопасность

Пакет не позволяет случайно импортировать дампы на продакшен. Импорт заблокирован, когда переменная окружения APP_ENV равна prod или predprod.

Тестирование

Полный цикл на живой БД

tests/Integration/FullCycleTest.php прогоняет цепочку целиком: сид → слепок → досье → решения → apply → check (static/live/plan) → export → check --stage=dump. Юнит-тесты проверяют каждое звено с моками, а расходятся звенья как раз на стыках — на форме слепка, на том, что решение адресует таблицу так же, как её называет конфиг, на порядке выгрузки. Без живой базы такой стык не проверить.

Без DBDUMP_TEST_DSN тест пропускается — в закрытом контуре базы в CI нет:

Тест работает в своей схеме (dbdump_it), которую сам создаёт и сносит в tearDown — чужие таблицы не трогает. Подойдёт любой Postgres, в том числе поднятый локальным стендом хост-проекта (docker-compose.local.yml, сервис postgres).

Локальная разработка

Чтобы подключить пакет из локальной папки (без Packagist), добавьте в composer.json вашего проекта:

Затем выполните composer update timbrs/database-dumps — Composer создаст симлинк на локальный пакет.

Требования

Обязательные:

• PHP ^7.1 | ^8.0
• symfony/yaml ^4.4 | ^5.4 | ^6.0 | ^7.0
• symfony/finder ^4.4 | ^5.4 | ^6.0 | ^7.0

Нижняя планка — 7.1: пакет ставится в том числе в проекты, которые с неё не сдвинулись. На практике нужен 7.1.3 — столько требует Symfony 4.4, самая старая поддерживаемая ветка symfony/yaml и symfony/finder.

Совместимость проверяется не на глаз, а сниффами:

(PHPCompatibility по src/ с testVersion 7.1-). Это единственный способ поймать, например, array_key_first() или флаг JSON_INVALID_UTF8_SUBSTITUTE — оба появились после 7.1 и оба уже пробирались в код. Тесты и статический анализ такого не видят: они гоняются на современном PHP.

Опциональные (зависят от фреймворка):

Лицензия

MIT License. Подробнее в файле LICENSE.

English

PHP package for exporting and importing database dumps as SQL. Supports PostgreSQL, MySQL, and Oracle (12c+). Works with Symfony, Laravel, and any PHP project.

Table of Contents

• Description
• Features
• Installation
• Quick Start
  • Symfony
  • Laravel
• Configuration
  • Full Export
  • Partial Export
  • Cascade Dependencies (cascade_from)
  • Personal Data Masking (faker)
  • Config Splitting by Schema (includes)
  • Multiple Connections
  • Settings
  • Auto-generate Configuration
• Symfony Setup
  • Bundle Registration
  • Directory Structure (Symfony)
  • Symfony Commands
• Laravel Setup
  • Provider Registration
  • Publishing Configuration
  • Laravel Commands
• Before/After Scripts
• IDE Support (JSON Schema)
• Architecture
  • How Export Works
  • How Import Works
  • Platform Differences
  • Source Directory Structure
• Security
• Testing
• Local Development
• Requirements
• License

Description

Database Dumps is a PHP package that helps developers create and deploy database dumps for local and test environments.

What problem does it solve? On a project with a large production database, developers need up-to-date test data — but copying the entire database is slow, and using real customer data in dev environments is not acceptable. This package lets you configure export rules once — which tables to grab in full, which partially — and forget about manual dump preparation.

How does it work? You describe export rules in a YAML file. The package then:

• generates SQL dumps from production (or staging) database, respecting FK dependencies between tables
• replaces personal data (Russian names, emails, phone numbers) with generated values, making dumps safe to use
• deploys dumps into the target database with a single command, with built-in protection against accidental runs on production

Where is it useful? In any PHP project using Symfony or Laravel (or standalone), where you need to:

• quickly set up a test database for developers
• share dumps across teams without leaking personal data
• keep seed data in the repository and update it from a real database
• work with multiple database connections simultaneously

Features

• No framework lock-in — works with Symfony, Laravel, and any PHP project
• PostgreSQL, MySQL & Oracle — automatically generates the right SQL for each database
• Multiple connections — export/import from several databases at once
• Batched INSERTs — automatically groups rows (1000 per statement)
• Rollback on errors — import runs inside a transaction
• Production guard — import is blocked when APP_ENV=prod
• Before/After scripts — run custom SQL before and after import
• Flexible config — YAML file with full and partial export rules
• Sequence reset — automatic sequence / auto-increment reset after import
• Auto-generate config — prepare-config command creates YAML from DB structure
• FK-aware ordering — automatic topological sorting of tables during export and import (parents first)
• Cascade dependencies — cascade_from generates WHERE subqueries to keep data consistent across FK relations
• Personal data masking (faker) — automatic detection and replacement of PII (Russian names, email, phone, gender) during export
• Config splitting — automatic splitting of configuration into per-schema files
• Smart Cycle Breaking — automatic resolution of circular FK dependencies (two-phase INSERT NULL → UPDATE) instead of falling back to alphabetical order
• Self-referential FK — support for self-referencing tables (category trees, org structures, threaded comments)
• Schema validation on import — warnings when dump columns don't match the DB, --ignore-schema-mismatch option
• Config settings — settings: section for batch_size, sample_size, max_cascade_depth
• Dry-run export — --dry-run option to preview the export plan without executing

Installation

Quick Start

Symfony

1. Register the bundle manually in config/bundles.php (there is no Flex recipe):

2. Create docker/database/dump_config.yaml (default path; override via config_path):

3. Export dumps:

4. Import dumps:

Laravel

1. The service provider is discovered automatically. The file docker/database/dump_config.yaml is created on first run.

2. Edit docker/database/dump_config.yaml (same format as Symfony).

3. Export dumps:

4. Import dumps:

Configuration

Export is configured via a YAML file with two sections: full_export (all rows) and partial_export (with limits).

Full Export

Exports all rows from listed tables:

Partial Export

Exports a limited number of rows with filtering:

Available options:

Cascade Dependencies (cascade_from)

When partially exporting related tables, data can become inconsistent: a child table may reference rows that didn't make it into the parent's dump. The cascade_from option solves this by automatically generating a WHERE subquery that limits the selection to only those rows whose FK parent is present in the dump.

In this example:

• orders exports only orders whose user_id exists among exported users
• order_items exports only items belonging to exported orders
• Subqueries are nested: order_items -> orders -> users (up to 10 levels deep)

The prepare-config command automatically detects FK dependencies and generates cascade_from. To disable: --no-cascade.

Personal Data Masking (faker)

The package can automatically detect and replace personal data during export. This allows safe use of dumps in dev/staging environments.

Supported patterns:

The faker section in configuration:

The inn, ogrn, digits, birth_date, doc_series and doc_number patterns are value-seeded: the same input always produces the same output, in every table and every run. Otherwise one tax number would map to different values in clients and in leads, breaking the link between records in the dump. Length, separators and date format are preserved, so these patterns also fit numeric (bigint) and date/timestamp columns.

The firstname, lastname, and patronymic patterns are detected via cross-correlation: if a composite column (fio, fio_short, name) is already found in the table and there's an adjacent column with individual first names/last names/patronymics — it will be detected automatically.

The gender pattern is detected by matching both the column name (gender, sex, пол) and its contents (valid values: male/female, m/f, м/ж, мужской/женский, муж/жен, мужчина/женщина). The original value's case and format are preserved during replacement.

The prepare-config command automatically analyzes table contents and generates the faker section when PII patterns are detected in columns (threshold: 80% match from 200 random rows). To disable: --no-faker.

Replacement is deterministic — the seed is based on the hash of the FIO value (column with fio pattern), if such a column exists in the table's faker config. If there is no fio column, the seed is computed from the hash of all faker column values in the row. This ensures the same person always gets the same replacement regardless of the table or run.

Config Splitting by Schema (includes)

When dealing with many tables, the configuration can become unwieldy. The prepare-config command splits config into per-schema files by default. The main dump_config.yaml lives in docker/database/, and per-schema files go into the docker/database/dump-settings/ subdirectory:

Main file (docker/database/dump_config.yaml):

💡 Include paths are written with a ./ prefix so PhpStorm/IDEs treat them as file references: Ctrl+B / Cmd+B (or Ctrl+click) on a path jumps straight to the target *.yaml. The prefix does not affect path resolution (both ./-prefixed and plain relative paths load fine).

Schema file (docker/database/dump-settings/public.yaml):

To generate a single file without splitting: --no-split.

Multiple Connections

To work with several databases, add a connections section:

Where dumps are saved:

• Main connection: {data_dir}/dumps/{schema}/{table}.sql
• Named connection: {data_dir}/dumps/{connection}/{schema}/{table}.sql

data_dir is the base data directory (default docker/database). Everything the package produces is resolved from it: the main config ({data_dir}/dump_config.yaml), per-schema files ({data_dir}/dump-settings), dumps ({data_dir}/dumps), analysis ({data_dir}/analysis) and hooks ({data_dir}/before_exec, {data_dir}/after_exec). Change it in the data_dir key of the settings file — config/packages/database_dumps.yaml (Symfony) / config/database-dumps.php (Laravel) — or via the DBDUMP_DATA_DIR env var. In prod the default docker/database is always used.

Default changed in 1.1.23. It used to be database, and the path to dump_config.yaml was a separate hardcoded constant that did not follow data_dir. The default is now docker/database, and the config lives inside data_dir next to the dumps. An installation that relied on the old default (no data_dir key set) will stop seeing its files after the upgrade — set data_dir: 'database' or move the directory.

The --connection option:

Settings

The settings section allows you to customize internal package parameters:

Auto-generate Configuration

The prepare-config command looks at your DB structure and creates or updates dump_config.yaml. The required mode argument defines the scope:

Modes:

all mode rebuilds the config from scratch and never reads the existing file: hand-tuned sample.criteria, cascade_from, limit and faker are replaced by machine guesses. That is why the command refuses to run over an existing dump_config.yaml and points at the modes that merge instead of overwriting (new, schema=, table=), plus check-criteria and validate. A deliberate rebuild from scratch is prepare-config all --force.

Options:

How tables are sorted:

• Rows <= threshold — full_export
• Rows > threshold — partial_export (with limit, auto-detected sorting and where: "1=1" template for easy customization)
• Empty tables — skipped
• Service tables (migrations, sessions, cache*, telescope, oauth_, audit_*) — skipped

Symfony Setup

Bundle Registration

The package ships no Flex recipe, so the bundle must be registered manually. Add it to config/bundles.php:

Registering under dev/test matches installation via composer require --dev. If the package is installed for prod (without --dev), register the bundle as ['all' => true].

Bundle Settings

All settings live in a single config/packages/database_dumps.yaml under the database_dumps: root key. The file is optional — defaults apply without it.

⚠️ If the bundle is registered as ['dev' => true, 'test' => true] (the recommended setup above), the section MUST be wrapped in when@dev: / when@test:. Files under config/packages/*.yaml are loaded in every environment, and there is no database_dumps extension in prod — a bare root key breaks the container build: There is no extension able to load the configuration for "database_dumps". The built-in web_profiler.yaml and debug.yaml work the same way. With ['all' => true] no wrapper is needed.

Full key list (shown without the wrapper, i.e. for ['all' => true]):

Row counts come from planner statistics (pg_class.reltuples, information_schema.tables.table_rows, all_tables.num_rows); an exact COUNT(*) runs only when the estimate fits in max_scan_rows or with prepare-analysis --exact-counts. On PostgreSQL column profiles are read from pg_stats and the table itself is not touched; row samples use TABLESAMPLE, never ORDER BY RANDOM(). Tables without statistics are reported as P-1, columns without SELECT privilege as P-2. The only data values that reach the inventory are codes — short ASCII identifiers of low-cardinality columns after a PII gate.

The token does not go here. It lives in .env.local (DBDUMP_LLM_TOKEN), so the file is safe to commit. DBDUMP_* environment variables override values from this file. Per-environment overrides work too — config/packages/dev/database_dumps.yaml.

Config moved in 1.1.24. data_dir, llm and opencode used to live in a separate PHP file, config/database-dumps.php, which the bundle read bypassing DI. It is now an ordinary bundle config. When upgrading, move the values from the old file into config/packages/database_dumps.yaml under the database_dumps: key and delete the old one — the Symfony bridge no longer reads it. Laravel is unchanged: still the published config/database-dumps.php.

Directory Structure (Symfony)

Symfony Commands

Verifying exported dumps (verify-dump) and the import report

verify-dump inspects what actually landed in {data_dir}/dumps/ — neither validate nor check-criteria looks there. It never connects to the database: every dump file is read once for all checks, and only counters and column names leave the file — no data values appear in the report.

Options: -s|--schema, -c|--connection, --inventory (schema inventory, default {data_dir}/analysis/schema_inventory.json; without it inventory-based checks are skipped and the report says so), --format=text|json, --out=PATH. Exit code is 1 on errors.

Edges for V-1 are the union of cascade_from and the inventory foreign_keys: in a constraint-less database the second list is empty today, but once FKs appear the relation is checked without touching the config.

import returns a report with the same rules: errors in it produce exit code 1 even when the transaction succeeded; --out=PATH writes the report as JSON.

Laravel Setup

Provider Registration

The service provider is discovered automatically. If not, register it in config/app.php:

Publishing Configuration

To customize paths, publish the PHP config:

This creates config/database-dumps.php:

Laravel Commands

Before/After Scripts

You can run custom SQL scripts before and after import.

Scripts run in alphabetical order. Use numeric prefixes to control the order:

To skip scripts, use --skip-before and --skip-after:

IDE Support (JSON Schema)

The package includes a JSON Schema for dump_config.yaml at resources/dump_config.schema.json. It provides autocompletion and validation in PHPStorm and other IDEs.

Option 1: YAML comment (recommended)

Add to the top of your dump_config.yaml:

The path is relative to the file: for Symfony — relative to config/, for Laravel — relative to docker/database/.

Option 2: PHPStorm manual setup

1. Open Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings
2. Add a mapping:
   • Schema file: vendor/timbrs/database-dumps/resources/dump_config.schema.json
   • File path pattern: dump_config.yaml

Architecture

How Export Works

1. TableConfigResolver — reads YAML and builds a list of tables to export
2. DatabaseDumper — manages the export process
3. TableDependencyResolver — topological sorting of tables by FK (parents are exported first). Circular dependencies are automatically broken via nullable edges
4. DataFetcher — fetches data from the DB via ConnectionRegistry
5. CascadeWhereResolver — generates WHERE subqueries from cascade_from for data consistency
6. RussianFaker — replaces personal data (names, email, phone, gender) with generated values
7. SqlGenerator — generates SQL: TRUNCATE + INSERT (with NULL for broken FKs) + counter reset + UPDATE (FK restoration)
8. Result is saved to docker/database/dumps/{schema}/{table}.sql

How Import Works

1. ProductionGuard — checks we're not on production
2. TransactionManager — wraps everything in a transaction
3. TableDependencyResolver — topological sorting of files by FK (parents are imported first), with automatic cycle breaking
4. SchemaValidator — compares dump columns against DB columns, warns about mismatches
5. ScriptExecutor — runs scripts from before_exec/
6. SqlParser / StatementSplitter — splits .sql files into individual statements
7. Statements are executed against the DB
8. ScriptExecutor — runs scripts from after_exec/

Platform Differences

The package generates the right SQL depending on the database:

The platform is detected automatically from the DB connection.

Oracle: DELETE FROM is used instead of TRUNCATE TABLE because Oracle TRUNCATE doesn't support CASCADE and is blocked by FK constraints. Sequence reset requires PL/SQL — use scripts in docker/database/after_exec/.

Source Directory Structure

Security

The package prevents accidental imports on production. Import is blocked when the APP_ENV environment variable is prod or predprod.

Testing

Local Development

To use the package from a local folder (without Packagist), add to your project's composer.json:

Then run composer update timbrs/database-dumps — Composer will create a symlink to the local package.

Requirements

Required:

• PHP ^7.2 | ^8.0
• symfony/yaml ^4.4 | ^5.4 | ^6.0 | ^7.0
• symfony/finder ^4.4 | ^5.4 | ^6.0 | ^7.0

Optional (depends on framework):

License

MIT License. See LICENSE for details.

Developed by Timur Bayan (Timbrs).