Deploy SurrealDB Earth and run your first query with one command

You can deploy a SurrealDB Earth instance from the Deploy page in Studio, or from your terminal with one surreal command that deploys an instance and runs your first query. Creating an instance takes about 500ms, and a cold start currently takes about 300ms.

Studio is the easiest way for most people to start, and the first section below covers it. If you spend most of your day in a terminal, the surreal CLI is the faster way, and the rest of this post shows how to use it.

What you need

Earth is serverless SurrealDB built on Cloudflare Durable Objects and R2. Each Earth database is its own instance.

You need two things before you start:

• •

  A SurrealDB Cloud account. You can sign up with Google, GitHub, or an email address and password. Earth Free needs no payment details, and it includes a monthly allowance. Earth Pro raises the allowance.

• •

  A browser or a terminal. Use a browser to deploy from Studio, or a terminal on macOS, Linux or Windows to deploy with the CLI.

Deploy from Studio

SurrealDB Studio offers the deploy flow as a page. Open your organisation, choose Instances, and select Deploy instance.

1. 1.

   Enter a name. The name cannot change later.

2. 2.

   Pick the Earth region card, which is the default.

3. 3.

   Choose where your data lives and, where one is offered, a preferred location. The section on data residency below explains the options.

4. 4.

   Review the instance details, including cells, network policy and capabilities.

5. 5.

   Choose a plan at checkout and select Deploy instance.

How do I install the surreal CLI?

surreal is SurrealDB's command-line tool. It is made of components that you install as you need them: surreal db runs the database on your own machine, and surreal cloud manages your SurrealDB Cloud instances. This post uses surreal cloud.

The install script installs surreal and the database, and --with cloud adds the cloud component in the same step:

curl -sSf https://install.surrealdb.com | sh -s -- --with cloud

To add a component later, install it by name:

surreal install cloud

Sign in to SurrealDB Cloud

Sign in once. The command opens a browser, or shows a device code or a URL when no browser is available.

surreal cloud auth login
surreal cloud whoami

If your account belongs to several organisations, choose the one to deploy into:

surreal cloud org list
surreal cloud org use acme

Deploy Earth with no questions asked

surreal cloud instance deploy with --yes takes every default and asks nothing. It deploys an Earth instance under a generated name such as brave-falcon, and waits until the instance is ready.

surreal cloud instance deploy --yes

Run the command without --yes and it asks for whatever the flags left out, in the same order as Studio's Deploy page, then confirms before it deploys. The CLI and Studio use the same defaults, so --yes and an untouched Deploy page produce the same instance.

Choose where your data lives

Every Earth instance has a data residency, which decides where its data may be stored and processed. Choose eu to keep the data inside the European Union, or us to keep it inside the United States. The default, world, lets Earth place the instance anywhere on Cloudflare's network.

Within a residency, a location hint says where you would prefer the instance to run, usually near most of your users. Without one, Earth places the instance automatically.

The command below deploys an instance named my-app that keeps its data in the EU and prefers to run in Western Europe:

surreal cloud instance deploy my-app --residency eu --location-hint weur --yes

Choose the residency and the location hint with care, because neither can change after the instance is created. surreal cloud catalog residencies lists the residencies and the location hints each one accepts.

Deploy and run a query in one command

surreal cloud instance sql --deploy deploys an instance, waits for it, creates a database token and opens a SurrealQL shell on it. Pipe a query into it, and the shell runs the query and exits:

echo "CREATE person:tobie SET name = 'Tobie'; SELECT * FROM person;" \
  | surreal cloud instance sql --deploy --yes --namespace app --database main

The namespace and database are created on first use. The token is passed to the shell in an environment variable, so it never appears on the command line.

Query an instance you already have

Open a shell on an existing instance by name:

surreal cloud instance sql my-app --namespace app --database main

Then run SurrealQL at the prompt:

CREATE person:tobie CONTENT { name: 'Tobie', city: 'London' };
SELECT * FROM person;

import and export connect to the database the same way, so surreal cloud instance export my-app exports the instance you just queried.

CLI flags for Earth

These flags apply to surreal cloud instance deploy when you deploy Earth:

A flag that belongs to a dedicated instance, such as --nodes or --type, is refused for Earth. Pass a cloud region to --region to deploy a dedicated instance instead.

Clean up

List your instances and delete the one you created:

surreal cloud instance list --earth
surreal cloud instance delete my-app --force

Every command accepts --json, so surreal cloud instance list --json | jq -r '.[].name' prints the instance names for scripts.

Next steps

An Earth instance takes one step in Studio or one command in a terminal. Sign up with an email address, deploy with surreal cloud instance deploy --yes or from the Deploy page, and choose a residency such as eu when your data needs to stay in one region. surreal cloud instance sql --deploy goes one step further and runs your first query on the new instance in the same command.

The SurrealDB Earth documentation covers cells, residency, network policy and usage in more depth, and the surreal cloud reference lists every command.

Start free on Earth