Skip to content

Tutorials

Query SurrealDB from Postman

SurrealDB provides a RESTful HTTP API for interacting with the database.

In this tutorial, you will learn how to query SurrealDB endpoints via the Postman collection. SurrealDB supports requests over HTTP and REST, which can handle queries ranging from creating simple tables to graph relationships between complex tables.

Check out the HTTP & REST integration documentation for a detailed list of all the endpoints supported.

This tutorial assumes that you have the following:

Before forking the Collection from Postman, ensure that you have your SurrealDB instance running locally because by default the collection endpoint is set to localhost:8000 or http://127.0.0.1:8000

To do so run the Start command in your terminal:

surreal db start --user root --pass secret

The above command starts SurrealDB with authentication and specifies that the user and password are root. Note that this is just for demonstration purposes. You can replace root in both instances with any other value.

After running locally, head over to Postman and create a fork for your workspace. You should see all the endpoints listed. You can also check the endpoints in the documentation.

You can get information about your workspace by using the INFO statement. However, you need the right permissions in order to see the output. See the documentation for the INFO statement.

Note that the namespace and database values for the Postman collection are set to test by default.

You can see the JSON output using the INFO statement in the body of the request.

INFO FOR ROOT / DB / NS

Below is the output of querying for the info of the current namespace.

INFO FOR NS
[
    {
        "result": {
            "accesses": {},
            "databases": {
                "test": "DEFINE DATABASE test"
            },
            "users": {}
        },
        "status": "OK",
        "time": "190.166µs"
    }
]

To define a record user, first navigate to the POST /sql endpoint and in the header of the request add the following fields:

Accept:application/json
NS:{{namespace}}
DB:{{database}}

You can also define a system user with other credentials such as Root or Database user. For this tutorial, we will be using only record users.

Note

The Namespace and Database fields are set to the value test by default. You can change this in the collection settings.

In the request body, define the record access method human with a session of 24 hours:

DEFINE ACCESS human ON DATABASE TYPE RECORD
    SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
    SIGNIN ( SELECT * FROM user WHERE email = $email
      AND crypto::argon2::compare(pass, $pass) )
    DURATION FOR SESSION 24h
;

The code above allows a user to sign up as a record user with their email and password, and hashes the password with the crypto::argon2::generate function.

The sign in logic gets all the users where the emails match and uses the crypto::argon2::compare function to compare the stored hash with the password provided.

Now when you get the info of the Database using INFO for DB you can see the access method human in the following output:

[
    {
        "result": null,
        "status": "OK",
        "time": "102.458µs"
    },
    {
        "result": {
            "accesses": {
                "human": "DEFINE ACCESS human ON DATABASE TYPE RECORD SIGNUP (CREATE user SET email = $email, pass = crypto::argon2::generate($pass)) SIGNIN (SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass)) DURATION FOR TOKEN 1h, FOR SESSION 1d"
            },
            "analyzers": {},
            "functions": {},
            "models": {},
            "params": {},
            "tables": {},
            "users": {}
        },
        "status": "OK",
        "time": "78.084µs"
    }
]

After defining the signup and signin logic head over to the POST /signup endpoint to signup and in the header of the request add the following fields:

Accept:application/json
namespace:test
database:test
access:human  

In the body of the request add the following information:

{
    "ns": "test",
    "db": "test",
    "ac": "human",
    "email": "test@surreal.com",
    "pass":"1234567886"
}

The result will be a JSON object:

{
    "code": 200,
    "details": "Authentication succeeded",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDY2NTgsIm5iZiI6MTcwNzE0NjY1OCwiZXhwIjoxNzA3MjMzMDU4LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJBQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOnc2ZzBsNmh5eHpjZzlubTY2dGVjIn0.8Gud51cocThB8DMKD1zovtGiVgf5L1dAS6-pjWb6Lm6a7-4Spp7xXjD7JrHHdtJVNX1O0d8GdjZwRGTsP_NM9A"
}

Now that a user is defined, you can sign in. To do so, go to the POST /signin endpoint and use the same credentials. In the body of the request, add the same information you used to sign up:

{
    "ns": "test",
    "db": "test",
    "ac": "human",
    "email": "test3@surreal.com",
    "pass":"1234567886"
} 

This should return a similar JSON object indicating successful authentication and providing a new token.

{
    "code": 200,
    "details": "Authentication succeeded",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDY2NTgsIm5iZiI6MTcwNzE0NjY1OCwiZXhwIjoxNzA3MjMzMDU4LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJBQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOnc2ZzBsNmh5eHpjZzlubTY2dGVjIn0.8Gud51cocThB8DMKD1zovtGiVgf5L1dAS6-pjWb6Lm6a7-4Spp7xXjD7JrHHdtJVNX1O0d8GdjZwRGTsP_NM9A"
}

The Postman collection has a couple of endpoints for POST GET PUT PATCH DEL operations. For example, if you want to add a new entry to the table Person (which is the default table in the collection), go to the POST /key/:table endpoint and add the table content in the body of the request. For example:

{
    age: 32,
    name: 'John'
}

You should get a response as seen below, notice that there is a record ID, with this record ID you can now use any of the /key/:table/:id endpoints for POST GET PUT PATCH DEL operations.

[
    {
        "result": [
            {
                "age": 32,
                "id": "person:p1cdf6cx89gnfboq5wye",
                "name": "John"
            }
        ],
        "status": "OK",
        "time": "105.667µs"
    }
]

In this tutorial, we've walked through how to set up and use SurrealDB over HTTP using Postman. We've covered how to define a new record access method, sign up a new user, and sign in with a user. These are the steps for managing user authentication in your applications using SurrealDB.

The Postman collection is still in active development. For more information on using SurrealDB via the HTTP endpoints, check out our documentation on HTTP and REST endpoints.

Was this page helpful?

Last updated