This page will guide you through the process of setting up and using Surrealist. At this point we assume you have already installed Surrealist on your system. If you have not done so yet, please refer to the installation guide.
When launching Surrealist for the first time you will be greeted by the start screen. This screen allows you to easy jump into a sandbox environment or create a new connection to your SurrealDB instance. If you are new to SurrealDB or looking to experiment with SurrealQL, we recommend starting with the sandbox environment. This environment allows you to test and experiment without installing the SurrealDB database or storing data persistently.
If you are looking to connect to a local or remote hosted SurrealDB instance, you can create a new connection by pressing the “New connection” button. This will open the connection dialog where you can enter your database details.
In order to interact with a SurrealDB database you must first create a connection. Connections store the details required to connect to a database, such as the endpoint, namespace, database, and authentication details. When you select an active connection in Surrealist, you will connect to the database and be able to interact with it using the available interface views.
After opening a connection, you can switch to another connection at any time by pressing the connection name in the top left of the interface. This will open the connection list allowing you to switch to another connection, or create a new one.
Within the connection list you will also find a special connection called Sandbox, which is always available and allows you to test and experiment without storing data persistently. This connection is useful for learning SurrealQL, testing queries, and more. As the Sandbox connection runs inside a single thread within the browser’s WebAssembly engine, it should not be used to estimate or evaluate performance.
When creating a new connection you will be prompted with a dialog to enter your database details. These details are required to connect to your SurrealDB instance.
HTTP.test.test.Depending on the selected authentication method, you will be prompted to enter additional details such as a username and password, or a token.
After filling in all fields, press “Create connection” to continue. 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.
On the left side of the interface you will find the navigation sidebar. This sidebar allows you to switch between different views in Surrealist. Each view is focused on a specific workflow for working with the database. If you are just getting started, we recommend one of the following:
Additional views are available for managing your schema, writing stored procedures (functions), exploring API documentation, and more.
In addition to the different views, you can also find a button to open Surrealist Search, and a button to open the settings. Within the settings dialog you can also find an option to change the appearance of the navigation sidebar.
As mentioned earlier, the sandbox environment is a special connection that allows you to test and learn SurrealQL. When active, the toolbar will provide some additional buttons useful for working with the sandbox environment.
After reading this guide, you can watch the following video which covers some features of Surrealist that can help you get started. This includes organising connections and connection groups, recordID inspector, editor shortcuts, surrealist search and useful settings.