--- title: "DB - Database connections" manual: "TYPO3 Explained" version: "11.5" permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars-db@11.5" source: "Configuration/Typo3ConfVars/DB.rst" rendered: "2026-10-21T15:30:00+00:00" --- > [!WARNING] > **Attention** > > TYPO3 v11 has reached end-of-life as of October 31th 2024 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 v11 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: - [additionalQueryRestrictions](https://docs.typo3.org/permalink/t3coreapi:additionalqueryrestrictions@11.5) - [Connections](https://docs.typo3.org/permalink/t3coreapi:connections@11.5) - [TableMapping](https://docs.typo3.org/permalink/t3coreapi:tablemapping@11.5) > [!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: > > - [typo3conf/LocalConfiguration.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-localconfiguration@11.5) > - [typo3conf/AdditionalConfiguration.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-additionalconfiguration@11.5) ## additionalQueryRestrictions {#typo3confvars-db-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](https://docs.typo3.org/permalink/t3coreapi:database-custom-restrictions@11.5) for details. ## Connections {#typo3confvars-db-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** ```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: **typo3conf/LocalConfiguration.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/2.13/reference/configuration.html#connection-details) > for a full overview of settings. ### charset {#typo3confvars-db-connections-charset} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['charset'\]** - *Type:* string - *Default:* 'utf8' The charset used when connecting to the database. Can be used with MySQL/MariaDB and PostgreSQL. ### dbname {#typo3confvars-db-connections-dbname} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['dbname'\]** - *Type:* string Name of the database/schema to connect to. Can be used with MySQL/MariaDB and PostgreSQL. ### driver {#typo3confvars-db-connections-driver} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['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 {#typo3confvars-db-connections-host} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['host'\]** - *Type:* string Hostname or IP address of the database to connect to. Can be used with MySQL/MariaDB and PostgreSQL. ### password {#typo3confvars-db-connections-password} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['password'\]** - *Type:* string Password to use when connecting to the database. ### path {#typo3confvars-db-connections-path} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['path'\]** - *Type:* string The filesystem path to the SQLite database file. ### port {#typo3confvars-db-connections-port} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['port'\]** - *Type:* string Port of the database to connect to. Can be used with MySQL/MariaDB and PostgreSQL. ### tableoptions {#typo3confvars-db-connections-tableoptions} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['tableoptions'\]** - *Type:* array - *Default:* \[\] Defines the charset and collate options for tables for MySQL/MariaDB: **typo3conf/LocalConfiguration.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 {#typo3confvars-db-connections-unixsocket} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['unix_socket'\]** - *Type:* string Name of the socket used to connect to the database. Can be used with MySQL/MariaDB. ### user {#typo3confvars-db-connections-user} - **$GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['user'\]** - *Type:* string Username to use when connecting to the database. ## TableMapping {#typo3confvars-db-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 `be_sessions` table should be swapped to another database: **typo3conf/LocalConfiguration.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', ] ```