CREATE USER
Syntax
CREATE [OR REPLACE] USER [IF NOT EXISTS] user_specification [,user_specification] ... [REQUIRE {NONE | tls_option [[AND] tls_option] ...}] [WITH resource_option [resource_option] ...] user_specification: username [authentication_option] authentication_option: IDENTIFIED BY 'password' | IDENTIFIED BY PASSWORD 'password_hash' | IDENTIFIED {VIA|WITH} authentication_plugin | IDENTIFIED {VIA|WITH} authentication_plugin {USING|AS} 'authentication_string' | IDENTIFIED {VIA|WITH} authentication_plugin {USING|AS} PASSWORD('password') tls_option: SSL | X509 | CIPHER 'cipher' | ISSUER 'issuer' | SUBJECT 'subject' resource_option: MAX_QUERIES_PER_HOUR count | MAX_UPDATES_PER_HOUR count | MAX_CONNECTIONS_PER_HOUR count | MAX_USER_CONNECTIONS count
Contents
Description
The CREATE USER
statement creates new MariaDB accounts. To use it, you must have the global CREATE USER
privilege or the INSERT
privilege for the mysql database. For each account, CREATE USER
creates a new row in
the mysql.user table that has no privileges.
See Account Names below for details on how account names are specified.
If any of the specified user accounts, or any permissions for the specified users, already exist (for example in some setups, ''@'%'
has all privileges on the test
database), ERROR 1396 (HY000)
results. If an error occurs, CREATE USER
will still create the accounts that do not result in an error. Only one error is produced for all users which have not been created:
ERROR 1396 (HY000): Operation CREATE USER failed for 'u1'@'%','u2'@'%'
Failed CREATE
or DROP
operations, for both users and roles, produce the
same error code.
The account can be given a password with the optional IDENTIFIED BY
clause.
To specify the password in plain text, omit the PASSWORD
keyword. To
specify the password as the hashed value as returned by the
PASSWORD
function, include the PASSWORD
keyword.
If you do not specify a password with the IDENTIFIED BY
clause, the user
will be able to connect without a password. A blank password is not a wildcard
to match any password. The user must connect without providing a password if no
password is set.
If you specify a plugin using the VIA
clause, the plugin name must be an
active authentication plugin as per show plugins. If it
doesn't show up you will need to install it with INSTALL
PLUGIN or install-soname).
For valid identifiers to use as user names, see Identifier Names.
OR REPLACE
MariaDB starting with 10.1.3
If the optional OR REPLACE
clause is used, it acts as a shortcut for:
DROP USER IF EXISTS name; CREATE USER name ...;
IF NOT EXISTS
MariaDB starting with 10.1.3
When the IF NOT EXISTS
clause is used, MariaDB will return a warning instead of an error if the specified user already exists.
MAX_*_PER_HOUR
MariaDB starting with 10.2.0
Limit to the number of queries, updates or connections the user can place or make per hour. The query count excludes results returned from the query cache. If set to zero, the default, no limit is imposed.
MAX_USER_CONNECTIONS
MariaDB starting with 10.2.0
Limit to the number of simultaneous connections that the user can hold. If set to 0
, no limit is imposed. It defaults to the value of the max_user_connections
system variable, which is 0
by default.
tls_options
MariaDB starting with 10.2.0
MariaDB 10.2.0 introduced a number of tls options.
SSL
Specifies that the server will only permit encrypted TLS connections for the user.
X509
Requires the client to have a valid certificate whose signature can be verified with one of the CA certificates, although the issuer, subject and exact certificate are not checked. Implies encryption, so there's no need for the SSL
option.
ISSUER
Requires the client to have a valid certificate issued by the specified issuer. Implies encryption, so there's no need for the SSL
option. The client must specify the --ssl-key and --ssl-cert options to connect, and it is also recommended that the --ssl-ca option be specified in order to verify the server's public certificate.
SUBJECT
Requires the client to have a valid certificate with the specified subject. Implies encryption, so there's no need for the SSL
option. The client must specify the --ssl-key and --ssl-cert options to connect, and it is also recommended that the --ssl-ca option be specified in order to verify the server's public certificate.
CIPHER
Specifies that a specific cipher method is used for encrypting connections.
Account Names
Account names have both a user name and a host name, and are specified as 'user_name'@'host_name'
.
When you connect to a MariaDB server, your user name and host must match a single account.
The user name and host name may be unquoted, quoted as strings using double quotes ("
) or
single quotes ('
), or quoted as identifiers using backticks (`
). You must use quotes
when using special characters (such as a hyphen) or wildcard characters. If you quote, you
must quote the user name and host name separately (for example 'user_name'@'host_name'
).
Host Names
If the host name is not provided, it is assumed to be '%'
.
Host names may contain the wildcard characters %
and _
. They are matched as if by
the LIKE
clause. If you need to use a wildcard character literally (for example, to
match a domain name with an underscore), prefix the character with a backslash. See LIKE
for more information on escaping wildcard characters.
Host name matches are case-insensitive. Host names can match either domain names or IP
addresses. Use 'localhost'
as the host name to allow only local client connections.
You can use a netmask to match a range of IP addresses using 'base_ip/netmask'
as the
host name. A user with an IP address ip_addr will be allowed to connect if the following
condition is true:
ip_addr & netmask = base_ip
You can only use netmasks that specify a multiple of 8 bits of the address to match. That is, only the following netmasks are allowed:
255.0.0.0 255.255.0.0 255.255.255.0 255.255.255.255
Using 255.255.255.255
is equivalent to not using a netmask at all.
User Names
User names must match exactly, including case. You can use the empty string to allow a user with any user name.
It is possible for more than one account to match when a user connects. MariaDB selects the first matching account after sorting according to the following criteria:
- Accounts with an exact host name are sorted before accounts using a wildcard in the host name. Host names using a netmask are considered to be exact for sorting.
- Accounts with a wildcard in the host name are sorted according to the position of the first wildcard character. Those with a wildcard character later in the host name sort before those with a wildcard character earlier in the host name.
- Accounts with a non-empty user name sort before accounts with an empty user name.
The following table shows a list of example account as sorted by these criteria:
+---------+-------------+ | User | Host | +---------+-------------+ | joffrey | 192.168.0.3 | | | 192.168.0.% | | joffrey | 192.168.% | | | 192.168.% | +---------+-------------+
Once connected, you only have the privileges granted to the account that matched, not all accounts that could have matched. For example, consider the following commands:
CREATE USER 'joffrey'@'192.168.0.3'; CREATE USER 'joffrey'@'%'; GRANT SELECT ON test.t1 to 'joffrey'@'192.168.0.3'; GRANT SELECT ON test.t2 to 'joffrey'@'%';
If you connect as joffrey from 192.168.0.3
, you will have the SELECT
privilege on the table test.t1
, but not on the table test.t2
. If you connect as joffrey from any other IP address, you will have the SELECT
privilege on the table test.t2
, but not
on the table test.t1
.
MariaDB starting with 5.5.31
Beginning with MariaDB 5.5.31, usernames can be up to 80 characters long. From MariaDB 10.0 the system tables are all by default this length. However, in order to enable this feature in MariaDB 5.5, the following schema changes must be made:
ALTER TABLE mysql.user MODIFY User CHAR(80) BINARY NOT NULL DEFAULT ''; ALTER TABLE mysql.db MODIFY User CHAR(80) BINARY NOT NULL DEFAULT ''; ALTER TABLE mysql.tables_priv MODIFY User CHAR(80) BINARY NOT NULL DEFAULT ''; ALTER TABLE mysql.columns_priv MODIFY User CHAR(80) BINARY NOT NULL DEFAULT ''; ALTER TABLE mysql.procs_priv MODIFY User CHAR(80) BINARY NOT NULL DEFAULT ''; ALTER TABLE mysql.proc MODIFY definer CHAR(141) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.event MODIFY definer CHAR(141) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.proxies_priv MODIFY User CHAR(80) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.proxies_priv MODIFY Proxied_user CHAR(80) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.proxies_priv MODIFY Grantor CHAR(141) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.servers MODIFY Username CHAR(80) NOT NULL DEFAULT ''; ALTER TABLE mysql.procs_priv MODIFY Grantor CHAR(141) COLLATE utf8_bin NOT NULL DEFAULT ''; ALTER TABLE mysql.tables_priv MODIFY Grantor CHAR(141) COLLATE utf8_bin NOT NULL DEFAULT ''; FLUSH PRIVILEGES;
Examples
CREATE USER foo2@test IDENTIFIED BY 'password';
tls options, from MariaDB 10.2.0:
CREATE USER 'foo4'@'test' REQUIRE ISSUER 'foo_issuer' SUBJECT 'foo_subject' CIPHER 'text'
Resource limits, from MariaDB 10.2.0
CREATE USER foo WITH MAX_QUERIES_PER_HOUR 10 MAX_UPDATES_PER_HOUR 20 MAX_CONNECTIONS_PER_HOUR 30 MAX_USER_CONNECTIONS 40;
OR REPLACE and IF NOT EXISTS:
CREATE USER foo2@test IDENTIFIED BY 'password'; ERROR 1396 (HY000): Operation CREATE USER failed for 'foo2'@'test' CREATE OR REPLACE USER foo2@test IDENTIFIED BY 'password'; Query OK, 0 rows affected (0.00 sec) CREATE USER IF NOT EXISTS foo2@test IDENTIFIED BY 'password'; Query OK, 0 rows affected, 1 warning (0.00 sec) SHOW WARNINGS; +-------+------+----------------------------------------------------+ | Level | Code | Message | +-------+------+----------------------------------------------------+ | Note | 1973 | Can't create user 'foo2'@'test'; it already exists | +-------+------+----------------------------------------------------+ 1 row in set (0.00 sec