cPanel module

Mysql

25 functions, invoked through the cpanel_uapi tool.

scope cpanel:uapi

Call any function with cpanel_uapi(service_id, module="Mysql", function, params). Live availability depends on the cPanel features JetHost has enabled on your account — call list_cpanel_operations to see what is active.

add_host GET#

Enable remote MySQL host access

This function authorizes a remote MySQL® host to access the account's databases.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

hostmixedRequired

The remote MySQL server's hostname or IP address. You may use the following IP address formats: 192.168.1.6 — IP address. 192.168.%.% — Range with the percent (%) symbol as a wildcard. * 192.168.0.0/16 — Range in CIDR format.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

add_host_note GET#

Add remote MySQL host note

This function adds a note about a remote MySQL® server.

Important:

If you attempt to add a note to an unauthorized remote MySQL server, the function will fail.
When you disable the MySQL role, the system disables this function.

hostmixedRequired

notestringRequired

note that describes the remote MySQL server.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

check_database GET#

Validate MySQL database integrity

This function checks for errors in all of the tables in a MySQL® database.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

namestringRequired

The database's name.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

msg_textstring

The message's contents.

msg_typestring

The type of message. status error info note * warning Note: For more information, read MySQL's CHECK TABLE documentation.

One of: status error info note warning

tablestring

The table's name.

create_database GET#

Create MySQL database

This function creates a MySQL® database.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

namestringRequired

The new database's name.

prefix-sizeintegerOptional

The desired prefix size.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

create_user GET#

Create MySQL user

This function creates a MySQL® database user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

namestringRequired

A valid database username. Important: ==== To learn more about database username limits, check your database type: MySQL 5.6 ---- MySQL version 5.6 limits the database username to 16 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MySQL usernames of up to 13 characters. An example_ database prefix allows MySQL usernames of up to eight characters. MySQL 5.7+ ---- MySQL versions 5.7 and later limit the database username to 32 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MySQL usernames of up to 29 characters. An example_ database prefix allows MySQL usernames of up to 24 characters. MariaDB ---- MariaDB limits the database username to 47 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MariaDB usernames of up to 44 characters. An example_ database prefix allows MariaDB usernames of up to 39 characters.

passwordstringRequired

The new user's password.

prefix-sizeintegerOptional

The desired prefix size.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

delete_database GET#

Delete MySQL database

This function deletes a MySQL® database.

Important:

when you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

namestringRequired

The database's name.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

delete_host GET#

Disable remote MySQL host access

This function removes a remote MySQL® host's access to the account's databases.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

hoststringRequired

The remote MySQL server's hostname, IP Address, or IP address range. Note: You may use the following IP address formats: 192.168.1.6 — IP address. 192.168.%.% — Range with the percent (%) symbol as a wildcard. 192.168.0.0/16 — Range in CIDR format.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

delete_user GET#

Delete MySQL user

This function deletes a MySQL® user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

namestringRequired

The MySQL user's name.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

dump_database_schema GET#

Return MySQL database schema

This function returns a string that you can give to MySQL® to recreate a particular database’s schema.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

dbnamestringRequired

The database's name.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

The string to give to MySQL.

get_host_notes GET#

Return remote MySQL host notes

This function returns the notes associated with the account's remote MySQL® hosts.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

The keys are remote MySQL hostnames or IP addresses and values are their corresponding notes.

get_privileges_on_database GET#

Return MySQL user privileges

This function lists a MySQL® database user's privileges.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

databasestringRequired

The database name.

userstringRequired

The database user's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (_). For example, for the dbuser user on the user cPanel account, pass in a value of user_dbuser.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

An array of privileges. Note: If the database user does not have privileges on the database database, this array will return empty. ALL PRIVILEGES One or more of the following individual privileges: ALTER ALTER ROUTINE CREATE CREATE ROUTINE CREATE TEMPORARY TABLES CREATE VIEW DELETE DROP EVENT EXECUTE INDEX INSERT LOCK TABLES REFERENCES SELECT SHOW VIEW TRIGGER UPDATE

get_restrictions GET#

Return MySQL name length restrictions

This function lists a MySQL® database's name, username length restrictions, and database prefix.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

max_database_name_lengthinteger

The maximum length of a MySQL database name.

max_username_lengthinteger

The maximum length of a MySQL database user's name.

prefixstring

The account's database prefix, if database prefixing is enabled. If database prefixing is enabled, a string of up to the first eight characters of the cPanel account username, and an underscore (_). If database prefixing is disabled, this is null.

get_server_information GET#

Return MySQL server host information and version

This function returns information about the account's MySQL® host.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

hostany

The MySQL server's hostname or IP address.

is_remoteinteger

Whether the host is a remote MySQL server. 1 - Remote host. 0 - Local host.

One of: 0 1

versionstring

The MySQL server's version.

list_databases GET#

Return MySQL databases

This function lists an account's MySQL® databases.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

databasestring

The database name.

disk_usageinteger

The disk space that the database uses, in bytes.

usersarray<string>

A list of database usernames. Note: If no users exist on a database, the function returns an empty array.

list_routines GET#

Return MySQL user routines

This function returns a database user's MySQL® routines.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

database_userstringOptional

The database user for whom to return MySQL routines. If you don't specify a database user, this function returns the MySQL routines for all database users.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

An array of MySQL routines. If no routines exist, the function returns an empty array.

