Converting utf8 databases to utf8mb4

Databases created on a BOA server store text as utf8mb4 — the full Unicode encoding that handles emoji and every modern script. Older servers used MySQL's original 3-byte utf8, and a site that arrived here as a dump from one of them usually still carries it. That works — until the mixed case bites: after an upgrade or migration the site can end up with 3-byte tables and 4-byte tables side by side, and JOIN-heavy pages start failing with illegal mix of collations errors.

The Convert to utf8mb4 task on your site's page fixes this in one step, and it is built to be safe to run even when you are not sure it is needed:

1. it inspects the database first — when nothing uses 3-byte utf8 any more, the task simply reports that and changes nothing;
2. otherwise it takes a fresh backup, puts the site into maintenance mode, converts every utf8 table and text column to utf8mb4, verifies the result against the database's own metadata, and brings the site back online.

On a large database the conversion can take several minutes; the site shows its maintenance page for that window. If a step hits a transient error — a brief lock from a live request caught mid-ALTER, say — the task retries it automatically before giving up. The task log names the backup it took, and re-running the task is always safe — tables already converted are skipped, so a run that stopped partway simply finishes the remainder.

The safe workflow

Test the conversion on a throwaway copy before touching the site your visitors use:

1. Clone the site (the Clone task on its page).
2. Run Convert to utf8mb4 on the clone.
3. Click through the clone — pages with comments, listings, search.
4. Satisfied? Convert the real site the same way — or keep working with the converted clone and retire the original.

When you'll want it

• Before upgrading an imported Drupal 7 site to Backdrop. The upgrade copies your database onto a server whose new databases are utf8mb4; a 3-byte source makes the mixed case above. Convert first, then upgrade — the Backdrop copy inherits the converted tables and the problem never appears.
• Between the two Drupal 6 steps. Drupal 6 sites store text in 3-byte utf8 (that was the era's standard), so the Drupal 7 copy that step one produces carries it too. Run the conversion on that Drupal 7 copy before step two.
• On any imported Drupal 7 site, upgrade plans or not — 4-byte content (emoji in comments, for a start) cannot be saved into 3-byte tables.

The task exists for Drupal 7 sites only: Drupal 6 core predates MySQL's utf8mb4 support entirely, and Backdrop sites never need it — a Backdrop site created by the upgrade task inherits whatever the Drupal 7 source had, which is exactly why converting before the upgrade is the right order. A Backdrop site imported from elsewhere with 3-byte tables is a rare case the task does not cover; ask your host.

The task is administrative like the upgrade tasks: if your panel login doesn't show it on the site's page, ask your host to run it for you.