Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Database schema and .dba files

Ship the tables of your application for every database engine - the .dba schema format, dumping it with ezsqldumpschema, installing it with ezsqlinsertschema, per-engine SQL files, an install command, and upgrades.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/creators/app-creators/schema-and-dba-files.md

On this page

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

  1. The .dba format
  2. Making the file
  3. Installing it
  4. An install command
  5. Upgrades
  6. Reviewing changes

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-user

Check 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-schema

It 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.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x