bxmaximum Bitrix sprint.migration
Module sprint.migration (Composer: andreyryabin/sprint.migration) stores
schema/content changes as PHP classes under VCS and applies them on each copy
of the project via CLI or admin UI.
Install location (either is valid; resolve before calling CLI):
| Path | Typical when |
|---|---|
/local/modules/sprint.migration/ |
Composer / marketplace into local |
/bitrix/modules/sprint.migration/ |
Marketplace / copy into kernel modules |
Below, {module} means that resolved directory. Do not edit module
source. Write only migration files and optional configs (usually under
php_interface/).
Progressive disclosure: open only the rule files that match the task.
How to use
- Confirm the module is installed (
Loader::includeModule('sprint.migration')). - Identify the layer (CLI/config vs writing a Version vs helpers/builders).
- Open the matching
rules/*.mdbelow. - Prefer helpers/
save*APIs over raw Bitrix API when they cover the entity. - For domain ORM/data updates without builders — use D7/
Resultinsideup(), still as aVersionclass.
Official wiki: https://github.com/andreyryabin/sprint.migration/wiki
Defaults (override via migrations.*.php / module options)
| Item | Default |
|---|---|
| Migration dir | {local|bitrix}/php_interface/migrations (local wins if present) |
| Versions table | sprint_migration_versions |
| Class prefix | Version + timestamp YmdHis (name must contain a valid timestamp) |
| Extend class | Sprint\Migration\Version |
| CLI entry | php {module}/tools/migrate.php |
| Extra configs | {local|bitrix}/php_interface/migrations.<name>.php → dir migrations.<name>, table sprint_migration_<name> |
Choose a rule file
When to read rules/cli-config.md
Read when the task involves:
- Running CLI (
add,ls,up,down,redo,mark,run,config) - Naming versions / timestamps
- Multiple configs (
--config,migrations.*.php) - Admin UI vs console auth user
When to read rules/writing.md
Read when the task involves:
- Authoring
Version(up/down) - Idempotent
save*vsadd*IfNotExists - Output (
outSuccess/outError), returnfalseon failure - Dependencies (
checkRequiredVersions) - Restartable long migrations
- Exchange files / large data sets
- Hand-written data migrations (ORM / SQL)
When to read rules/helpers-builders.md
Read when the task involves:
- Choosing a Helper (
Iblock(),Hlblock(), …) - Choosing a Builder (
run IblockBuilder, …) - Export-from-admin → commit generated PHP
When to read rules/checklist.md
Read before finishing or reviewing a migration change:
- Safety / anti-patterns
- Apply / verify checklist
Related skills
| Need | Skill |
|---|---|
| Iblock domain model | bitrix-iblocks |
| Highloadblock CRUD | bitrix-highloadblock |
| Raw SQL / DDL outside helpers | bitrix-database |
| Module install SQL (not sprint) | bitrix-modules |
| Agents registration | bitrix-background-jobs |
| Options / storage choice | bitrix-storage |
Checklist
- Opened only the rule file(s) needed for this task.
- Migration files live under the configured
migration_dir(not in the module). - Did not modify sprint.migration module source.
- Applied
upon a local/dev copy when verifying the change.