Cloud Platform

About UTF-8 support in Drupal 7

As of version 7.50, Drupal supports the use of multi-byte UTF-8 characters. For reference, Cloud Platform and previous Drupal versions supported some versions of UTF8. Newer versions of Drupal support utf8mb4 by default.

To ensure that your Acquia-hosted Drupal 7 website can use UTF-8, complete the following steps:

  • Examine your database connections. Acquia has already taken care of the basic infrastructure requirements for utf8mb4, namely the innodb_large_prefix, innodb_file_format, and innodb_file_per_table configurations described in the documentation.

  • Alter your database connection settings. A variation on the normally-recommended database connection code in the settings.php file is required to ensure that the database’s character set and collation are appropriate for utf8mb4 content. Add the following code in place of our regular include statement, ensuing that you edit the website and database names to match your own environment (for more information, see Working with databases):

    // Note that SITE_NAME and DATABASE_NAME should be replaced accordingly in
    // the following code:
    if (file_exists('/var/www/site-php')) {
       // Delay the initial database connection.
        $conf['acquia_hosting_settings_autoconnect'] = FALSE;
       // The standard require line goes here.
       // Alter the charset and collation of the databases.
          $databases['default']['default']['driver'] = 'mysql';
          $databases['default']['default']['charset'] = 'utf8mb4';
          $databases['default']['default']['collation'] = 'utf8mb4_general_ci';
          $databases['[DATABASE_NAME]']['default']['charset'] = 'utf8mb4';
          $databases['[DATABASE_NAME]']['default']['collation'] = 'utf8mb4_general_ci';
          // Now connect to the default database.
  • If your website was upgraded from a version of Drupal before version 7.5: The character set and collation for database tables are most likely not appropriate for utf8mb4. In this case, you must manually alter the tables, or instead use a tool such as utf8mb4 Convert.


    During this activity we recommend that you first create a complete backup of your database(s), and then rehearse this step on non-production environments and ensure that production sites are set to maintenance mode.

  • Ensure that your database backups will accept these characters.

    The mysqldump command, used for creating database backups and copies, can use configuration overrides beyond those provided by Cloud Platform. These overrides are made in a file called ~/.my.cnf that you can create on the infrastructure for one or more environments.

    The contents of the ~/.my.cnf file should be as follows:


    This file will apply to all websites in your environment. If you are using multisites and have not yet completed converting all of your websites to utf8mb4, there may be unpredictable results.

    [client] loose-default-character-set = utf8mb4  [mysqldump] default-character-set=utf8mb4

    This file can be created in non-production environments for testing, prior to its creation in the home directory of your production environment.