DEFINE USER statement

Use the DEFINE USER statement to create system users on SurrealDB

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 with owner permissions can create Root, Namespace and Database users.

  • Namespace users with owner permissions can create Namespace and Database users

  • Database users with owner permissions 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.

Statement syntax

DEFINE USER [ OVERWRITE | IF NOT EXISTS ] @name
	ON [ ROOT | NAMESPACE | DATABASE ]
	[ PASSWORD @pass | PASSHASH @hash ]
	[ ROLES @roles ]
	[ DURATION ( FOR TOKEN @duration [ , ] [ FOR SESSION @duration ] | FOR SESSION @duration [ , ] [ FOR TOKEN @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;

Note that even a root-level user can be given a limited role such as VIEWER. This can be useful for automated services that need to monitor each namespace and database, or coworkers high up the org chart that are not particularly tech-savvy.

DEFINE USER birthday_bot ON ROOT PASSWORD "botpassword9!" ROLES VIEWER;
DEFINE USER clumsy_ceo ON ROOT PASSWORD "password" ROLES VIEWER COMMENT "Don't let the CEO have more than VIEWER access";

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

The IF NOT EXISTS clause can be used to define a user only if it does not already exist. You should use the IF NOT EXISTS clause when defining a user in SurrealDB if you want to ensure that the user is only created if it does not already exist. If the user already exists, the DEFINE USER statement will return an error.

It's particularly useful when you want to safely attempt to define a user without manually checking its existence first.

On the other hand, you should not use the IF NOT EXISTS clause when you want to ensure that the user definition is updated regardless of whether it already exists. In such cases, you might prefer using the OVERWRITE clause, which allows you to define a user and overwrite an existing one if it already exists, ensuring that the latest version of the user definition is always in use

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

Using OVERWRITE clause

The OVERWRITE clause can be used to define a user and overwrite an existing one if it already exists. You should use the OVERWRITE clause when you want to modify an existing user definition. If the user already exists, the DEFINE USER statement will overwrite the existing user definition with the new one.

-- Create an USER and overwrite if it already exists
DEFINE USER OVERWRITE example ON ROOT PASSWORD "example" ROLES OWNER;

Roles

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

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.