Surrealist
Surrealist is a user interface for interacting with your SurrealDB database visually. It enables you to seamlessly connect to any SurrealDB instance, allowing you to execute queries, explore your tables, design your schemas, and much more. Surrealist is available as a web and desktop app, and this guide will walk you through the setup process, interface navigation, and everything you need to know to get started. the setup process, interface navigation, and everything you need to know to get started.
Installation
Desktop app
You can download the latest version of Surrealist from our GitHub releases page. We support installers for Windows (msi), MacOS (dmg), and Linux (AppImage). If your platform is unsupported you can still make use of the web app version of Surrealist, although it has a few caveats compared to the desktop app.
Web app
The hosted web version of Surrealist is available at surrealist.app and includes most of the functionality offered by the desktop app, except the ability to spin up a local SurrealDB instance directly from the interface.
NOTE: Due to security restrictions it will not always be possible to connect to databases hosted locally on localhost (or 127.0.0.1) using the web app in certain browsers. If you intend on doing so, we recommend using the desktop app instead as it does not have such restrictions.
Set up
When starting up Surrealist you can choose between creating your first connection or opening the sandbox environment. If you are looking to experiment with SurrealQL or get started without setting up a database, choose the sandbox, otherwise select create connection to enter your connection details.
Connections
In the connection option Surrealist allows you to define and manage multiple connections, each having it’s own combination of endpoint, namespace, database, and authentication. Connections store their own query tabs, favourite tables, and more. You can create as many connections as you prefer, however only one can be active at once. This connection will be displayed in the top left of the interface.
Before creating a connection, ensure that you have a database running that you can connect to. If you are unsure how to do this, you can follow the running SurrealDB guide to start an in-memory database.
Views
The interface of Surrealist is divided into separate views, each focused on a specific workflow for working with the database. You can switch between views using the navigation bar on the left of the screen. If you are just getting started, we recommend using the Query view where you can start writing your SurrealQL queries and visualise their responses. Each available view will be explained in further detail later on in this page.
Connecting to SurrealDB
You can connect to a local or remote SurrealDB instance by creating a new connection. The connection dialog requires an endpoint, database details, and authentication details.
Enter your database address into the first field in the dialog. The address can be localhost, an ip address, or a domain name. If the database is running on a specific port make sure to append it after the address as well.
The dropdown to the left of the address is the protocol used to connect to your database. If you are unsure what to choose, select HTTP.
In the database section you must enter the namespace and database to use for your connection.
The authentication section first asks you for the authentication method. Changing this can also change the details you will have to enter. For scope authentication, you can also manage the scope data sent along with your request by pressing “Edit scope data”.
After filling in all fields, press “Create connection” to continue. You will now be able to see all available views. If the connection was established successfully, you should see a green indicator next to the session name in the top left of the interface.
If the connection failed and you see a red indicator, make sure all your details are correct and update your connection accordingly. You can edit connection details again by expanding the connection list, and choosing “Edit” on your connection.
Connecting to the sandbox
You can always switch to the sandbox by opening the connections list and choosing “Sandbox”. This option is always available and useful in situations where you would like to test and experiment without storing data persistently.
If you would like to clear the sandbox manually, you can press the “Reset sandbox environment” to clear any records and schema you have configured.