The database layer in one page #

This page is for database administrators who meet Exponential for the first time and want to know how the application talks to the database before they touch a server. It answers: which code opens the connection, how the driver is chosen, what the drivers do differently, which tools turn the engine-neutral schema into DDL, and what is kept in the database as opposed to files. Every class and file named here exists in the 6.0.x kernel.

Contents #

1. One entry point: eZDB
2. Drivers and their aliases
3. Schema handlers
4. What is in the database, and what is not
5. Caches between the site and the database
6. Where the pieces live
7. What this means for your work

One entry point: eZDB #

Every part of Exponential reaches the database through eZDB::instance() (lib/ezdb/classes/ezdb.php). It reads site.ini [DatabaseSettings] DatabaseImplementation, looks the value up in ImplementationAlias[], creates the driver object and keeps it for the rest of the request.

All drivers implement one interface, eZDBInterface (lib/ezdb/classes/ezdbinterface.php): connect, query(), arrayQuery() with offset and limit, transactions, lastSerialID(), escapeString() and helpers for what differs between engines (subString(), concatString(), md5(), bitAnd(), bitOr()).

If the alias names no class, the request does not stop at once. eZDB::instance() returns a null database (eZNullDB, lib/ezdb/classes/eznulldb.php) and writes "Database implementation not supported" to var/log/error.log. Every page that needs content then fails, so a typing error looks like a database that is down (9.1).

Drivers and their aliases #

The kernel aliases are in settings/site.ini; the Oracle aliases are added by the extension's own site.ini.append.php when it is active. Code can ask which engine it runs on: eZDB::instance()->databaseName() returns sqlite, postgresql, mongo, mysql or oracle (and null for the null database).

Two drivers do more than pass SQL through:

• SQLite registers the functions SQLite lacks (md5(), the BIT_OR and BIT_AND aggregates), rewrites MySQL's UPDATE ... JOIN, ignores MySQL-only SET statements and queues writers (SQLite 3 for database administrators).
• MongoDB never runs SQL: the adapter translates the kernel's SQL-shaped calls into MongoDB operations (MongoDB: limits and operations).

Schema handlers #

The schema is kept in an engine-neutral format, .dba (share/db_schema.dba, share/db_data.dba). A schema handler turns it into the DDL of one engine and reads a live database back into the same format. The handlers are registered in settings/dbschema.ini [SchemaSettings]:

The installers, the schema tools (ezsqldumpschema.php, ezsqlinsertschema.php) and the upgrade check all go through these handlers. See The .dba schema format.

What is in the database, and what is not #

A database backup alone is therefore not a backup of the site; see Backups per engine.

Caches between the site and the database #

Most page views never reach the database: Velocity's response cache, the content view cache and the template-block cache answer first, and the optional SQL query cache (settings/querycache.ini, Mode=off by default) answers repeated SELECT statements on every engine except MongoDB. A write made outside Exponential, with a SQL client or a restore, is not seen by these caches; clear them afterwards (The SQL query cache, Performance and scaling).

Where the pieces live #

What this means for your work #

• The database account is the only credential the application needs; it lives in one override file (Securing the database).
• Schema changes come from update files and the schema tools, never from hand edits (Upgrades and the SQL update files).
• After any write outside the application, clear the caches.

Related pages #

• Database administrators: start here
• The DatabaseSettings reference
• Supported engines and versions
• Database support
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.