Reading and changing database settings #

This page is for database administrators who need to read the connection settings of a running site, or change them: a new password, a new host after a migration, a different engine. It answers: where the values are kept, how to see the value in effect and the file it comes from, how to write a change, and what to restart so that every process uses it. Sources: 9.1 and exp:ini.

Contents #

1. Where the values are kept
2. Read the value in effect
3. Find the file a value comes from
4. Change a value
5. Make every process read it
6. Changing the password
7. Common mistakes

Where the values are kept #

settings/override/ wins over every extension. The override files hold the database password: keep them out of version control (Securing the database).

Read the value in effect #

php bin/php/console exp:ini get site.ini/DatabaseSettings/DatabaseImplementation --allow-root-user
php bin/php/console exp:ini get site.ini/DatabaseSettings/Database --allow-root-user
php bin/php/console exp:ini list site.ini/DatabaseSettings global --allow-root-user

The console first prints a line naming the script it runs, on the error stream, then the value alone, for example sqlite3. Values whose name looks like a secret (Password among them) are shown as ********; --show-secrets shows them, so use it only where nobody reads over your shoulder.

In the administration, Setup > System information shows the engine, server, database name and character set in the Database card and the Database connection part; the database user and password are never shown there (System information).

Find the file a value comes from #

php bin/php/console exp:ini where site.ini/DatabaseSettings/Server --allow-root-user
php bin/php/console exp:ini where site.ini/DatabaseSettings/Server admin --allow-root-user   # for the siteaccess admin

where lists every file that sets the variable, in the order the settings are loaded, and the value in effect. A value you changed that still shows the old one means the change went into a file or a block that is not read.

Change a value #

Edit settings/override/site.ini.append.php with an editor, or let exp:ini write it and record the change:

php bin/php/console exp:ini set site.ini/DatabaseSettings/Server db2.example.internal global --dry-run --allow-root-user
php bin/php/console exp:ini set site.ini/DatabaseSettings/Server db2.example.internal global --allow-root-user

--dry-run shows the change without writing. The scope global writes settings/override/; siteaccess:<name> writes that siteaccess's file. Avoid putting a password on the command line on a shared machine: it is visible in the process list and the shell history; edit the file instead.

Make every process read it #

php bin/php/ezcache.php --clear-tag=ini --allow-root-user
php bin/php/console exp:velocity restart --allow-root-user       # only when Velocity serves the site

• Clear the INI cache with --clear-tag=ini.
• Reload the PHP-FPM pool that serves the site, gracefully, so that no worker keeps the old connection (Deploying, reload the right PHP-FPM).
• Velocity's workers read site.ini when they start; restart them.
• Cronjobs and console commands read the settings at every run.

Changing the password #

1. Set the new password on the database server for the site's account, keeping the old one valid if the engine allows it (or plan a short maintenance window).
2. Write the new password into settings/override/site.ini.append.php.
3. Clear the INI cache, reload PHP-FPM, restart Velocity.
4. Load a page and sign in to the administration.
5. Remove the old password on the server.

If the site uses the DFS cluster, its metadata database has its own login in file.ini [eZDFSClusteringSettings] and in config.cluster.php (Clustering: DFS and its metadata database).

Common mistakes #

Related pages #

• The DatabaseSettings reference
• Troubleshooting database errors
• Where the connection is stored (for hosting companies)
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.