Last modified: July 30, 2021
The MysqlDump stream is experimental. The behavior of this endpoint may change in a future version of cPanel & WHM.
The MysqlDump stream allows you to produce a dump of a MySQL® database via WebSocket from any computer that has access to the server. You do not need to log in to your server. You can run a command to request that your server sends you the dump output. You can then use the dump output to create a backup.
Using the MysqlDump stream
To stream a dump output from cPanel or WHM, call it via any WebSocket client. You will also need an API token or authenticate via Basic HTTP Authentication to use the endpoint.
Use Basic HTTP Authentication
To use Basic HTTP Authentication, follow the directions in our Guide to API Authentication - Username and Password Authentication documentation. For more information about Basic HTTP Authentication, read the RFC 7617 documentation.
Generate an API token in cPanel
To generate a cPanel API token, use cPanel’s Manage API Tokens interface (cPanel >> Home >> Security >> Manage API Tokens). You can also use the UAPI
Tokens::create_full_access function. For more information, read our How to Use cPanel API Tokens documentation.
Generate an API token in WHM
To generate a WHM API token, use WHM’s Manage API Tokens interface (WHM >> Home >> Development >> Manage API Tokens). You can also use the WHM API 1
api_token_create function. For more information, read our Guide to API Authentication - API Tokens in WHM documentation.
root-enabled resellers can access WHM’s MysqlDump stream. For more information, read our Edit Reseller Nameserver and Privileges interface (WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges) documentation.
In WHM, you can use the MysqlDump stream to dump any MySQL database. This includes a database not managed by cPanel & WHM.
You must use the following parameters:
||The name of the database to dump.||
||The value to give the default MySQL character set. Possible values:
We recommend that you run
||A Boolean value that indicates whether to include table data in the dump.||
--no-tablespaces option if you do not need to stream tablespace information and receive the following error:
Incompatible Change: Access to the INFORMATION_SCHEMA.FILES table now requires the PROCESS privilege.
The WebSocket close frame will include one of the following status codes:
1011— General error.
4000— Collation error; try a different
4000 error codes contain an error ID. You can search the
/usr/local/cpanel/logs/error_log file to locate more information about why the command failed.
To stream a cPanel MySQL dump output via the npm wscat2 utility, run the following command:
wscat -H 'Authorization: cpanel username:GG24IS0019Q8SGI6R5EATJHLMBY3UX6Z' -c 'wss://example.com:2083/websocket/MysqlDump?dbname=username_db1&include_data=1&encoding=utf8mb4' > /$PATH/file.sql
In this example:
usernamerepresents the account’s username.
GG24IS0019Q8SGI6R5EATJHLMBY3UX6Zrepresents the cPanel API Token.
example.comrepresents any name in DNS that resolves to the server.
username_db1represents the database’s name.
/$PATH/file.sqlrepresents the directory and filename for the dump output.
The command will produce output similar to the following example: