The DatabaseSettings reference
This page is for database administrators who read or write the connection settings of an Exponential site. It lists
every key of settings/site.ini, block [DatabaseSettings], as shipped in 6.0.x, with its default and the engines
that use it, and gives a minimal block per engine. Sources: settings/site.ini and
9.1 How Exponential chooses a database driver.
Note
Never edit settings/site.ini itself: an upgrade replaces it. Put your values in
settings/override/site.ini.append.php (the whole installation) or settings/siteaccess/<name>/site.ini.append.php
(one siteaccess). See Reading and changing database settings.
Contents
- Connection keys
- Behavior keys
- Replica keys
- Debug keys
- SQLite keys
- Driver aliases
- Keys outside this block
- Minimal blocks per engine
Connection keys
| Key | Shipped default | Used by | Meaning |
|---|---|---|---|
DatabaseImplementation | ezmysqli | all | The driver alias (Driver aliases). The installers write the value for your engine. |
Server | localhost | MySQL, PostgreSQL, MongoDB | Host name or address. Not used by Oracle. |
Port | empty | MySQL, PostgreSQL, MongoDB | Empty means the driver's default port (3306, 5432, 27017). Not used by Oracle. |
Socket | disabled | MySQL, MariaDB | A Unix socket path instead of host and port. |
User, Password | root, empty | all but SQLite | The login. Never keep the shipped root in production. MongoDB requires a user even without access control. |
Database | nextgen | all | The database name; for SQLite the file; for Oracle the connect string. |
Charset | utf-8 | MySQL, Oracle | The connection character set (Character sets and collations). |
UseBuiltinEncoding | true | "Use charset conversion routines in DB if possible" (comment in site.ini). |
Behavior keys
| Key | Shipped default | Used by | Meaning |
|---|---|---|---|
ConnectRetries | 0 | MySQL, PostgreSQL, SQLite | How often to try again when the first connection fails. MySQL and PostgreSQL wait between attempts; SQLite tries again at once. Oracle has its own RetryCount and falls back to this value. |
UsePersistentConnection | disabled | MySQL, PostgreSQL, Oracle | Reuse a connection across requests of the same PHP process (p: host prefix for mysqli, pg_pconnect for PostgreSQL). |
Transactions | enabled | all | Run grouped writes in transactions. Leave it on. |
Replica keys
| Key | Shipped default | Meaning |
|---|---|---|
UseSlaveServer | disabled | Send reads to a replica chosen at random per request; writes go to Server. MySQL and MariaDB only. |
SlaveServerArray[], SlaveServerPort[] | commented out | Replica hosts and ports. |
SlaverServerUser[], SlaverServerPassword[], SlaverServerDatabase[] | commented out | Replica logins and database names. The keys really are spelled Slaver.... |
See MySQL and MariaDB read replicas.
Debug keys
| Key | Shipped default | Used by | Meaning |
|---|---|---|---|
SQLOutput | disabled | all | Show statements in the debug output. |
SlowQueriesOutput | 0 | all | With a value above 0, only statements slower than this many milliseconds. |
QueryAnalysisOutput | disabled | MySQL, MariaDB | With SQLOutput=enabled, MySQL's EXPLAIN of each statement. |
DebugTransactions | disabled | all | Record a stack trace for every begin and commit, to find an unbalanced transaction. |
These only show when the debug output is on for your address. See Finding slow queries.
SQLite keys
| Key | Shipped default | Meaning |
|---|---|---|
SQLitePragmas[] | empty | PRAGMAs over the driver's defaults, one name=value per entry. |
SQLiteTransactionWait | 25 | Seconds a transaction waits for the writers ahead of it. Keep it below the web server's request timeout. |
SQLiteCLITransactionWait | 300 | The same on the command line (cronjobs, imports, scripts). |
SQLiteBusyTimeout | 5000 | Milliseconds a single statement waits for another write in a web request. |
SQLiteCLIBusyTimeout | 30000 | The same on the command line. |
Details: SQLite: the write queue and locking and SQLite maintenance.
Driver aliases
ImplementationAlias[] maps the value of DatabaseImplementation to a class. Shipped:
mysql, mysqli, ezmysql, ezmysqli to eZMySQLiDB; postgresql, ezpostgresql, pgsql to eZPostgreSQLDB;
sqlite3 to eZSQLite3DB; mongodb to expMongoDB. The ezoracle extension adds ezoracle and oracle. An
extension can add more aliases from its own site.ini.append.php.
Keys outside this block
| Setting | Where | Meaning |
|---|---|---|
Oracle-only keys OracleEmptyStringForNull, OracleCaseInsensitive, OracleCaseInsensitiveSort | site.ini [DatabaseSettings], read by ezoracle | See Setting up Oracle |
| Connection pooling, retries, tracing for Oracle | ezoracle.ini | See Oracle: persistent connections, DRCP and tuning |
| The SQL query cache | querycache.ini [QueryCacheSettings] | See The SQL query cache |
| The DFS cluster metadata database | file.ini [eZDFSClusteringSettings] | See Clustering: DFS and its metadata database |
| Sessions in the database | site.ini [Session] Handler | See Sessions in the database |
Minimal blocks per engine
# SQLite 3
[DatabaseSettings]
DatabaseImplementation=sqlite3
Database=exponential.db
# PostgreSQL
[DatabaseSettings]
DatabaseImplementation=ezpostgresql
Server=localhost
Port=5432
User=exponential
Password=<the password>
Database=exponential
# MariaDB and MySQL
[DatabaseSettings]
DatabaseImplementation=ezmysqli
Server=localhost
User=exponential
Password=<the password>
Database=exponential
Charset=utf-8MongoDB and Oracle blocks are on Setting up MongoDB and Setting up Oracle. The placeholder values are examples; use your own and never commit the override file.
Related pages
- Reading and changing database settings
- The database layer in one page
- Database support, the settings
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.