DB - Database connections

The following configuration variables can be used to configure settings for the connection to the database:

Note

The configuration values listed here are keys in the global PHP array $GLOBALS['TYPO3_CONF_VARS']['DB'].

This variable can be set in one of the following files:

additionalQueryRestrictions , Type: array
Connections , Type: array
- charset , Type: string
- dbname , Type: string
- defaultTableOptions , Type: array
- driver , Type: string
- host , Type: string
- password , Type: string
- path , Type: string
- port , Type: string
- tableoptions , Type: array
- unix_socket , Type: string
- user , Type: string
TableMapping , Type: array

additionalQueryRestrictions

Type: array
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['additionalQueryRestrictions']
Default: []

It is possible to add additional query restrictions by adding class names as key to $GLOBALS['TYPO3_CONF_VARS']['DB']['additionalQueryRestrictions']. Have a look into the chapter Custom restrictions for details.

Connections

Type: array
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']

One or more database connections can be configured under the Connections key. There must be at least one configuration with the Default key, in which the default database is configured, for example:

config/system/settings.php | typo3conf/system/settings.php

'Connections' => [
    'Default' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'typo3_database',
        'host' => '127.0.0.1',
        'password' => 'typo3',
        'port' => 3306,
        'user' => 'typo3',
    ],
]

It is possible to swap out tables from the default database and use a specific setup (for instance, for caching). For example, the following snippet could be used to swap the be_sessions table to another database or even another database server:

config/system/settings.php | typo3conf/system/settings.php

'Connections' => [
    'Default' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'typo3_database',
        'host' => '127.0.0.1',
        'password' => '***',
        'port' => 3306,
        'user' => 'typo3',
    ],
    'Sessions' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'sessions_dbname',
        'host' => 'sessions_host',
        'password' => '***',
        'port' => 3306,
        'user' => 'some_user',
    ],
],
'TableMapping' => [
    'be_sessions' => 'Sessions',
]

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.

Note

The connection options described below are the most commonly used. These options correspond to the options of the underlying Doctrine DBAL library. Please refer to the Doctrine DBAL connection details for a full overview of settings.

charset

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['charset']
Default: 'utf8'

The charset used when connecting to the database. Can be used with MySQL/MariaDB and PostgreSQL.

dbname

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['dbname']

Name of the database/schema to connect to. Can be used with MySQL/MariaDB and PostgreSQL.

defaultTableOptions

Type: array
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['defaultTableOptions']

Defines the charset and collation options when new tables are created (MySQL/MariaDB only):

config/system/settings.php | typo3conf/system/settings.php

'Connections' => [
    'Default' => [
        'driver' => 'mysqli',
        // ...
        'charset' => 'utf8mb4',
        'defaultTableOptions' => [
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
        ],
    ],
]

For new installations the above is the default.

driver

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['driver']

The built-in driver implementation to use. The following drivers are currently available:

mysqli: A MySQL/MariaDB driver that uses the mysqli extension.
pdo_mysql: A MySQL/MariaDB driver that uses the pdo_mysql PDO extension.
pdo_pgsql: A PostgreSQL driver that uses the pdo_pgsql PDO extension.
pdo_sqlite: An SQLite driver that uses the pdo_sqlite PDO extension.

host

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['host']

Hostname or IP address of the database to connect to. Can be used with MySQL/MariaDB and PostgreSQL.

password

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['password']

Password to use when connecting to the database.

path

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['path']

The filesystem path to the SQLite database file.

port

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['port']

Port of the database to connect to. Can be used with MySQL/MariaDB and PostgreSQL.

tableoptions

Type: array
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['tableoptions']
Default: []

Deprecated since version 13.4

Since TYPO3 v11 the tableoptions keys were silently migrated to defaultTableOptions, which is the proper Doctrine DBAL connection option for MariaDB and MySQL.

Furthermore, Doctrine DBAL 3.x switched from using the array key collate to collation, ignoring the old array key with Doctrine DBAL 4.x. This was silently migrated by TYPO3, too.

These silent migrations are now deprecated in favor of using the final array keys.

Migration:

Review settings.php and additional.php and adapt the deprecated configuration by renaming affected array keys.

 'Connections' => [
     'Default' => [
-        'tableoptions' => [
+        'defaultTableOptions' => [
-            'collate' => 'utf8mb4_unicode_ci',
+            'collation' => 'utf8mb4_unicode_ci',
         ],
     ],
 ],

unix_socket

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['unix_socket']

Name of the socket used to connect to the database. Can be used with MySQL/MariaDB.

user

Type: string
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['user']

Username to use when connecting to the database.

TableMapping

Type: array
Path: $GLOBALS['TYPO3_CONF_VARS']['DB']['TableMapping']
Default: []

When a TYPO3 table is swapped to another database (either on the same host or another host) this table must be mapped to the other database.

For example, the be_sessions table should be swapped to another database:

config/system/settings.php | typo3conf/system/settings.php

'Connections' => [
    'Default' => [
        // ...
    ],
    'Sessions' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'sessions_dbname',
        'host' => 'sessions_host',
        'password' => '***',
        'port' => 3306,
        'user' => 'some_user',
    ],
],
'TableMapping' => [
    'be_sessions' => 'Sessions',
]