This project is not covered by Drupal’s security advisory policy.

Drush command that converts existing MySQL UTF8 databases into UTF8MB4.

Note: this will set the engine to be InnoDB for all tables that are managed by Drupal (so MyISAM tables will be automatically converted).

THIS IS NOT A MODULE. YOU CAN'T ENABLE IT. This is an experimental project. Make a backup of your database before running this!


  • Ensure Drupal core 7.50 or later is installed.
  • Ensure the requirements listed in default.settings.php are met:
    • In order to allow for large indexes, MySQL must be set up with the following my.cnf settings:

      These settings are available as of MySQL 5.5.14, and are defaults in MySQL 5.7.7 and up. After editing my.cnf don't forget to restart the mysql server!

    • The PHP MySQL driver must support the utf8mb4 charset (libmysqlclient
      5.5.3 and up, as well as mysqlnd 5.0.9 and up)
    • The MySQL server must support the utf8mb4 charset (5.5.3 and up).


  • Run drush @none dl utf8mb4_convert-7.x and drush will download it into your .drush folder. (Alternately, you can obtain the package another way and copy the folder into .drush yourself.)
  • Clear the Drush cache with "drush cc drush".


  1. Make backups of your databases.
  2. Comment out any MySQL databases listed in settings.php that you do not want to convert.
  3. Put your site into maintenance mode: drush vset maintenance_mode 1
  4. Run drush utf8mb4-convert-databases
  5. Enable utf8mb4 in your settings.php:
    $databases['default']['default'] = array(
      'driver' => 'mysql',
      'database' => 'databasename',
      'username' => 'username',
      'password' => 'password',
      'host' => 'localhost',
      'charset' => 'utf8mb4',
      'collation' => 'utf8mb4_general_ci',
  6. Take your site out of maintenance mode: drush vset maintenance_mode 0

Issue in versions prior to 7.x-1.0-beta2

Versions prior to 7.x-1.0-beta2 included an issue which would change column definitions for certain columns in that it would lose description, default value, and not null definitions: #2781545: Respect original default value, not null and comment definitions

If possible, recover a backup (from before the script was run), and re-run the script using 7.x-1.0-beta2 or later. Alternatively, inspect the database for differences using the Schema module. We are working on an automated solution (see issue #2781545).

Project Information