Product docs and API reference are now on Akamai TechDocs.
Search product docs.
Search for “” in product docs.
Search API reference.
Search for “” in API reference.
Search Results
 results matching 
 results
No Results
Filters
Getting Started with SurrealDB
Traducciones al EspañolEstamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
SurrealDB offers a new approach to relational databases. It brings features like all-in-one handling of database, API, and security layers, real-time queries, and multi-model data storage — while still retaining a familiar SQL-like language. In this tutorial, learn more about SurrealDB’s offerings and how you can get started with this new database solution.
Why SurrealDB?
SurrealDB serves as a complete database solution for serverless applications and for use cases that require a high degree of scalability. For serverless applications, SurrealDB’s all-in-one schema handling lets you design APIs right alongside your databases. Web clients can then readily access those APIs, letting SurrealDB support Jamstack and other serverless web applications. SurrealDB has also been designed with scalability in mind. It is built on Rust, giving it high performance. SurrealDB’s architecture and database handling places distributed systems at the forefront, making it ready for horizontal scaling.
Though not complete, here is a list of some of the features that SurrealDB offers:
Handling of database, API, and security layers all in one place. SurrealDB does not require separate server-side applications to schematize and expose a client-facing API. You can do that from right within SurrealDB, providing support to serverless applications like those using the Jamstack architecture. Moreover, SurrealDB includes a robust access-control system. This further reduces the need to implement separate server-side tools and development.
Implements a multi-model approach. SurrealDB retains the familiarity of SQL queries. At the same time, SurrealDB’s queries can leverage inter-document relations and support multiple models. You can store data however you like, and retrieve it however you need. SurrealDB does not limit your models on either end, and does not require you to finalize your models in advance.
Supports real-time queries. SurrealDB can keep clients up-to-date with live push updates for changes in data. Clients can subscribe to queries, and SurrealDB leverages advanced filtering options to fine-tune what kinds of changes clients get live push updates for.
Uses a highly-scalable architecture. SurrealDB is designed to support running databases on distributed clusters, making it easily scalable. SurrealDB’s database operations are specially built to handle distributed operations without table or row locks.
Before You Begin
If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.
Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
sudo
. If you’re not familiar with the sudo
command, see the Users and Groups
guide.How to Install SurrealDB
To start with SurrealDB, install a standalone instance on your system. SurrealDB provides an installation script that makes the process straightforward. Follow along with the steps below to install the SurrealDB server, then keep reading to learn how to use it.
Install Tar to extract
tar
packages as this is required for part of the installation script’s process:sudo apt install tar
sudo dnf install tar
While optional, also install the
jq
tool to more legibly print cURL outputs later on in the tutorial:sudo apt install jq
sudo dnf install jq
Run the installation script. cURL accesses the script via its URL, the script’s contents are then piped to your shell for execution.
curl -sSf https://install.surrealdb.com | sh
.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' Fetching the latest database version... Fetching the host system architecture... [...] SurrealDB successfully installed in: /home/example-user/.surrealdb/surreal [...]
By default, the SurrealDB binary file is stored at
~/.surrealdb/surreal
. For easier access to thesurreal
command, move the binary to a directory on your shell path. Make sure to changeexample-user
to your actual username.sudo mv /home/example-user/.surrealdb/surreal /usr/local/bin
Leave the
~/.surrealdb/
directory in place. The next section showcases SurrealDB’s option to persist a database to a file, and the directory provides a convenient location.
SurrealDB: The Basics
Running the SurrealDB Server
To begin using SurrealDB, you must first start the database server. You can do this from the surreal
binary’s start
command. However, before starting the server, you need to decide how to store data: in memory or in a file.
Below are two versions of a basic command for starting up the SurrealDB server, one for each of the kinds of storage options:
Memory: To run SurrealDB using in-memory database storage, end the
start
command withmemory
. This option is exceptional for testing out SurrealDB, allowing you to get a feel for queries without committing to persistent data.surreal start --user root --pass exampleRootPass memory
File: To run SurrealDB using a database file for storage, end the
start
command withfile://<path>
, where<path>
points to a.db
file. The example here points to aexampleDatabase.db
file (which does not yet exist) stored in the current user’s (example-user
) home directory. This uses the absolute path, so it begins with a/
. Make sure to changeexample-user
to your actual username.surreal start --user root --pass exampleRootPass file:///home/example-user/.surrealdb/exampleDatabase.db
[...]
2022-12-31T22:23:24.252627Z INFO surrealdb::net: Starting web server on 0.0.0.0:8000
2022-12-31T22:23:25.262728Z INFO surrealdb::net: Started web server on 0.0.0.0:8000
[...]
Notice that both of the commands have --user
and --pass
options. These define the root user credentials for your server instance, which you can use for queries in later examples.
Before moving ahead with SurrealDB, you likely want to implement stricter security around this user, and to create other users with managed access. If so, check out our tutorial Managing Security and Access Control for SurrealDB .
Running on a Different Port
By default, SurrealDB runs on port 8000
. You can alter the port with the --bind
option. This example runs the SurrealDB server on port 8080
:
surreal start --bind 0.0.0.0:8080 --user root --pass exampleRootPass memory
The --bind
option also lets you alter the address at which the SurrealDB server can be accessed. By default, the address is 0.0.0.0
as above. The server can thus be accessed from any address that accesses the server machine.
The examples in this tutorial only need to access the SurrealDB server over localhost
(127.0.0.1
). It’s good practice to only run the server there for testing purposes:
surreal start --bind 127.0.0.1:8000 --user root --pass exampleRootPass memory
Querying SurrealDB from the CLI
In addition to the server, the surreal
binary includes an sql
command to run SurrealDB’s CLI tool. This provides easy access to the SurrealDB server and is probably the best way to learn SurrealDB queries.
First, open a second terminal for the SurrealDB CLI, as the original is still running the SurrealDB server. The rest of the commands in this tutorial are run from this second terminal.
To start a SurrealDB CLI session, use a command like the one below. This connects to a SurrealDB server started with one of the examples commands above (except for the one that changes the default port).
surreal sql --conn http://localhost:8000 --user root --pass exampleRootPass --ns exampleNs --db exampleDb --pretty
The command specifies a connection to a SurrealDB server running on
localhost
, and connects using theroot
user and the example password from above. Additionally, for this tutorial’s purposes, the connection to the database server immediately initiates aexampleNs
namespace and aexampleDb
database.The example CLI startup here also includes the
--pretty
option. This “pretty prints” responses from the server, making them easier to read and navigate.From there, you can start executing queries on your SurrealDB database. These steps provide some examples that set up a set of tables and records. These do a lot to demonstrate some of SurrealDB’s unique features.
Create a
tags
table to store tags for each blog post and provide a few starting values:INSERT INTO tags [ { id: "first", value: "first" }, { id: "last", value: "last" }, { id: "post", value: "post" }, { id: "test", value: "test" } ];
SurrealDB automatically generates unique IDs, but entering these manually makes the records more intuitive to fetch. For instance, you can fetch the
last
tag above with the following command:SELECT value FROM tags:last;
{ value: 'last' }
SurrealDB IDs consist of the record’s ID,
last
in this case, and the table name, hencetags:last
.Create a set of blog posts in an
article
table. These consist of defined IDs, titles, and body content. Date values are included as well for easily sorting the records later.INSERT INTO article [ { id: "first", date: "2023-01-01T12:01:01Z", title: "First Post", body: "This is the first post." }, { id: "second", date: "2023-02-01T13:02:02Z", title: "Second Post", body: "You are reading the second post." }, { id: "third", date: "2023-03-01T14:03:03Z", title: "Third Post", body: "Here, the contents for the third post." } ];
For those familiar with traditional SQL, the two
INSERT
statements above may seem unusual. SurrealDB supports the traditionalINSERT
syntax, but the syntax in this version condenses the command and is more aligned with “document” database work.Create some relations between the
article
records andtags
records. This provides a nice way to “tag” the posts while also demonstrating how SurrealDB’sRELATE
statement can be used for managing inter-document relations.RELATE article:first->tagged->tags:post; RELATE article:first->tagged->tags:first; RELATE article:first->tagged->tags:test; RELATE article:second->tagged->tags:post; RELATE article:second->tagged->tags:test; RELATE article:third->tagged->tags:post; RELATE article:third->tagged->tags:last; RELATE article:third->tagged->tags:test;
To elaborate, the commands above result in the
first
article being associated with thepost
,first
, andtest
tags. See how to create fresh and useful models from these relations later on.Now take a look at what kinds of records your database has. To start, get all the records from the
article
base table:SELECT id, title, body FROM article;
[ { body: 'This is the first post.', id: article:first, title: 'First Post' }, { body: 'You are reading the second post.', id: article:second, title: 'Second Post' }, { body: 'Here, the contents for the third post.', id: article:third, title: 'Third Post' } ]
Now do the same for
tags
:SELECT id, value FROM tags;
[ { id: tags:first, value: 'first' }, { id: tags:last, value: 'last' }, { id: tags:post, value: 'post' }, { id: tags:test, value: 'test' } ]
One of the key features of this setup is being able to relate article records to tags. This next query essentially uses the
tagged
relations to create a new model, one that should prove much more useful for rendering the blog:SELECT id, title, body, ->tagged->tags.value AS tags, date FROM article ORDER BY date;
[ { body: 'This is the first post.', date: '2023-01-01T12:01:01Z', id: article:first, tags: [ 'post', 'test', 'first' ], title: 'First Post' }, { body: 'You are reading the second post.', date: '2023-02-01T13:02:02Z', id: article:second, tags: [ 'post', 'test' ], title: 'Second Post' }, { body: 'Here, the contents for the third post.', date: '2023-03-01T14:03:03Z', id: article:third, tags: [ 'test', 'last', 'post' ], title: 'Third Post' } ]
Querying SurrealDB Using HTTP
A SurrealDB server instance also maintains a set of HTTP endpoints. With these, a wide range of applications can query the database without needing a separate server-side application.
This section provides some simple demonstrations of SurrealDB’s HTTP endpoints using cURL from the command line. For legibility, the following two examples pipe the cURL output through the jq
tool to pretty print the JSON.
Just like starting up the SurrealDB CLI, it’s best to indicate the namespace and database upfront with HTTP requests. For this, create a file with the header contents for your requests, which makes these easier to input:
cat > surreal_header_file <<EOF Accept: application/json NS: exampleNs DB: exampleDb EOF
Now you can make your first HTTP query to the SurrealDB database. In the command below, notice that in addition to the header file, these HTTP queries need a
--user
option. This option provides your credentials for the database.curl -X GET -H "@surreal_header_file" --user "root:exampleRootPass" http://localhost:8000/key/article/first | jq
[ { "time": "144.031µs", "status": "OK", "result": [ { "body": "This is the first post.", "date": "2023-01-01T12:01:01Z", "id": "article:first", "title": "First Post" } ] } ]
The above is one of the simplest queries available. SurrealDB makes dedicated endpoints available on the
/key
path that let you query by table (article
) and ID (first
).You can make any SurrealDB query through the HTTP API using the
/sql
endpoint.These queries are somewhat easier to manage with the query commands held in a dedicated file. Using the modeled query from the previous section, store that query in a file for access by the cURL command:
cat > surreal_query_file <<EOF SELECT id, title, body, ->tagged->tags.value AS tags, date FROM article ORDER BY date; EOF
Now run the cURL request to fetch the modeled blog post data:
curl -X POST -H "@surreal_header_file" --user "root:exampleRootPass" --data-binary "@surreal_query_file" http://localhost:8000/sql | jq
[ { "time": "828.056µs", "status": "OK", "result": [ { "body": "This is the first post.", "date": "2023-01-01T12:01:01Z", "id": "article:first", "tags": [ "post", "test", "first" ], "title": "First Post" }, { "body": "You are reading the second post.", "date": "2023-02-01T13:02:02Z", "id": "article:second", "tags": [ "post", "test" ], "title": "Second Post" }, { "body": "Here, the contents for the third post.", "date": "2023-03-01T14:03:03Z", "id": "article:third", "tags": [ "test", "last", "post" ], "title": "Third Post" } ] } ]
Conclusion
You now have a foundation in SurrealDB and are ready to start making use of its powerful features as a database. To build on these foundations, you may want to start with the official SurrealDB documentation linked below.
Afterwards, continue reading our other tutorials on SurrealDB. These tackle more advanced and focused use cases. In particular, everyone should follow our Managing Security and Access Control for SurrealDB tutorial next, ensuring a secure and controlled database server.
From there, take your pick based on your interests and needs:
- Deploying a SurrealDB Cluster
- Building an Web Application on Top of SurrealDB
- Modeling Data with SurrealDB’s Inter-document Relations
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on