Version: 2.x(alpha)

`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 record user.

Statement syntax

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

Example usage

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

-- Create the user with an owner role and some example durations
DEFINE USER username ON ROOT PASSWORD '123456' ROLES OWNER DURATION FOR SESSION 15m, FOR TOKEN 5s;

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 with an editor role and some example durations
DEFINE USER username ON NAMESPACE PASSWORD '123456' ROLES EDITOR DURATION FOR SESSION 12h, FOR TOKEN 1m;

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 with a viewer role and some example durations
DEFINE USER username ON DATABASE PASSWORD '123456' ROLES VIEWER DURATION FOR SESSION 5d, FOR TOKEN 2h;

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.)

Duration

The duration clause specifies the duration of the token returned after successful authentication with a password or passhash as well as the duration of the session established both using a password or passhash and the aforementioned token. The difference between these concepts is explained in the expiration documentation.

DEFINE USER statement

Requirements​

Statement syntax​

Example usage​

Using IF NOT EXISTS clause Since 1.3.0​

Roles​

Duration​