(This README updated March 30, 2020)
An experimental Drupal database driver for Doctrine DBAL. Do not use if not for trial. No support, sorry :)
| Requires | Minimum version |
|---|---|
| Drupal | 11.x |
| Doctrine DBAL | 4 |
| Drush | 13.x |
| PHP | 8.3 |
The concept is to use Doctrine DBAL as an additional database abstraction layer. The code of the DBAL Drupal database driver is meant to be 'database agnostic', i.e. the driver should be able to execute on any db platform that DBAL supports (in theory, practically there still need to be db-platform specific hacks through the concept of DBAL extensions, see below).
The Drupal database Connection class that this driver implements opens
a DBAL\Connection, and hands over statements' execution to it.
DBAL\Connection itself wraps a lower level driver connection (PDO
for pdo_mysql and pdo_sqlite drivers, mysqli for the mysqli driver).
Similarly, the StatementWrapper wraps a DBAL\Statement, which itself
wraps a DBAL-driver level Statement.
The DBAL connection provides additional features like the Schema Manager
that can introspect a database schema and build DDL statements, a Query
Builder that can build SQL statements based on the database platform in use,
etc. etc.
To overcome DBAL limitations and/or fit Drupal specifics, the DBAL Drupal
database driver also instantiates an additional object called
DBALExtension, unique for the DBAL Driver in use, to which some
operations that are db- or Drupal-specific are delegated.
The code in the master branch is working on a MySql database, using
either the 'mysql' or the 'mysqli' DBAL drivers, on a SQlite database, using
the 'sqlite' DBAL driver, or on a Oracle database using the 'oci8' database
driver.
'Working' means:
- it is possible to install a Drupal site via the installer, selecting 'Doctrine DBAL' as the database of choice;
- it is passing a selection of core PHPUnit tests , executed on GitHub Actions CI. The latest patches for the issues listed in 'Related Drupal issues' below need to be applied to get a clean test run.
Very rough instructions to install Drupal from scratch with this db driver under the hood:
- Get the DruDbal module from Packagist via Composer, it will install Doctrine DBAL as well:
$ composer require mondrake/drudbal:dev-master
- Launch the interactive installer. Proceed as usual and when on the db selection form, select 'Doctrine DBAL' and enter a 'database URL' compliant with Doctrine DBAL syntax. Note: the driver works only with mysql, mysqli, oci8 or sqlite DBAL drivers.
- If everything goes right, when you're welcomed to the new Drupal installation, visit the Status Report. The 'database' section will report something like:
| Issue | Description | Info |
|---|---|---|
| doctrine/dbal#1349 | DBAL-182: Insert and Merge Query Objects | |
| doctrine/dbal#1320 | DBAL-163: Upsert support in DBAL | |
| doctrine/dbal#2762 | Bulk inserts | |
| doctrine/dbal#1033 | DBAL-1096: schema-tool:update does not understand columnDefinition correctly | |
| doctrine/migrations#17 | Data loss on table renaming. | |
| doctrine/dbal#2415 | Add some MySQL platform data in Tables | fixed in 2.9.0 |
| Issue | Description |
|---|---|
| tbd | Add tests for Upsert with default values |
| tbd | Ensure that when INSERTing a NULL value in a database column, SELECTing it back returns NULL and not empty string - for all fetch modes |
| tbd | UpdateTestBase::runUpdate should reset database schema after updating |
| #2992274 | Installer tests fail if contrib driver hides database credentials form fields |