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 (excerpt)

<?php

return [
  // ... some configuration
  'DB' => [
    'Connections' => [
      'Default' => [
        'charset' => 'utf8',
        'dbname' => 'theDatabaseName',
        'driver' => 'mysqli',
        'host' => 'theHost',
        'password' => 'theConnectionPassword',
        'port' => 3306,
        'user' => 'theUser',
      ],
    ],
  ],
  // ... more configuration
];

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\Core\Database\Connection as main facade around Doctrine DBAL.

Example: two connections

Attention

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 (excerpt)

<?php

return [
  // ... some configuration
  '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',
    ],
  ],
  // ... more configuration
];

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.