In this guide, we will walk you through installing SurrealDB on your machine, defining your schema, and writing some queries with SurrealQL.
BEFORE YOU STARTMake sure you’ve installed SurrealDB — it should only take a second!
First ensure that your database is set up correctly. To do so, run:
surreal version
To start your database, run the start command specific to your machine.
surreal start memory -A --user root --pass root
surreal.exe start memory -A --user root --pass root
Here’s what each segment of this command does:
surreal start: This initiates the process of starting the SurrealDB database server.-A: Enable all capabilities.--user root --pass root: These flags set the initial username and password to access the database. Here both are set as root. Once the initial credentials are created, they are persisted in the datastore, which means you don’t have to include the command line arguments next time you start SurrealDB. Instead, they should be securely stored in environment variables or some form of secret management system.memory: This argument indicates that the database should be run in memory. Databases run in memory can have quicker data access times because they’re not reading and writing from disk, but the data will be lost when the server is restarted.SurrealQL is the query language for SurrealDB which can be used to query data from your SurrealDB database. While this is not a requirement for getting started, it is helpful to familiarise yourself with some commands.
There are two main ways to use SurrealQL:
For more information, you can visit Surrealist and the SurrealDB CLI documentation.
Once you have your database running, head over to Surrealist. Surrealist offers a simple interface to run SurrealQL queries. You can run queries, view the results, and even save your queries for later use. To start running queries, you can either set up a connection using your database credentials or use a sandbox which uses the default credentials.
For the sake of this guide, we recommend using a sandbox connection. Once you have set up your connection, you can run your queries in the query editor.
Once you have your database running, you can use the SurrealDB CLI to run your queries. To do so, run the following commands:
surreal sql --endpoint memory --ns namespace --db database --pretty
surreal sql --endpoint http://localhost:8000 --username root --password root --namespace test --database test
NoteThe
--endpointflag is the URL of your SurrealDB instance. The--usernameand--passwordflags are the credentials you set when you started the database. The--namespaceand--databaseflags are the namespace and database you want to connect to. The values above can be set to your preference. Learn more about this in the Start command documentation.
Once you see the >character you can type your SurrealQL query, followed by the enter key. The command has support for ↑ and ↓ arrows for selecting previous SurrealQL statements, and stores the statement history in a history.txt file. To exit the REPL use the ctrl + c or ctrl + d key combinations.
CREATEThe create statement is used to add records to the database.
The account record will be created, and a random ID has been generated for this record.
In SurrealDB, every record can be created and accessed directly by its ID. In the following query, we will create a record, but will use a specific ID.
You can also link records to each other by creating a mutual record, for example, create a blog article record, which links to the person and account tables.
In the following example we link to the specific person record directly by its ID, in the article table’s author field, and we link to the account record with a subquery which searches using the name field.
Let’s now create a blog article record, which references the person and account tables in it’s author and account fields.
SELECTThe querying functionality in SurrealDB works similarly to a traditional SQL, but with many of the added benefits of NoSQL query languages. To retrieve data, we will use a SELECT statement. You can query all the articles in your records and this will also return the record links.
SELECT * FROM article;
Also, in SurrealDB we can retrieve data from multiple different tables or records at once. In the example below we’ll retrieve data from both the article and the account table in one query.
SELECT * FROM article, account;
Also, instead of pulling data from multiple tables and merging that data together, SurrealDB allows you to traverse related records efficiently without needing to use JOINs. In the following example, we will get all the articles where the author is younger than 30.
In order to get the information for the author age for our filter condition we need to fetch the relevant records from the person table referenced by the author field.
SELECT * FROM article WHERE author.age < 30 FETCH author, account;
UPDATESimilar to UPDATE in SQL you can also update specific IDs, for example say you wanted to update the first name of the person you can do so:
UPDATE person:john SET name.first = 'David', name.full = string::join(' ', name.first, name.last);
The above code will update the firstname to be David and then create a new string for fullname with the updated first and last name.
You can also update specific fields:
UPDATE person:john SET admin = false WHERE name.last = 'Adams';
DELETEYou can also delete specific records from the recordID DELETE person:john with the DELETE statement or, you could delete a record with specific conditions:
DELETE article WHERE person.name.first = 'David';
REMOVEYou can also remove a specific table using the REMOVE TABLE:
REMOVE TABLE person
REMOVE TABLE article
Congratulations, you’re now on your way to database and API simplicity! For the next steps, take a look at some of our in-depth guides to see some of the other advanced functionality that you can use in SurrealDB.
By completing this guide you have successfully set up a SurrealDB database and ran some SurrealQL queries. To learn more about SurrealQL, refer to the SurrealQL guides.