README

(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

Concept

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.

Status

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.

Installation

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:

Related DBAL issues/PRs

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

Related Drupal issues

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

mondrake / drudbal

Maintainers

Details