DB - Database connections¶

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

additionalQueryRestrictions
Connections
- charset
- dbname
- driver
- host
- password
- path
- port
- tableoptions
- unix_socket
- user
TableMapping

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 ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['additionalQueryRestrictions']¶

Type: array
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 ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']¶

Type: array

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:

typo3conf/LocalConfiguration.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 (e.g. for logging or caching). For example, the following snippet could be used to swap the sys_log table to another database or even another database server:

typo3conf/LocalConfiguration.php¶

'Connections' => [
    'Default' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'typo3_database',
        'host' => '127.0.0.1',
        'password' => '***',
        'port' => 3306,
        'user' => 'typo3',
    ],
    'Syslog' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'syslog_dbname',
        'host' => 'syslog_host',
        'password' => '***',
        'port' => 3306,
        'user' => 'syslog_user',
    ],
],
'TableMapping' => [
    'sys_log' => 'Syslog',
]

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 ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['charset']¶

Type: string
Default: 'utf8'

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

dbname ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['dbname']¶

Type: string

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

driver ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['driver']¶

Type: string

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 ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['host']¶

Type: string

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

password ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['password']¶

Type: string

Password to use when connecting to the database.

path ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['path']¶

Type: string

The filesystem path to the SQLite database file.

port ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['port']¶

Type: string

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

tableoptions ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['tableoptions']¶

Type: array
Default: []

Defines the charset and collate options for tables for MySQL/MariaDB:

typo3conf/LocalConfiguration.php¶

'Connections' => [
    'Default' => [
        'driver' => 'mysqli',
        // ...
        'charset' => 'utf8mb4',
        'tableoptions' => [
            'charset' => 'utf8mb4',
            'collate' => 'utf8mb4_unicode_ci',
        ],
    ],
]

For new installations the above is the default.

unix_socket ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['unix_socket']¶

Type: string

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

user ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections'][<connection_name>]['user']¶

Type: string

Username to use when connecting to the database.

TableMapping ¶

$GLOBALS['TYPO3_CONF_VARS']['DB']['TableMapping']¶

Type: array
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 sys_log table should be swapped to another database:

typo3conf/LocalConfiguration.php¶

'Connections' => [
    'Default' => [
        // ...
    ],
    'Syslog' => [
        'charset' => 'utf8mb4',
        'driver' => 'mysqli',
        'dbname' => 'syslog_dbname',
        'host' => 'syslog_host',
        'password' => '***',
        'port' => 3306,
        'user' => 'syslog_user',
    ],
],
'TableMapping' => [
    'sys_log' => 'Syslog',
]