--- title: "DB - database connections" manual: "TYPO3 Explained" version: "14.3" permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars-db@14.3" source: "Configuration/Typo3ConfVars/DB.rst" rendered: "2026-10-01T15:20:05+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@14.3) > - [config/system/additional.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-additional@14.3) ## additionalQueryRestrictions {#typo3confvars-db-additionalqueryrestrictions} - **additionalQueryRestrictions** - *Type:* array - *Default:* \[\] - *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['additionalQueryRestrictions'\] 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@14.3) 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/14.3/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 - *Default:* 'utf8' - *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['Connections'\]\[\\]\['charset'\] 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. - **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 - *Default:* \[\] - *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['DB'\]\['TableMapping'\] 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', ], ], ]; ```