> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt # SurrealDB Earth What SurrealDB Earth is, how it runs SurrealDB on the Cloudflare network, and which features are not available on it yet. 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](/docs/manage/instances.md). Some SurrealDB features are not available on Earth yet. See [Features not available yet](#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](/docs/manage/instances/connect/via-studio.md), [an SDK](/docs/manage/instances/connect/via-sdk.md), [the CLI](/docs/manage/instances/connect/via-cli.md) or [HTTP](/docs/manage/instances/connect/via-http.md). 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 `@`. | Client | Host | Port | User name | | --- | --- | --- | --- | | PostgreSQL client that sends SNI | `.sql.surrealdb.earth` | `5432` | `` | | PostgreSQL client that does not send SNI | `sql.surrealdb.earth` | `5432` | `@` | | MySQL client | `sql.surrealdb.earth` | `3306` | `@` | MySQL clients, such as the `mysql` CLI and other clients built on libmysqlclient, do not send SNI, so a MySQL user name always includes `@`. When a client does not send SNI and the user name has no `@`, Earth closes the connection without an error message. `psql` then reports `server closed the connection unexpectedly`. Add `@` to the user name, or connect to `.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](/docs/reference/query-language/statements/define/user.md) first: ```surql title="Define a database user" DEFINE USER app ON DATABASE PASSWORD 'change-me' ROLES EDITOR; ``` Name the namespace and database as `/`, with a slash: ```bash title="Connect with psql" psql "host=.sql.surrealdb.earth port=5432 user=app dbname=main/main sslmode=require" ``` ```bash title="Connect with psql, without SNI" psql "host=sql.surrealdb.earth port=5432 user=app@ dbname=main/main sslmode=require" ``` ```bash title="Connect with the mysql CLI" mysql -h sql.surrealdb.earth -P 3306 -u 'app@' -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](/docs/learn/querying/real-time/changefeeds.md) | | **Surrealism** | WebAssembly extensions cannot be loaded or called | [Extensions](/docs/learn/extensions.md) | | **JavaScript functions** | Embedded scripting functions, written as `function() { ... }`, are turned off. The scripting capability cannot be turned on | [Scripting](/docs/reference/query-language/scripting/overview.md) | | **DiskANN vector indexes** | A `DEFINE INDEX ... DISKANN` statement returns an error. Define the vector index with `HNSW` instead, which Earth supports | [Vector indexes](/docs/learn/data-models/vector-search/vector-indexes.md) | If your workload needs one of these features now, deploy it on the [Start or Scale plan](/docs/manage/instances/create.md). > [!NOTE] > Check the [changelog](https://surrealdb.com/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](/docs/learn/security/authorization/capabilities.md) 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. ## Related pages - **[Instances](/docs/manage/instances.md):** the Start and Scale plans and how they differ. - **[Connect to an instance](/docs/manage/instances/connect.md):** Studio, SDKs, the CLI and HTTP. - **[Live queries](/docs/learn/querying/real-time/live-queries.md):** real-time notifications, which Earth supports. - **[Pricing](https://surrealdb.com/pricing):** how Earth usage is billed.