Configuration

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 from the 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 config/system/settings.php and ends up in $GLOBALS['TYPO3_CONF_VARS'] after the Core bootstrap. The specific sub-array is $GLOBALS['TYPO3_CONF_VARS']['DB'].

Example: one connection

A typical basic example using only the Default connection with a single database endpoint:

config/system/settings.php
// [...]
'DB' => [
    'Connections' => [
        'Default' => [
            'charset' => 'utf8',
            'dbname' => 'theDatabaseName',
            'driver' => 'mysqli',
            'host' => 'theHost',
            'password' => 'theConnectionPassword',
            'port' => 3306,
            'user' => 'theUser',
        ],
    ],
],
// [...]

Remarks:

  • The Default connection must be configured, this can not be left out or renamed.

  • For the mysqli driver: If the host is set to localhost and 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.1 or IPv6 address ::1/128 respectively must be used as host value.

  • 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.

  • If the charset option is not specified, it defaults to utf8.

  • The option wrapperClass is used by TYPO3 to insert the extended Connection class TYPO3\CMS\Database\Connection as main facade around Doctrine DBAL.

Example: two connections

Attention

Changed in version 13.0.

TYPO3 expects all "main" Core system tables to be configured for the Default connection (especially sys_*, pages, tt_content and in general all tables that have TCA configured). The reason for this is to improve performance with joins between tables. Cross-database joins are almost impossible.

One scenario for using a separate database connection is to query data directly from a third-party application in a custom extension. Another use case is database-based caches.

Another example with two connections, where the be_sessions table is mapped to a different endpoint:

config/system/settings.php
// [...]
'DB' => [
    'Connections' => [
        'Default' => [
            'charset' => 'utf8',
            'dbname' => 'default_dbname',
            'driver' => 'mysqli',
            'host' => 'default_host',
            'password' => '***',
            'port' => 3306,
            'user' => 'default_user',
        ],
        'Sessions' => [
            'charset' => 'utf8mb4',
            'driver' => 'mysqli',
            'dbname' => 'sessions_dbname',
            'host' => 'sessions_host',
            'password' => '***',
            'port' => 3306,
            'user' => 'some_user',
        ],
    ],
    'TableMapping' => [
        'be_sessions' => 'Sessions',
    ]
],
// [...]

Remarks:

  • The array key Sessions is 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 TableMapping.

Attention

The TYPO3 installer supports only a single MariaDB or MySQL connection at the moment.