backdrop-issues icon indicating copy to clipboard operation
backdrop-issues copied to clipboard

Document `$database_charset` setting in `settings.php`

Open argiepiano opened this issue 3 years ago • 2 comments

Backdrop allows the use of UTF8-MB4 database encoding (which allows for the use of Asian characters and emojis). This feature is documented online at this page.

It would be great to also see some documentation about this feature in the settings.php file, as a commented line, like all other features in this file.

argiepiano avatar Oct 05 '22 13:10 argiepiano

At the time this feature was implemented, many MySQL/MariaDB installs did not have the required configuration set as defaults. Now they do. It would be nice if we could include this line as a not-commented out line. Like the default database connection and prefix. Right now the installer appends the line at the bottom of the file if the site supports UTF-8 MB4. Now that this is so widespread it'd be better IMO if we included it by default at the top of the file with the default of utf8mb4, and commented-out if necessary.

quicksketch avatar Oct 13 '22 07:10 quicksketch

PR filed at https://github.com/backdrop/backdrop/pull/4259 that documents the $database_charset value and includes setting it to utf8mb4 by default now. When running the installer, it will update this line to be utf8 if utf8mb4 is not supported.

While updating the documentation for database connections, I also added a sentence about $database_prefix, and replaced the single instance of master/slave terminology with primary/replica (as is done in https://github.com/backdrop/backdrop-issues/issues/4451). Since we don't often update settings.php, I thought it would be a good opportunity to change this single instance.

To test:

  • Start with an empty database and clean settings.php file from this PR.
  • Visit core/install.php.
  • Select English as the install language.
  • Enter your database credentials.
  • Install Backdrop.
  • If your database supports UTF8MB4 the $database, $config_directories and $settings['hash_salt'] lines should be updated. The $database_charset line should stay the same, since it is now utf8mb4 out of the box.
  • If your database does not support UTF8MB4, the $database_charset line should be rewritten by the installer to be utf8.
  • You can also confirm the line gets updated if your server does support UTF8MB4 by starting over, and set the line to utf8 before running install.php. After entering the database credentials, the line will be switched to utf8mb4.

Note that the settings.php file only gets automatically rewritten if you set the database string through the UI. If You specify a string directly in settings.php, the database settings UI portion of the installer is skipped, and whatever value is in settings.php for $database_charset is left unmodified. I think that's expected for anyone manually setting their database configuring in settings.php.

quicksketch avatar Nov 27 '22 04:11 quicksketch

PHPCS flagged coding standards in settings.php. Although the flagged lines are not part of this PR's changes, it might be appropriate to make the changes here.

There is the question (in the PR) of whether to use primary/replica (as in https://github.com/backdrop/backdrop-issues/issues/4451) or primary/secondary (as in https://docs.backdropcms.org/documentation/database-configuration). If we use the former, we should update the docs page, and vice-versa. Which is preferred?

bugfolder avatar Sep 19 '23 01:09 bugfolder