How do I dump a cPanel database using an API token?

Question

How do I dump a cPanel database using an API token?

Answer

cPanel's MysqlDump stream sends a database dump over a WebSocket. You authenticate with an API token, so you do not need SSH access.

Note: The MysqlDump stream is experimental, and its behavior may change in a future version of cPanel & WHM.

1. Log in to cPanel.
2. Navigate to Home / Security  Manage API Tokens.
3. Click Create, enter a name, and set an expiration.
4. Copy the token. cPanel displays it only once.

5. Next, on the client, you need to install the WebSocket Client. 

   # npm install -g wscat

6. On the client machine where we installed wscat, run the dump.

   Note: Please replace USERNAME with your cPanel username. API_TOKEN with the token from Step 1. SERVER_HOSTNAME with any hostname that resolves to the server and finally, USERNAME_DBNAME with the full database name, including the prefix. Additionally, the following is required: Replace the character_set with the character set you need. utf8mb4 or utf8 If you receive a collation error, and the include_data. Where 1 includes table data; 0 dumps structure only. 

   # wscat -H "Authorization: cpanel USERNAME:API_TOKEN" -c "wss://SERVER_HOSTNAME:2083/websocket/MysqlDump?dbname=USERNAME_DBNAME&include_data=1&character_set=utf8mb4" > $USERNAME_DBNAME.sql

Additional Resources

• Close code 1000: The dump succeeded.
• Close code 4000: Collation error. Retry with character_set=utf8.
• Close code 1011: General error. The close frame includes an error ID. An administrator can search /usr/local/cpanel/logs/error_log for it.
• Certificate errors: Use a hostname with a valid certificate, or add --no-check to wscat for a self-signed certificate.
• The MysqlDump Stream