--- title: "DB - Database connections" manual: "TYPO3 Explained" version: "13.4" permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars-db@13.4" source: "Configuration/Typo3ConfVars/DB.rst" rendered: "2026-09-26T10:27:18+00:00" --- # 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@13.4) > - [config/system/additional.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-additional@13.4) ## additionalQueryRestrictions {#typo3confvars-db-additionalqueryrestrictions} - **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@13.4) for details. ## Connections {#typo3confvars-db-connections} - **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', ] ``` > [!WARNING] > **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](https://docs.typo3.org/m/typo3/reference-tca/13.4/en-us/Index.html#start) 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](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. - **defaultTableOptions** - *Type:* array - *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['defaultTableOptions'\] Defines the charset and collation options when new tables are created (MySQL/MariaDB only): **config/system/settings.php | typo3conf/system/settings.php** ```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'\]\[\\]\['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:* \[\] 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. ```diff 'Connections' => [ 'Default' => [ - 'tableoptions' => [ + 'defaultTableOptions' => [ - 'collate' => 'utf8mb4_unicode_ci', + 'collation' => 'utf8mb4_unicode_ci', ], ], ], ``` - **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 {#typo3confvars-db-tablemapping} - **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', ] ```