list_users GET#

Return MySQL users

This function lists an account's MySQL® database users.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

databasesarray<string>

An array of databases that belong to the database user. Note: If no users are assigned to a database, the function returns an empty array.

shortuserstring

The short version of the database username.

userstring

The database username.

locate_server GET#

Return MySQL server host information

This function returns information about the account's MySQL® host.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

is_remoteinteger

Whether the host is a remote MySQL server. 1 - Remote host. 0 - Local host.

One of: 0 1

remote_hostany

The remote MySQL server's hostname or IP address.

rename_database GET#

Update MySQL database name

This function renames a MySQL® database.

MySQL does not allow you to rename a database. When cPanel & WHM "renames" a database, the system performs the following steps: 1. The system creates a new database. 2. The system moves data from the old database to the new database. 3. The system recreates grants and stored code in the new database. 4. The system deletes the old database and its grants.

Warning:

It is potentially dangerous to rename a MySQL database. We strongly recommend that you

perform a backup of the database before you attempt to rename it.

If any of the first three steps fail, the system returns an error and attempts to restore the database's original state.

If the restoration process fails, the API function's error response describes these additional failures.

In rare cases, the system creates the second database successfully, but fails to delete the old database or grants.

The system treats the rename action as a success; however, the API function returns warnings that describe the failure to delete the old database or grants.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

newnamestringRequired

The database's new name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (_). For example, for the dbuser database on the user cPanel account, pass in a value of user_dbuser. The maximum length of the database name is 64 characters. However, due to the method that cPanel & WHM uses to store MySQL database names, each underscore character requires two characters of that limit. Therefore, if you enable database prefixing, the maximum length of the database name is 63 characters, which includes both the database prefix and the underscore character. Each additional underscore requires another two characters of that limit.

oldnamestringRequired

The database's current name.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

rename_user GET#

Update MySQL username

This function renames a MySQL® database user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

newnamestringRequired

The user's new name. Important: ==== To learn more about database username limits, check your database type: MySQL 5.6 ---- MySQL version 5.6 limits the database username to 16 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MySQL usernames of up to 13 characters. An example_ database prefix allows MySQL usernames of up to eight characters. MySQL 5.7+ ---- MySQL versions 5.7 and later limit the database username to 32 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MySQL usernames of up to 29 characters. An example_ database prefix allows MySQL usernames of up to 24 characters. MariaDB ---- MariaDB limits the database username to 47 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username. For example: A db_ database prefix allows MariaDB usernames of up to 44 characters. An example_ database prefix allows MariaDB usernames of up to 39 characters.

oldnamestringRequired

The user's current name.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

repair_database GET#

Repair MySQL database tables

This function repairs all of the tables in a MySQL® database.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

namestringRequired

The database's name.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

msg_textstring

The message's contents.

msg_typestring

The type of message. status error info note * warning Note: For more information, read MySQL's REPAIR TABLE documentation.

One of: status error info note warning

tablestring

The table's name in the database.

revoke_access_to_database GET#

Remove MySQL user privileges

This function revokes a MySQL® database user's privileges.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

databasestringRequired

The database's name.

userstringRequired

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

set_password GET#

Update MySQL user password

This function sets a MySQL® database user's password.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

passwordstringRequired

The user's new password.

userstringRequired

The MySQL database user.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

failuresarray<object>

An array of the function's error messages.

errorstring

The error message.

hoststring

The hostname that reported the error.

set_privileges_on_database GET#

Update MySQL user privileges

This function sets a MySQL® database user's privileges.

Important:

When you disable the MySQL/MariaDB role, and remote MySQL is not already configured, the system disables this function.

databasestringRequired

The database's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (_). For example, for the db database on the user cPanel account, pass in a value of user_db.

userstringRequired

privilegesstringOptional

ALL PRIVILEGES A comma-separated list of one or more of the following individual privileges: ALTER ALTER ROUTINE CREATE CREATE ROUTINE CREATE TEMPORARY TABLES CREATE VIEW DELETE DROP EVENT EXECUTE INDEX INSERT LOCK TABLES REFERENCES SELECT SHOW VIEW TRIGGER UPDATE Note: This list replaces, rather than adds to, the existing privilege list. In browser-based and command line calls, separate multiple values with %2C and replace spaces with %20.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.

setup_db_and_user GET#

Create a randomly named MySQL username/database set.

This function creates a randomly named MySQL® database and user. This allows a 3rdparty tool to create its own DB without needing any knowledge of cPanel internals such as quotas or other limits. These will simply be passed back as an error.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

prefixstringOptional

An optional string to prepend to the randomly generated database name. This is in addition to the cPanel user which will appear prior to this. The prefix should be 6 characters or less and be only alphanumeric characters. WARNING: longer prexies lead to less entropy in the random username. Keep it short if you can!

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

databaseany

The randomized name of the database created. This is normally prefixed with the account username and can also be prefixed with application prefix.

database_userany

The randomized username assigned to the database. This is normally prefixed with the account username and can also be prefixed with application prefix.

database_user_passwordstring

A randomly generated password intended to be maximally randomized.

hostnameany

The hostname to connect to from within the server to connect to the MySQL server

portstring

The port to connect to from within the server to connect to the MySQL server

update_privileges GET#

Update MySQL® privileges

This function updates privileges for all MySQL® databases and users on an account.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.