SurrealDB Earth

SurrealDB Earth is serverless SurrealDB that runs on the Cloudflare network.

You get a full SurrealDB database with SurrealQL, transactions and live queries. You do not choose an instance type or a node count: Earth adds compute when traffic grows and scales to zero when the instance is idle.

Earth is a separate product from the Start and Scale plans. Some SurrealDB features are not available on Earth yet. See Features not available yet before you move a workload to it.

When to use Earth

Use Earth when	Use Start or Scale when
Traffic is irregular, or the database is idle for long periods	Traffic is steady and you want fixed capacity
Clients connect from many locations	Clients run in one cloud region, next to the database
You want no capacity planning	You want to choose the instance type and the number of nodes
The workload does not need the features listed below	The workload needs change feeds, Surrealism, JavaScript functions or DiskANN vector indexes

How Earth works

An Earth instance has three parts:

Compute: SurrealDB runs on the Cloudflare network, close to the clients that connect to it. Each client session is served by one compute unit. When the sessions on the current units fill them, Earth starts more units for the instance.
Commit order: each instance has one commit log. Every transaction commits in one strict order, so a transaction sees a consistent snapshot of the data and conflicting writes fail at commit, as they do on any SurrealDB server.
Storage: the data of an instance is kept in Cloudflare object storage in one location. Earth writes a commit to durable storage before it acknowledges the commit.

These parts give the behaviour that follows:

Single-location storage, queries from many locations. The data lives in one place, and queries arrive through the Cloudflare location nearest to each client.
Scale to zero. After the last request, an idle instance stops using compute. The next request wakes it. The first request after an idle period can take longer than later requests.
Fully transactional. Explicit transactions (BEGIN and COMMIT) and single statements both commit in the instance's one commit order.
Highly available. No single compute unit holds data that only it can serve. If a unit fails, a new unit serves its sessions and reads the data from storage.

Connect to an Earth instance

You connect to an Earth instance in the same way as to any other instance: with SurrealDB Studio, an SDK, the CLI or HTTP. Use the connection URL that Studio shows for the instance.

Use a WebSocket connection when a client sends many queries. Each HTTP request is routed and authenticated separately, so a long series of HTTP requests is slower than the same queries on one open WebSocket.

Connect with PostgreSQL or MySQL clients

PostgreSQL and MySQL clients connect to an Earth instance over TCP. TLS is required, and a connection without TLS is closed.

A client names the instance in one of two ways: in the TLS server name (SNI), or in the user name as <user>@<instance-id>.

Client	Host	Port	User name
PostgreSQL client that sends SNI	`<instance-id>.sql.surrealdb.earth`	`5432`	`<user>`
PostgreSQL client that does not send SNI	`sql.surrealdb.earth`	`5432`	`<user>@<instance-id>`
MySQL client	`sql.surrealdb.earth`	`3306`	`<user>@<instance-id>`

MySQL clients, such as the mysql CLI and other clients built on libmysqlclient, do not send SNI, so a MySQL user name always includes @<instance-id>.

When a client does not send SNI and the user name has no @<instance-id>, Earth closes the connection without an error message. psql then reports server closed the connection unexpectedly. Add @<instance-id> to the user name, or connect to <instance-id>.sql.surrealdb.earth with a client that sends SNI.

Sign in with a user defined ON DATABASE. Users defined ON ROOT or ON NAMESPACE cannot run queries over PostgreSQL or MySQL, so define a database user first:

Define a database user

DEFINE USER app ON DATABASE PASSWORD 'change-me' ROLES EDITOR;

Name the namespace and database as <namespace>/<database>, with a slash:

Connect with psql

psql "host=<instance-id>.sql.surrealdb.earth port=5432 user=app dbname=main/main sslmode=require"

Connect with psql, without SNI

psql "host=sql.surrealdb.earth port=5432 user=app@<instance-id> dbname=main/main sslmode=require"

Connect with the mysql CLI

mysql -h sql.surrealdb.earth -P 3306 -u 'app@<instance-id>' -p --ssl-mode=REQUIRED main/main

Handle busy responses

When an instance is adding compute, Earth can answer a new request with HTTP status 503. The request did not start, so it is safe to send again. Retry it after a short delay, and increase the delay for each retry.

Earth does not refuse work that belongs to a transaction it has already accepted. A transaction that has started continues to its commit or rollback.

Features not available yet

The features below are not available on Earth. They are planned for a future release.

Feature	What happens on Earth	Documentation
Change feeds	`SHOW CHANGES` returns an error, and a table or database defined with `CHANGEFEED` records no changes	Change feeds
Surrealism	WebAssembly extensions cannot be loaded or called	Extensions
JavaScript functions	Embedded scripting functions, written as `function() { ... }`, are turned off. The scripting capability cannot be turned on	Scripting
DiskANN vector indexes	A `DEFINE INDEX ... DISKANN` statement returns an error. Define the vector index with `HNSW` instead, which Earth supports	Vector indexes

If your workload needs one of these features now, deploy it on the Start or Scale plan.

Note

Check the changelog for features as they become available on Earth.

Things to know

Define a table before a long transaction writes to it. A transaction that creates a table by its first write, and stays open for a long time, can fail at commit with a transaction conflict. Run DEFINE TABLE first, outside the transaction, and the same transaction commits.
Capabilities still apply. You can allow or deny functions, network targets and other capabilities for an Earth instance. The scripting capability always stays off.
The first request after an idle period is slower. An instance that has scaled to zero starts again on its next request.

Instances: the Start and Scale plans and how they differ.
Connect to an instance: Studio, SDKs, the CLI and HTTP.
Live queries: real-time notifications, which Earth supports.
Pricing: how Earth usage is billed.