Migrations and seed data: .dba schema files and packages #

This page is for developers who run doctrine:migrations:migrate, php artisan migrate, manage.py migrate or rails db:migrate. Tables are described in database-neutral .dba files, created by commands, and changed by upgrade steps that you write and ship. Content classes and content are moved with packages. Since 6.0.15 a site also has migrations close to what you know: files YYYYMMDDHHMMSS_name.php in migrations/, run in order by ./console exp:migration:migrate, recorded in the table exp_migration, with down() for a rollback (Migrations). Say this early in a project; it changes how a release is planned.

Contents #

1. The pieces
2. The .dba format
3. Creating and installing a schema
4. Upgrades: your own migration steps
5. Seed data and content
6. Compared with migration tools

The pieces #

The .dba format #

A .dba file is a PHP array of tables, each with fields (type, length, default, not null), indexes and the primary key. The kernel's own schema is share/db_schema.dba and its data share/db_data.dba. The class that reads and writes them is eZDbSchema (lib/ezdbschema/), which generates the SQL for SQLite, PostgreSQL, MySQL/MariaDB and Oracle from the same file (Database schema and .dba files).

Creating and installing a schema #

Create the table on a development database, then dump only your tables:

php bin/php/ezsqldumpschema.php --type=sqlite --table-include=expdemo_item --output-array \
  var/storage/sqlite3/exponential.db extension/expdemo/share/db_schema.dba --allow-root-user

Install it on a database:

php bin/php/ezsqlinsertschema.php --type=mysql --user=<user> extension/expdemo/share/db_schema.dba <database>

Better: give your extension one idempotent command that creates missing tables, the way expqueue does with ./console ext:expqueue:install-schema. A script in extension/expdemo/bin/php/install-schema.php becomes ./console ext:expdemo:install-schema without registration (Command line).

Upgrades: your own migration steps #

1. Never change a released table in place without an upgrade step.
2. Ship upgrade steps as numbered scripts or SQL files per engine (for example extension/<ext>/update/), and let your install command apply the ones that are missing. Keep the record of what ran in a small table or setting of your own; the kernel does not keep one for you.
3. Add columns with defaults, so the old code keeps working during the deploy.
4. Write steps that only add where possible, so a code rollback still runs on the new schema.
5. Review data changes row by row, not by diff: a .dba is a PHP array, and removing one row renumbers the rest.

Seed data and content #

php ezpm.php list --allow-root-user
php ezpm.php import var/tmp/<package>.ezpkg --allow-root-user

Compared with migration tools #

The deployment order that follows from this is on Servers and deployment and A deployment pipeline.

Related pages #

• Database schema and .dba files
• Package wizard
• ezpm package manager CLI
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.