Configuring the Doctrine DBAL for
TYPO3 CMS is all about specifying the single database endpoints
and handing over 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 from the
to point them to a different database endpoint.
As with other central configuration options, the database endpoint and mapping configuration happens
typo3conf/LocalConfiguration.php and ends up in
the Core bootstrap. The specific sub-array is
A typical, basic example using only the
Default connection with a single database endpoint:
// LocalConfiguration.php // [...] '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.
- For mysqli, if the
hostis set to
localhostand if the default
PHPoptions in this area are not changed, the connection will be socket based. This saves a little overhead. To force a
TCP/IPbased connection even for
::1/128respectively must be used as
- The connect options are hand over to Doctrine DBAL without much manipulation from
TYPO3 CMSside. Please refer to the doctrine connection docs for a full overview of settings.
charsetoption is not specified it defaults to
- The option
wrapperClassis used by TYPO3 to insert the extended Connection class
TYPO3\CMS\Database\Connectionas main facade around Doctrine DBAL.
A slightly more complex example with two connections, mapping the
sys_log table to a different endpoint:
// LocalConfiguration.php // [...] '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’s good practice to give it a useful speaking name.
- It is possible to map multiple tables to a different endpoint by adding further table name /
connection name pairs to
- Mind this “connection per table” approach is limited: If in the above example a join query
that spans over different connections is fired, an exception is raised. It is up to the
administrator to group affected tables to the same connection in those cases, or a developer
should implement some fallback logic to suppress the
Connections to databases
mysql are actively tested.
mssql is currently not actively tested.
TYPO3 CMS installer supports only a single
at the moment and the connection details can not be properly edited within the
section of the Install Tool.