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 or namespace user before you can use the
DEFINE DATABASE
statement. - You must select your namespace before you can use the
DEFINE DATABASE
statement.
Statement syntax
SurrealQL SyntaxDEFINE 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;