TYPO3 CMS is all about specifying the single database endpoints
and handing over connection credentials. The frameworks 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
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-dbalwithout 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 the
TYPO3 CMSframework to “hang in” the extended Connection class
TYPO3\CMS\Database\Connectionas main facade around
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
At the time of this writing (TYPO3 CMS version 8.6), there are still some known issues with
connections to databases other than
mariadb. Core internal tests to
mssql still fail. This however should improve with younger versions.
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.
The core team hopes this situation settles until the final release of
TYPO3 v8 LTS.