Skip to content

Restoring a mysqldump into a cPanel account without surprising the user mapping

A restore that succeeds in SQL terms can still leave the cPanel account confused about which databases it owns. Here is the sequence that keeps the dbmap and the data in sync.

Restoring a database into a cPanel account is two operations, not one. The first is the SQL restore — pipe the dump into mysql, watch it run. The second is making cPanel acknowledge that the database exists and belongs to the account. The second step is what people skip, and it’s why you see accounts where phpMyAdmin shows a database that the cPanel UI insists isn’t there, or vice versa. The dbmap is a separate index that cPanel uses to scope permissions, backups, and account migrations; if you restore data without updating the map, half the platform features stop seeing the database.

What’s happening

cPanel maintains a per-account database registry at /var/cpanel/databases/<user>.json (or the legacy users.db.cache). This registry says “account acmecorp owns these databases and these users.” When you mysql < dump.sql as root, MySQL creates the database and tables, but cPanel has no idea it happened. The next time the user runs MySQL Databases in cPanel, they don’t see the restored database. Backups configured per-account don’t include it. Account migrations to another WHM server miss it entirely. A clean restore needs both the data and the map.

How to verify

Before restore:

whmapi1 list_dbs user=acmecorp
ls /var/cpanel/databases/acmecorp.*
mysql -e "SELECT User, Host FROM mysql.user WHERE User LIKE 'acmecorp\\_%'"
df -h /var/lib/mysql

The first lists what cPanel currently believes the account owns. The second confirms the dbmap exists for this account (if missing, the account is broken — fix the map first). The user list shows existing prefixed users (you’ll need at least one for the new database). The df is a sanity check — InnoDB restores can briefly double disk usage during table rebuild.

After restore, the same whmapi1 list_dbs should now include the restored database name. If it doesn’t, the map was not updated.

The fix

  1. Pre-create the database via the API so the dbmap is correct from the start:
    uapi --user=acmecorp Mysql create_database name=wp
    This creates acmecorp_wp in MySQL and adds it to the cPanel map. Now the database exists empty, the map knows about it, and the user owns it.
  2. Restore data into the pre-created database:
    zcat /home/acmecorp/backups/acmecorp_wp-2026-05-19.sql.gz | mysql --max_allowed_packet=512M acmecorp_wp
    Note: no CREATE DATABASE in the dump, no USE statement — you’re restoring tables into an existing database. If the dump has CREATE DATABASE acmecorp_wp, MySQL ignores it because the database already exists; if it has CREATE DATABASE IF NOT EXISTS oldname, that creates a separate database and the data goes there instead. Inspect the first 20 lines of the dump before piping.
  3. Re-grant if the user is new or the password rotated:
    uapi --user=acmecorp Mysql set_privileges_on_database user=acmecorp_wp database=acmecorp_wp privileges=ALL
  4. If you restored a database that cPanel did not know about (you ran the SQL restore first and only realized later), repair the map:
    /usr/local/cpanel/bin/dbmaprepair --dbmap-clobber acmecorp
    This rebuilds the dbmap from the live MySQL grants and database list. Idempotent and safe to re-run.
  5. Verify by browsing: open the cPanel account, navigate to MySQL Databases, confirm the database appears with the expected row count. Then phpMyAdmin to spot-check a table. If both show the data, you’re done.
  6. For per-account backups to pick up the restored database, the dbmap must be correct before the next backup window. Otherwise the backup tooling will skip the database entirely and a restore drill three months from now will find nothing.

For takeover migrations where dozens of accounts need restored databases with intact dbmap, Stack Harbor’s cPanel server administration team scripts the create-restore-map-verify sequence per account and runs the verification at the end.