Deploy on Surreal Cloud

What is Surreal Cloud?

Surreal Cloud is a fully managed database service that provides a seamless deployment experience for SurrealDB. It’s designed to be lightweight, leveraging the open-source SurrealDB product as much as possible. Its features are intended to complement those of the open-source version and offer you a seamless deployment experience.

In this guide, we’ll walk through the process and options to deploy SurrealDB using Surreal Cloud.

Requirements

To get started with Surreal Cloud, you’ll need to have an account. If you don’t have one, you can sign up for a free account by downloading Surrealist or using the Surrealist web app.

Create an Instance

To create an Instance, in Surrealist, click on the Surreal Cloud tab and select Continue. This will prompt you to the authentication page. If you don’t have an account, you’ll be asked to sign up with an email address, Google, or GitHub.

After you’ve signed up, you’ll be redirected to the Surreal Cloud dashboard. Here, you can create an Instance by clicking on the Create Instance button.

Configure your Instance

While creating an Instance, you’ll be asked to provide a few details about your Instance. These include:

• Instance Name: Easily distinguish and manage your Instance in the Surreal Cloud dashboard by assigning it a unique and meaningful name. This ensures seamless identification across your projects.
• SurrealDB Version: Stay up-to-date with the latest innovations! The Beta program ensures you’re always using the most recent version of SurrealDB.
• Instance Region: Optimize performance by selecting a deployment region close to your location. This minimizes latency, resulting in faster and smoother interactions.
• Instance Size: Tailor your Instance to meet your workload requirements. For free plans, you start with 0.25 vCPU and 512.00 MB of memory on a single-node setup—perfect for lightweight applications or experimenting.
• Instance Category: Choose the perfect fit for your use case:
  • Production: Built for high-performance and high-availability applications. Ideal for mission-critical projects.
  • Development: A cost-effective option designed for testing, prototyping, and building.
  • Free: Perfect for learners and hobbyists to experiment and explore the capabilities of SurrealDB without any cost.

Note

Both Production and Development categories are paid plans and allows you to further customize your Instance vCPU and memory. To use them, you’ll need to upgrade to a paid plan by adding billing information. In this guide, we’ll be using the free category which has a 0.25 vCPU and 512.00MB of memory on a single node. You can also upgrade your instance as it grows by updating your instance size.

After you’ve provided the required information, click on the Create button. This will start the Instance provisioning process.

Query your Instance

Query via Surrealist

You can connect to your Instance using Surrealist, the SurrealDB CLI, or the SurrealDB SDKs. In this guide, we’ll be using Surrealist as our client.

In the connect dropdown, select the Open in Surrealist option. This will open the query view in Surrealist. Before you can start querying your Instance, you’ll need to create a namespace and a database.

To create a namespace, click on the Create Namespace button. This will open a modal to input the name of the namespace. Once you’ve input the name, click on the Create button.

Note

You can create multiple namespaces in your Instance. If you previously created a namespace, you’ll see it in the dropdown and then the option will be to select the namespace.

To create a database, click on the Create Database button. This will open a modal to input the name of the database. Once you’ve input the name, click on the Create button. This will create the database.

After you’ve created a namespace and a database, you can start querying your Instance. For example, make a table called users and insert a record into it.

Create a user table and insert a record into it
-- Create schemaless user table.
DEFINE TABLE user SCHEMALESS;

-- Define some fields.
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string
  ASSERT string::is::email($value);
DEFINE INDEX userEmailIndex ON TABLE user COLUMNS email UNIQUE;

-- SEE IT IN ACTION - Example 1
-- 1: Add a user with all required fields and an undefined one.
CREATE user CONTENT { 
	firstName = 'Tobie', 
	lastName = 'Hitchcock', 
	email = 'Tobie.Hitchcock@surrealdb.com',
};

-- Query the data
SELECT * FROM user;

Additional Querying Options

You can also query your Instance using the SurrealDB CLI and the SurrealDB SDKs. They work similarly by providing a connection string to your Instance. The only difference is that with the CLI, you’ll be provided an authentication token to use with your Instance.

With the SDKs, you’ll use the connect method to connect to your Instance and then provide the namespace and database you want to work in. Lets take a look at some examples of how these work.

Connect via CLI

In your Instances dashboard, you’ll see a Connect button, select the Connect via CLI option. This will provide you with a connection string to your Instance. You can then copy the connection string and use it to connect to your Instance using the SurrealDB CLI.

Important

To connect via CLI, you’ll need to have the SurrealDB CLI installed. You can install the CLI by following the instructions in the installation guide.

Open your terminal and run the copied command, it should follow the following format:

Connect via CLI example
surreal sql --endpoint <connection-string> --token <token>

This will connect you to your Instance and you can start writing queries to your Instance.

Connect via SDKs

In addition to the first two methods, you can also connect to your Instance using the SurrealDB SDKs. The SurrealDB SDKs are available for a variety of languages, including JavaScript / TypeScript, Python, Rust, Go, and Java.

To use this method, you’ll need to have the SurrealDB SDK for your language installed. Once you’ve installed the SDK, you can use the connect method to connect to your Instance.

From the Surreal Cloud dashboard, you’ll see a Connect button, select the Connect via SDK option. This will provide you modal to carry out the following steps:

1. Select the language of the SDK you want to use.
2. Specify the Namespace and Database to connect to.
3. Add authentication details for your Instance.
4. Copy the code snippet to your project.

Once you’ve completed these steps, you can use the SDK to connect to your Instance and start querying your Instance.

Connect via HTTP

You can also connect to your Instance using the HTTP API. This allows you to connect to your Instance using any HTTP client. To get started, select the Connect button on your Instance. Then select HTTP cURL.

This will open a modal to fill in your credentials for Namespace and Database and authentication before you can copy the URL.

Conclusion

In this guide, we’ve shown you how to deploy SurrealDB using Surreal Cloud. We’ve also shown you how to query your Instance using Surrealist, the SurrealDB CLI, and the SurrealDB SDKs. For more information on Surreal Cloud, you can visit the Surreal Cloud documentation or the Surreal Cloud Landing Page.