Database schema and .dba files
This page is for application creators whose extension has its own tables. Exponential describes schemas in a
database-neutral format, .dba, and generates the SQL for each engine from it, so one file serves SQLite, PostgreSQL,
MySQL/MariaDB and Oracle.
Contents
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; extensions keep theirs in
extension/<ext>/share/db_schema.dba (and db_data.dba for seed rows). The class that reads and writes them is
eZDbSchema (lib/ezdbschema/).
Making the file
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-userCheck the options of your version with php bin/php/ezsqldumpschema.php --help; the dump can also write SQL for one
engine instead of the array.
Installing it
php bin/php/ezsqlinsertschema.php --type=mysql --user=<user> extension/expdemo/share/db_schema.dba <database>ezsqlinsertschema.php ("Insert database schema and data to specified database") creates the tables for the engine
named by --type. ezimportdbafile.php imports a .dba into the configured database.
An install command
Give your extension one idempotent command that creates its tables if they are missing, the way expqueue does with
./console ext:expqueue:install-schema (expqueue):
extension/expdemo/bin/php/install-schema.php -> ./console ext:expdemo:install-schemaIt reads the .dba, checks which tables exist, and creates only the missing ones; running it twice changes nothing.
Upgrades
- Never change a released table in place without an upgrade step.
- Ship upgrade steps as numbered scripts or SQL files per engine (
extension/<ext>/update/), and let the install command apply the missing ones. - Add columns with defaults, so old code keeps working during the deploy.
Reviewing changes
A .dba is a PHP array; removing one row renumbers what follows, so a text diff is unreadable for data files. Compare
schemas with php bin/php/ezsqldiff.php, and data row by row with a script, not by diff.
Related pages
- Persistent objects and custom tables
- Database access and SQL
- Databases
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.