SurrealDB has been built from the ground up to be the ultimate database for developers who want to build tomorrow's applications. On this page you can find information regarding many of the features which are built into SurrealDB, alongside features and ideas which are planned for future releases of SurrealDB.
Architecture
Single-node (in-memory)
Complete
SurrealDB can be configured to run in a single-node memory-only runtime, enabling
multi-reader, single-writer querying and data analysis. This is suitable for testing and
for data which fits inside the memory capacity of a single machine.
When wanting to use SurrealDB from within the browser, the WebAssembly library has support for
connecting to a remote database over HTTP or WebSockets, or running with data persistence on
top of IndexedDB in the browser.
When wanting persistent data storage on a single-node, on-disk storage can be
used to enable larger data storage capabilities. RocksDB
is optimised for high performance and fast storage on SSDs.
As an alternative to RocksDB, when running on a single machine, SpeeDB
can be used for greater resource efficiency, and improved storage performance on disk.
Single-node (SurrealKV)
Planned 1.X
Our own native storage engine, written in Rust will support multiple concurrent writers and readers.
SurrealKV will enable versioned queries over time, enabling immutable data querying, data change auditing,
historic aggregate query analysis, and versioned queries on the graph.
Distributed (SurrealKV)
Future
For highly-available setups, SurrealKV will support the ability to horizontally scale to multiple terabytes
of data. As a distributed cluster SurrealKV will enable versioned queries over time, enabling immutable data
querying, data change auditing, historic aggregate query analysis, and versioned queries on the graph.
For highly-available and highly-scalable setups, SurrealDB can be run on top of a
FoundationDB cluster, with the
ability to horizontally scale to multiple terabytes of data.
For highly-available and highly-scalable setups, SurrealDB can be run on top of a
TiKV cluster, with the
ability to horizontally scale to multiple terabytes of data.
Platform
Multi-tenancy data separation
Complete
Split data into namespaces and databases. There is no limit to the number of databases under each
namespace, with the ability to switch between databases inside queries and transactions.
Schemafull or schemaless
Complete
Store unstructured nested data with any columns, or limit data stored to only specific columns or
fields. Get started quickly without having to define every column, and move to schemafull when
your data model is defined.
Multi-table, multi-row transactions
Complete
As a fully ACID compliant database, SurrealDB allows you to run transactions across
multiple-rows, and across multiple different tables. There is no limit to the length of time a
transaction can run.
Versioned temporal tables
Future
Versioned temporal tables enable the option to 'go back in time' when querying your data. See how
data looked before changes were made, or restore to a particular point-in-time.
Table fields
Complete
When a table is defined as schemafull, only data allowed by defined fields will be stored. Table
fields can be nested, and can be limited to a certain data type. VALUE clauses can
be used to ensure a default value is always specified if no data is entered.
Table events
Complete
Table events can be triggered after any change or modification to the data in a record. Each
trigger is able to see the $before and $after value of the record,
enabling advanced custom logic with each trigger.
Table indexes
Complete
Table indexes improve data querying performance, and also allow for UNIQUE values in
a table. Table indexes can be specified for a column, multiple columns, and have support for all
nested fields including arrays and objects.
-- Specify a field on the user tableDEFINEFIELD email ONTABLE user TYPE string ASSERTstring::is::email($value);-- Add a unique index on the email field to prevent duplicate valuesDEFINEINDEX email ONTABLE user COLUMNS email UNIQUE;-- Create a new event whenever a user changes their email addressDEFINEEVENT email ONTABLE user WHEN$before.email!=$after.emailTHEN(CREATE event SET user =$this, time =time::now(), value =$after.email, action ='email_changed');
Table constraints
Complete
Each defined table field supports an ASSERT clause which acts as a constraint on the
data. This clause enables advanced SurrealQL statements which can ensure that the
$value entered is within certain parameters. Each clause is also able to see the
$before and $after value of the record, enabling advanced custom logic
with each trigger.
-- Specify a field on the user tableDEFINEFIELD countrycode ON user TYPE string
-- Ensure country code is ISO-3166ASSERT$value=/[A-Z]{3}/-- Set a default value if emptyVALUE$valueOR$beforeOR'GBR';
Full text indexing and filtering
Complete
The ability to define full-text indexes, with functionality to search through the full-text index
on a table. Searches support field queries, configurable text analyzers, relevance matching, highlighting with offsets extraction.
-- Define a text analyzerDEFINEANALYZER en TOKENIZERS camel,class FILTERS snowball(English);-- Define a search index for a field on the book tableDEFINEINDEX search_title ON book COLUMNS title SEARCHANALYZER en BM25HIGHLIGHTS;-- Select all books who match given keywordsSELECTsearch::score(1)AS score,search::highlight('<b>','</b>',1)AS title
FROM book WHERE title @1@'rust web'ORDER BY score DESC;
Vector embedding indexing
Beta
The ability to define full-text indexes, with functionality to search through the full-text index
on a table. Searches support field queries, configurable text analyzers, relevance matching, highlighting with offsets extraction.
-- Add vector embedding data to record contentCREATEarticle:1SET embedding =[1,2,3,4];CREATEarticle:2SET embedding =[4,5,6,7];CREATEarticle:3SET embedding =[8,9,10,11];-- Define a vector embedding index for a field on the article tableDEFINEINDEX mt_obj ON vec FIELDS embedding MTREEDIMENSION4DISTEUCLIDEAN;
Pre-defined aggregate analytics views
Complete
Aggregate views let you pre-compute analytics queries as data is written to SurrealDB. Similarly
to an index, a table view lets you select, aggregate, group, and order data, with support for
moving averages, time-based windowing, and attribute-based counting. Pre-defined aggregate views
are efficient and performant, with only a single record modification being made for every write.
-- Drop all writes to the reading table. We don't need every reading.DEFINETABLE reading DROP;-- Define a table as a view which aggregates data from the reading tableDEFINETABLE temperatures_by_month ASSELECTcount()AS total,time::month(recorded_at)AS month,math::mean(temperature)AS average_temp
FROM reading
GROUP BY city
;-- Add a new temperature reading with some basic attributesCREATE reading SET
temperature =27.4,
recorded_at =time::now(),
city ='London',
location =(-0.118092,51.509865);
Live queries and record changes
Complete
Live SQL queries allow for advanced filtering of the changes to specific documents, documents
which match a particular filter, or all documents in a specific table. Live SQL queries can
send the fully-updated document, or only the document changesets, by using the efficient
DIFF-MATCH-PATCH algorithm for highly-performant web-based data syncing.
-- Subscribe to all matching document changesLIVESELECT*FROM document
WHERE
account =$auth.accountOR public =true;-- Subscribe to all changes to a single recordLIVESELECT*FROMpost:c569rth77ad48tc6s3ig;-- Stop receiving change notificationsKILL"1986cc4e-340a-467d-9290-de81583267a2";
Global parameters
Complete
Global parameters can be used to store values across the database, which are then accessible to
all queries.
-- Define a global parameter which will be accessible to all queries.DEFINE PARAM $STRIPEVALUE"https://api.stripe.com/payments/new";-- Use the defined global parameter in all queries on the database.DEFINEEVENT payment ONTABLE order WHEN$event='CREATE'THENhttp::post($STRIPE,$value);
Custom functions
Complete
Custom functions allow for complicated or repeated user-defined code, to be run seamlessly within
any query across the database. Custom functions support typed arguments, and multiple nested
queries with custom logic.
-- Define a global function which can be used in any queryDEFINEFUNCTIONfn::get_person($first: string,$last: string,$birthday: string){LET$person=SELECT*FROM person WHERE[first, last, birthday]=[$first,$last,$birthday];RETURNIF$person[0].id THEN$person[0]ELSECREATE person SET first =$first, last =$last, birthday =$birthdayEND;};-- Call the global custom function, receiving the returned resultLET$person=fn::get_person('Tobie','Morgan Hitchcock','2022-09-21');
Data model
Basic types
Complete
Support for booleans, strings, and numerics is built in by default. Numeric values default to
decimal based numbers, but can be stored as int or float
values for 64 bit integer or 64 bit floating point precision.
Empty values
Complete
Values can be NONE, or NULL. A field which is NONE does
not have any data stored, while NULL values are values which are entered but empty.
Arrays
Complete
SurrealDB has native support for arrays, with no limit to the depth of nesting within arrays.
Arrays can contain any other data value.
Objects
Complete
Embedded object types are an integral feature of SurrealDB, with no limit to the depth of nesting
for objects.
Durations
Complete
Any duration from nanoseconds to weeks can be stored and used for calculations. Durations can be
added to datetimes, and to other durations.
Datetimes
Complete
Support for dates and datetimes in ISO-8601 format are supported. All dates are converted and
stored in the UTC timezone.
Geometries
Complete
SurrealDB makes working with GeoJSON easy, with support for Point,
Line, Polygon, MultiPoint, MultiLine,
MultiPolygon, and Collection values. SurrealQL automatically detects
GeoJSON objects converting them into a single data type.
UPDATEcity:londonSET
centre =(-0.118092,51.509865),
boundary ={type:"Polygon",coordinates:[[[-0.38314819,51.37692386],[0.1785278,51.37692386],[0.1785278,51.61460570],[-0.38314819,51.61460570],[-0.38314819,51.37692386]]]};
Futures
Complete
Values which should be computed only when outputting data, can be stored as futures. These values
are stored in SurrealDB as SurrealQL code, and are calculated only when output as part of a
SELECT clause.
Casting
Complete
In SurrealDB, all data values are strongly typed. Values can be cast and converted to other types
using specific casting operators. These include bool, int,
float, string, number, decimal,
datetime, and duration casts.
UPDATE product SET
name ="SurrealDB",
launch_at ="2021-11-01",
countdown =<future>{ launch_at -time::now()};
UPDATE person SET
waist =<int>"34",
height =<float>201,
score =<decimal>0.3+0.3+0.3+0.1;
Strict typing
Complete
With a strict typing system, SurrealQL ensures that document structures are easier to understand, and any data
conforms to the defined record schema. Advanced types for arrays and record links, ensure that related data
works in the same way as basic types.
// Ensure that a record field must be a number.DEFINEFIELD age ON person TYPE number;// Allow the field to be optional or a number.DEFINEFIELD age ON person TYPE option<number>;// Ensure that a record link is specified and of a specific type.DEFINEFIELD author ON book TYPE record<person>;// Allow a field to be optional and of a selection of types.DEFINEFIELD pet ON user TYPE option<record<cat | dog>>;// Allow a field to be one of multiple types.DEFINEFIELD rating ON film TYPE float | decimal;// Ensure that a field is an a array of unique values of a certain length.DEFINEFIELD tags ON person TYPE set<string,5>;
Manipulation and querying of data in SurrealQL is done using the SELECT,
CREATE, UPDATE, and DELETE methods. These enable
selecting or modifying individual records, or whole tables. Each statement supports multiple
different tables or record types at once.
-- Create a new article record with a specific idCREATEarticle:surrealSET name ="SurrealDB: The next generation database";-- Update the article record, and add a new fieldUPDATEarticle:surrealSET time.created =time::now();-- Select all matching articlesSELECT*FROM article, post WHERE name CONTAINS'SurrealDB';-- Delete the articleDELETEarticle:surreal;
RELATE statements
Complete
The RELATE statement adds graph edges between records in SurrealDB. It follows the
convention of vertex -> edge -> vertex or noun -> verb -> noun,
enabling the addition of metadata to the edge record.
INSERT statements
Complete
The INSERT statement resembles the traditional SQL statement, enabling users to get
started quickly. It supports the creation of records using a VALUES clause, or by
specifying the record data as an object.
-- Add a graph edge between user:tobie and article:surrealRELATEuser:tobie->write->article:surrealSET time.written =time::now();-- Add a graph edge between specific users and developersLET$from=(SELECT users FROMcompany:surrealdb);LET$devs=(SELECT*FROM user WHERE tags CONTAINS'developer');RELATE$from->like->$devsUNIQUESET time.connected =time::now();
INSERT INTO company {name:'SurrealDB',founded:"2021-09-10",founders:[person:tobie,person:jaime],tags:['big data','database']};INSERT IGNORE INTO company (name, founded)VALUES('SurrealDB','2021-09-10')ON DUPLICATE KEY UPDATE tags +='developer tools';
FOR statements
Complete
FOR statements enable simplified iteration over data, or for advanced logic when dealing with nested arrays or recursive functions, within code blocks or custom functions.
THROW statements
Complete
The THROW statement statement can be used to return custom error types, which allow for building advanced programming and business logic right within the database and authentication engine.
FOR$personIN(SELECTVALUE id FROM person){CREATE gift CONTENT{recipient:$person,type:"ticket",date:time::now(),event:"SurrealDB World",};};
FOR$userIN$input{IF$user.age<18{THROW"Only adults should be inserted";}IF$user.country!='USA'{THROW$user.country+" is not a valid country";}};
Parameters
Complete
Parameters can be used to store values or result sets, and can be used as stored parameters in
client code.
Subqueries
Complete
Recursive subqueries are useful for advanced querying or modification of values, whilst
simplifying the overall query.
Nested field queries
Complete
In SurrealQL any nested array or object value can be accessed and manipulated using traditional
dot notation ., or array notation [].
Maths operators
Complete
Maths operators can be used to perform complex mathematical calculations directly in SurrealQL.
Geospatial operators
Complete
Geospatial operators enable geospatial containment and intersection operators on geospatial
types.
Set operators
Complete
Advanced set operators can be used to detect whether one or multiple values are included within
an array. Fuzzy matching and regex matching can also be used for advanced filtering.
-- Use mathematical operators to calculate valueSELECT*FROM temperature WHERE(celsius *1.8)+32>86.0;-- Use geospatial operator to detect polygon containmentSELECT*FROM restaurant WHERE location INSIDE{type:"Polygon",coordinates:[[[-0.38314819,51.37692386],[0.1785278,51.37692386],[0.1785278,51.61460570],[-0.38314819,51.61460570],[-0.38314819,51.37692386]]]};-- Select all people whose tags contain "tag1" OR "tag2"SELECT*FROM person WHERE tags CONTAINSANY["tag1","tag2"];-- Select all people who have any email address ending in 'gmail.com'SELECT*FROM person WHERE emails.*.value ?=/gmail.com$/;
Maths constants
Complete
SurrealQL has a number of built-in constants for advanced mathematical expressions and
calculations, including math::E, math::FRAC_1_PI,
math::FRAC_1_SQRT_2, math::FRAC_2_PI,
math::FRAC_2_SQRT_PI, math::FRAC_PI_2, math::FRAC_PI_3,
math::FRAC_PI_4, math::FRAC_PI_6, math::FRAC_PI_8,
math::LN_10, math::LN_2, math::LOG10_2,
math::LOG10_E, math::LOG2_10, math::LOG2_E,
math::PI, math::SQRT_2, and math::TAU.
Expressions
Complete
SurrealQL supports fetching data using dot notation ., array notation
[], and graph semantics ->. SurrealQL enables records to link to other
records and traverses all embedded links or graph connections as desired. When traversing and
fetching remote records SurrealQL enables advanced filtering using traditional
WHERE clauses.
-- Select a nested array, and filter based on an attributeSELECT emails[WHERE active =true]FROM person;-- Select all 1st, 2nd, and 3rd level people who this specific person record knows, or likes, as separate outputsSELECT->knows->(? AS f1)->knows->(? AS f2)->(knows, likes AS e3 WHERE influencer =true)->(? AS f3)FROMperson:tobie;-- Select all person records (and their recipients), who have sent more than 5 emailsSELECT*,->sent->email->to->person FROM person WHEREcount(->sent->email)>5;-- Select other products purchased by people who purchased this laptopSELECT<-purchased<-person->purchased->product FROMproduct:laptop;-- Select products purchased by people in the last 3 weeks who have purchased the same products that we purchasedSELECT->purchased->product<-purchased<-person->(purchased WHERE created_at >time::now()-3w)->product FROMperson:tobie;
Complex Record IDs
Complete
SurrealDB supports the ability to define record IDs using arrays and objects. These values sort
correctly, and can be used to store values or recordings in a timeseries context.
// Set a new parameterLET$now=time::now();// Create a record with a complex ID using an arrayCREATEtemperature:['London',$now]SET
location ='London',
date =$now,
temperature =23.7;// Create a record with a complex ID using an objectCREATEtemperature:{location:'London',date:$now}SET
location ='London',
date =$now,
temperature =23.7;
Record ID ranges
Complete
SurrealDB supports the ability to query a range of records, using the record ID. The record ID
ranges, retrieve records using the natural sorting order of the record IDs. These range queries
can be used to query a range of records in a timeseries context.
-- Select all person records with IDs between the given rangeSELECT*FROMperson:1..1000;-- Select all records for a particular location, inclusiveSELECT*FROMtemperature:['London',NONE]..=['London',time::now()];-- Select all temperature records with IDs less than a maximum valueSELECT*FROMtemperature:..['London','2022-08-29T08:09:31'];-- Select all temperature records with IDs greater than a minimum valueSELECT*FROMtemperature:['London','2022-08-29T08:03:39']..;-- Select all temperature records with IDs between the specified rangeSELECT*FROMtemperature:['London','2022-08-29T08:03:39']..['London','2022-08-29T08:09:31'];
Learning fields
Future
Learning fields bring machine-learning based decision-making directly into SurrealDB. When a
value is not entered directly, then the field can be automatically calculated based on the
machine learning analysis of other specified columns or fields.
-- Add a field which is based on other fields when a value is not specifiedDEFINEFIELD won ON opportunity TYPE boolean
LEARN FROM
confidence,
person.tags,
person->sent->email.body
;-- We are specifying the 'won' field, so it will use this to learnCREATE opportunity SET won =true, confidence =7, person =person:valeria;-- We are specifying the 'won' field, so it will use this to learnCREATE opportunity SET won =false, confidence =3, person =person:jonathan;-- Here the 'won' field is calculated with machine learningCREATE opportunity SET confidence =6, person =person:steven;
Functions
Array functions
Complete
Functions for manipulation, joining, and diffing of arrays are built into SurrealDB as standard.
Http functions
Complete
HTTP functions can be used for remote trigger events and webhook functionality.
Math functions
Complete
Math functions can be used for complex statistical analysis of numbers and sets of numbers.
Parsing functions
Complete
Parsing functions can be used for parsing and extracting individual parts or urls, emails, and domains.
Rand functions
Complete
Random generation functions can be used to generate random values, numbers, strings, UUIDs, and datetimes.
Search functions
Complete
Functions related to the full-text search capabilities, such as calculating relevance scores or highlighting content.
String functions
Complete
Functions for string manipulation enable modification and processing of strings.
Type functions
Complete
Type checking functions can be used to check the type of a value, which is useful in custom function definitions.
Vector functions
Complete
A collection of essential vector operations that provide foundational functionality for numerical computation,
machine learning, and data analysis.
Geo functions
Complete
Geospatial functions can be used for converting between geohash values, and for calculating the
distance, bearing, and area of GeoJSON data types.
Time functions
Complete
Time functions can be used to manipulate dates and times - with support for rounding, and
extracting specific parts of datetimes.
SurrealDB supports general count functionality for counting total values, or for aggregate
grouping. It's also possible to count only those expressions which result in a truthy value.
Validation functions
Complete
Validation functions can be used to determine that field values match a certain pattern
including
hexadecimal, alphanumeric, ascii, numeric, or email addresses.
SELECTcount(age >18)FROM user;
SELECT email,string::is::email(email)AS valid FROM user;
Embedded JavaScript functions
Complete
Javascript functions can be used for more complex functions and triggers. Each Javascript
function iteration runs with its own context isolation - with the current record data passed in
as the execution context or this value.
CREATE film SET
ratings =[{rating:6,user:user:bt8e39uh1ouhfm8ko8s0},{rating:8,user:user:bsilfhu88j04rgs0ga70},],
featured =function(){
return this.ratings.filter(r =>{
return r.rating >=7;}).map(r =>{
return {...r,rating: r.rating *10};});};
Permissions
Root access
Complete
Root access enables full data access for all data in SurrealDB. Root access can be limited to
specific IPv4 or IPv6 IP addresses.
Namespace access
Complete
Namespace access enables full data access for all databases under a specific namespace. This
access level is controlled using custom defined usernames and passwords.
Database access
Complete
Database access enables full data access to a specific database under a specific namespace. This
access level is controlled using custom defined usernames and passwords.
Scope access
Complete
Scope access is the powerful functionality which enables SurrealDB to operate as a web database.
Flexible authentication and access rules enable fine-grained access to tables and fields with
the highest security, whilst ensuring that performance is affected as little as possible.
3rd party authentication
Complete
If authentication with a 3rd party OAuth provider is desired, specific tokens can be used for
authentication with SurrealDB. ES256, ES384, ES512,
HS256, HS384, HS512, PS256,
PS384, PS512, RS256, RS384, and
RS512 algorithms are supported.
-- Enable scope authentication directly in SurrealDBDEFINESCOPE account SESSION24hSIGNUP(CREATE user SET email =$email, pass =crypto::argon2::generate($pass))SIGNIN(SELECT*FROM user WHERE email =$emailANDcrypto::argon2::compare(pass,$pass));
// Signin and retrieve a JSON Web Tokenlet jwt =fetch('https://api.surrealdb.com/signup',{method:'POST',headers:{'Accept':'application/json','NS':'google',// Specify the namespace'DB':'gmail',// Specify the database},body:JSON.stringify({'NS':'google','DB':'gmail','SC':'account',email:'tobie@surrealdb.com',pass:'a85b19*1@jnta0$b&!'}),});
Table permissions
Complete
Fine-grained table permissions can be used to prevent users from accessing data which they
shouldn't
see. Independent permissions for selecting, creating, updating, and deleting data are supported,
ensuring fine-grained control over all data in SurrealDB.
-- Specify access permissions for the 'post' tableDEFINETABLE post SCHEMALESSPERMISSIONSFOR select
-- Published posts can be selectedWHERE published =true-- A user can select all their own postsOR user =$auth.idFOR create, update
-- A user can create or update their own postsWHERE user =$auth.idFOR delete
-- A user can delete their own postsWHERE user =$auth.id-- Or an admin can delete any postsOR$auth.admin=true;
Connectivity
REST API
Complete
All tables and data can be queried using a traditional Key-Value REST API. In addition, SurrealQL
statements can be submitted to the REST API for custom query logic.
## Execute a SurrealQL querylocalhost % curl -X POST https://api.surrealdb.com/sql## Interact with a tablelocalhost % curl -X GET https://api.surrealdb.com/key/userlocalhost % curl -X POST https://api.surrealdb.com/key/userlocalhost % curl -X DELETE https://api.surrealdb.com/key/user## Interact with a recordlocalhost % curl -X GET https://api.surrealdb.com/key/user/tobielocalhost % curl -X PUT https://api.surrealdb.com/key/user/tobielocalhost % curl -X POST https://api.surrealdb.com/key/user/tobielocalhost % curl -X PATCH https://api.surrealdb.com/key/user/tobielocalhost % curl -X DELETE https://api.surrealdb.com/key/user/tobie
SurrealQL over WebSocket
Complete
SurrealQL querying and data modification is supported over WebSockets for bi-directional
communication, and real-time updates.
JSON-RPC over WebSocket
Complete
Querying and data modification is available using JSON-RPC over WebSockets, enabling easier
implementation of 3rd party libraries.
GraphQL querying
Future
Support for querying all data using GraphQL, with embedded and remote record fetching.
GraphQL mutations
Future
Support for modifying and updating any data using GraphQL, depending on permissions.
GraphQL subscriptions
Future
Support for subscribing to real-time data modification events, depending on permissions.
Tooling
Command-line tool
Complete
The command-line tool can be used to export data as SurrealQL, import data as SurrealQL, and
start a SurrealDB instance or cluster.
user@localhost % surreal
.d8888b. 888 8888888b. 888888b.
d88P Y88b 888 888 'Y88b 888 '88b
Y88b. 888 888 888 888 .88P
'Y888b. 888 888 888d888 888d888 .d88b. 8888b. 888 888 888 8888888K.
'Y88b. 888 888 888P' 888P' d8P Y8b '88b 888 888 888 888 'Y88b
'888 888 888 888 888 88888888 .d888888 888 888 888 888 888
Y88b d88P Y88b 888 888 888 Y8b. 888 888 888 888 .d88P 888 d88P
'Y8888P' 'Y88888 888 888 'Y8888 'Y888888 888 8888888P' 8888888P'
To get started using SurrealDB, and for guides on connecting to and building applications
on top of SurrealDB, check out the SurrealDB documentation (https://surrealdb.com/docs).
If you have questions or ideas, join the SurrealDB community (https://surrealdb.com/community).
If you find a bug, submit an issue on GitHub (https://github.com/surrealdb/surrealdb/issues).
We would love it if you could star the repository (https://github.com/surrealdb/surrealdb).
----------
Usage: surreal <COMMAND>
Commands:
start Start the database server
backup Backup data to or from an existing database
import Import a SurrealQL script into an existing database
export Export an existing database as a SurrealQL script
version Output the command-line tool and remote server version information
upgrade Upgrade to the latest stable version
sql Start an SQL REPL in your terminal with pipe support
is-ready Check if the SurrealDB server is ready to accept connections [aliases: isready]
validate Validate SurrealQL query files
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
SQL export
Complete
Export all data as SurrealQL from a SurrealDB database for backup purposes. This includes
authentication scopes, tables, fields, events, indexes, and data.
SQL import
Complete
Import SurrealQL into a SurrealDB database in order to restore from a backup. This includes
authentication scopes, tables, fields, events, indexes, and data.
Incremental backup
Future
Export all data from SurrealDB as raw binary data. This will also support incremental binary
backups for efficient backing up of SurrealDB clusters.
Docker container
Complete
In addition to binary releases, SurrealDB is packaged as a Docker container for easy setup and
configuration. All configuration is done with the command-line options. The Docker container can
be used to start a SurrealDB instance or cluster, or to import and export data.
docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start
IDE language support
Future
SurrealDB aims to include official language highlighting packages for Atom, Sublime Text, Visual
Studio Code, and Vim.
Language Server Protocol
Future
SurrealDB will support the Language Server Protocol which will help with code and query
completion, and error highlighting for SurrealQL.
User interface
Planned 1.X
An easy-to-use interface with support for table-based views, SurrealQL querying, embedded object
editing, and graph visualisation. The interface will be embedded within every SurrealDB
executable.
Web app
Planned 1.X
The interface will be available as a web app, installed on every instance of SurrealDB, and can
be used for connecting to SurrealDB Cloud, or a local or enterprise cluster.
macOS
Planned 1.X
The interface will be available as a desktop application for macOS powered by Tauri. This can be
used for connecting to SurrealDB Cloud, or a local or enterprise cluster.
Windows
Planned 1.X
The interface will be available as a desktop application for Windows powered by Tauri. This can
be used for connecting to SurrealDB Cloud, or a local or enterprise cluster.
SDKs
Rust
Available
An async-friendly SDK for Rust with bi-directional, binary communication over WebSockets or HTTP.
Golang
Available
An SDK for Golang with bi-directional communication over WebSockets or HTTP.
Python
Available
An SDK for Python with bi-directional, binary communication over WebSockets or HTTP.
Javascript
Available
An SDK for Javascript with bi-directional, binary communication over WebSockets or HTTP.
Node.js
Available
An SDK for Javascript with bi-directional, binary communication over WebSockets or HTTP.
Deno
Available
An SDK for Deno with bi-directional, binary communication over WebSockets or HTTP.
WebAssembly
Available
An SDK for Javascript with bi-directional, binary communication over WebSockets or HTTP.
Java
Available
An SDK for Java with bi-directional communication over WebSockets or HTTP.
.NET
Beta
An SDK for .NET with bi-directional communication over WebSockets or HTTP.
C
Future
An SDK for C with bi-directional, binary communication over WebSockets or HTTP.
PHP
Future
An SDK for PHP with bi-directional, binary communication over WebSockets or HTTP.
Swift
Future
An SDK for Swift with bi-directional communication over WebSockets.
Dart
Future
An SDK for Dart with bi-directional communication over WebSockets.
R
Future
An SDK for R with bi-directional communication over WebSockets.
Ruby
Future
An SDK for Dart with bi-directional communication over WebSockets.
Erlang
Future
An SDK for Erlang with bi-directional communication over WebSockets.
Ember.js
Future
A real-time, live-updating SDK for Ember.js, with authentication, model definition, embedded
types, and remote fetching.
React.js
Future
A real-time, live-updating SDK for React.js, with authentication, model definition, embedded
types, and remote fetching.
Vue.js
Future
A real-time, live-updating SDK for Vue.js, with authentication, model definition, embedded
types, and remote fetching.
Next.js
Future
A real-time, live-updating SDK for Next.js, with authentication, model definition, embedded
types, and remote fetching.
Angular
Future
A real-time, live-updating SDK for Angular, with authentication, model definition, embedded
types, and remote fetching.
Flutter
Future
An SDK for Flutter with bi-directional communication over WebSockets.