Version: 1.x

`DEFINE USER` statement

Use the DEFINE USER statement to create system users on SurrealDB

NOTE: While existing logins still function, the DEFINE LOGIN statement has been replaced with DEFINE USER.

Requirements

You must be authenticated with a user that has enough permissions. Only the OWNER built-in role grants permissions to create users.
You must be authenticated with a user that has permissions on the level where you are creating the user:
- Root users can create Root, Namespace and Database users.
- Namespace users can create Namespace and Database users
- Database user can create Database users.
To select the level where you want to create the user, you may need to select a namespace and/or database before you can use the DEFINE USER statement for database or namespace tokens.

NOTE: You cannot use the DEFINE USER statement to create a SCOPE user.

Statement syntax

SurrealQL Syntax
DEFINE USER [ IF NOT EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles [ COMMENT @string ]

Example usage

The following example shows how you can create a ROOT user using the DEFINE USER statement.

-- Create a root user
DEFINE USER username ON ROOT PASSWORD '123456' ROLES OWNER;

The following example shows how you can create a NAMESPACE user using the DEFINE USER statement.

-- Specify the namespace
USE NS abcum;
-- Create the user
DEFINE USER username ON NAMESPACE PASSWORD '123456' ROLES OWNER;

The following example shows how you can create a DATABASE user using the DEFINE USER statement.

-- Specify the namespace and database for the user
USE NS abcum DB app_vitalsense;
-- Create the user
DEFINE USER username ON DATABASE PASSWORD '123456' ROLES OWNER;

Using `IF NOT EXISTS` clause Since 1.3.0

The IF NOT EXISTS clause can be used to define a user only if it does not already exist. If the user already exists, the DEFINE USER statement will return an error.

-- Create a USER if it does not already exist
DEFINE USER IF NOT EXISTS example ON ROOT PASSWORD "example" ROLES OWNER;

Roles

Currently, only the built-in roles OWNER, EDITOR and VIEWER are available.

Role	Description
OWNER	Can view and edit any resource on the user's level or below, including user and token (IAM) resources. It also grants full permissions for child resources that support the `PERMISSIONS` clause (tables, fields, etc.)
EDITOR	Can view and edit any resource on the user's level or below, but not users or token (IAM) resources It also grants full permissions for child resources that support the `PERMISSIONS` clause (tables, fields, etc.)
VIEWER	Grants permissions to view any resource on the user's level or below, but not edit. It also grants view permissions for child resources that support the `PERMISSIONS` clause (tables, fields, etc.)

DEFINE USER statement

Requirements​

Statement syntax​

Example usage​

Using IF NOT EXISTS clause Since 1.3.0​

Roles​