---
title: "DB - Database connections"
manual: "TYPO3 Explained"
version: "12.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars-db@12.4"
source: "Configuration/Typo3ConfVars/DB.rst"
rendered: "2026-10-21T15:29:37+00:00"
---
> [!WARNING]
> **Attention**
>
> TYPO3 v12 has reached end-of-life as of April 30th 2026 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v12 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).
# DB - Database connections {#typo3confvars-db}
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:
>
> - [config/system/settings.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-settings@12.4)
> - [config/system/additional.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-additional@12.4)
- **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](https://docs.typo3.org/permalink/t3coreapi:database-custom-restrictions@12.4) 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**
```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**
```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',
]
```
> [!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](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html#connection-details)
> for a full overview of settings.
- **charset**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['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'\]\[\\]\['dbname'\]
Name of the database/schema to connect to. Can be used with
MySQL/MariaDB and PostgreSQL.
- **driver**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['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'\]\[\\]\['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'\]\[\\]\['password'\]
Password to use when connecting to the database.
- **path**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['path'\]
The filesystem path to the SQLite database file.
- **port**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['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'\]\[\\]\['tableoptions'\]
- *Default:* \[\]
Defines the charset and collate options for tables for MySQL/MariaDB:
**config/system/settings.php | typo3conf/system/settings.php**
```php
'Connections' => [
'Default' => [
'driver' => 'mysqli',
// ...
'charset' => 'utf8mb4',
'tableoptions' => [
'charset' => 'utf8mb4',
'collate' => 'utf8mb4_unicode_ci',
],
],
]
```
For new installations the above is the default.
- **unix_socket**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['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'\]\[\\]\['user'\]
Username to use when connecting to the database.
- **initCommands**
- *Type:* string
- *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['initCommands'\]
Initial commands to execute after connecting to the database.
For example, database session options.
- **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**
```php
'Connections' => [
'Default' => [
// ...
],
'Sessions' => [
'charset' => 'utf8mb4',
'driver' => 'mysqli',
'dbname' => 'sessions_dbname',
'host' => 'sessions_host',
'password' => '***',
'port' => 3306,
'user' => 'some_user',
],
],
'TableMapping' => [
'be_sessions' => 'Sessions',
]
```