DEFINE DATABASE statement

The DEFINE DATABASE statement allows you to instantiate a named database, enabling you to specify security and configuration options.

Requirements

• You must be authenticated as a root owner or editor, or namespace owner or editor before you can use the DEFINE DATABASE statement.
• You must select your namespace before you can use the DEFINE DATABASE statement.

Statement syntax

SurrealQL Syntax
DEFINE DATABASE [ OVERWRITE | IF NOT EXISTS ] @name [ COMMENT @string ]

Example usage

Below shows how you can create a database using the DEFINE DATABASE statement.

-- Specify the namespace for the database
USE NS abcum;

-- Define database
DEFINE DATABASE app_vitalsense;

Using IF NOT EXISTS clause

Available since: v1.3.0

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

It’s particularly useful when you want to safely attempt to define a database 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 database 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 database and overwrite an existing one if it already exists, ensuring that the latest version of the definition is always in use.

-- Create a DATABASE if it does not already exist
DEFINE DATABASE IF NOT EXISTS app_vitalsense;

Using OVERWRITE clause

Available since: v2.0.0

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

-- Create a DATABASE and overwrite if it already exists
DEFINE DATABASE OVERWRITE app_vitalsense;