The configuration of Doctrine DBAL for TYPO3 is about specifying the single
database endpoints and passing the connection credentials. The framework
supports the parallel usage of multiple database connections, a specific
connection is mapped depending on its table name. The table space can be seen as
a transparent layer that determines which specific connection is chosen for a
query to a single or a group of tables: It allows "swapping out" single tables
Default connection to point them to a different database endpoint.
As with other central configuration options, the database endpoint and mapping
configuration is done in
typo3conf/LocalConfiguration.php and ends up in
$GLOBALS['TYPO3_CONF_VARS'] after the Core bootstrap. The specific sub-array is
Example: one connection¶
A typical basic example using only the
Default connection with a single
// [...] 'DB' => [ 'Connections' => [ 'Default' => [ 'charset' => 'utf8', 'dbname' => 'theDatabaseName', 'driver' => 'mysqli', 'host' => 'theHost', 'password' => 'theConnectionPassword', 'port' => 3306, 'user' => 'theUser', ], ], ], // [...]
Defaultconnection must be configured, this can not be left out or renamed.
mysqlidriver: If the
hostis set to
localhostand if the default PHP options in this area are not changed, the connection will be socket-based. This saves a little overhead. To force a TCP/IP-based connection even for
localhost, the IPv4 address
127.0.0.1or IPv6 address
::1/128respectively must be used as
The connection options are passed to Doctrine DBAL without much manipulation from TYPO3 side. Please refer to the doctrine connection docs for a full overview of the settings.
charsetoption is not specified, it defaults to
wrapperClassis used by TYPO3 to insert the extended Connection class
TYPO3\CMS\Database\Connectionas main facade around Doctrine DBAL.
Example: two connections¶
Another example with two connections, where the
sys_log table is mapped
to a different endpoint:
// [...] 'DB' => [ 'Connections' => [ 'Default' => [ 'charset' => 'utf8', 'dbname' => 'default_dbname', 'driver' => 'mysqli', 'host' => 'default_host', 'password' => '***', 'port' => 3306, 'user' => 'default_user', ], 'Syslog' => [ 'charset' => 'utf8', 'dbname' => 'syslog_dbname', 'driver' => 'mysqli', 'host' => 'syslog_host', 'password' => '***', 'port' => 3306, 'user' => 'syslog_user', ], ], 'TableMapping' => [ 'sys_log' => 'Syslog' ], ], // [...]
The array key
Syslogis just a name. It can be different, but it is good practice to give it a useful, descriptive name.
It is possible to map multiple tables to a different endpoint by adding further table name / connection name pairs to
However, this "connection per table" approach is limited: In the above example, if a join query is executed that spans different connections, an exception will be thrown. It is up to the administrator to group the affected tables to the same connection in those cases, or a developer should implementfallback logic to suppress the
Connections to MariaDB, MySQL, PostgreSQL and SQLiteare actively tested. However, SQL Server is currently not actively tested.
The TYPO3 installer supports only a single MariaDB or MySQL connection at the moment.