---
title: "Deploy SurrealDB"
description: "Multi-model database for documents, graphs and vectors in one engine"
category: "Storage"
url: https://railway.com/deploy/surrealdb
---

# Deploy SurrealDB

Multi-model database for documents, graphs and vectors in one engine

**[Deploy SurrealDB on Railway](https://railway.com/template/surrealdb)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/surrealdb/manifest.json

- **Creator:** A3A
- **Category:** Storage

## Template content

### surrealdb https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/surrealdb.svg

- **Image:** surrealdb/surrealdb:v3.2
- **Start command:** `/surreal start`
- **Health check:** /health

### backup https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/docker-volume-backup.svg

- **Source:** https://github.com/gridalpha/surrealdb-railway
- **Health check:** /healthz

### console https://raw.githubusercontent.com/surrealdb/surrealist/main/src-tauri/icons/icon.png

- **Source:** https://github.com/gridalpha/surrealdb-railway
- **Health check:** /healthz
- **Public domain:** Yes

## Buckets

- **backups**

## Documentation

# Deploy and Host SurrealDB on Railway

Deploy SurrealDB to get one database that stores documents, graph edges, vectors, time-series and key-value data behind a single query language. Teams normally reach for Postgres for relational data, MongoDB for documents and Neo4j for relationships, then spend the project keeping them in sync. SurrealQL removes that split: a record can hold nested objects, be joined by graph edges written `->edge->`, and be searched by full-text or vector index, in one statement. Written in Rust, it speaks HTTP and WebSocket on one port and enforces record-level permissions, which is why it is often used as an application's entire backend.

Self-host SurrealDB here as three services. `surrealdb` runs the database on the official `surrealdb/surrealdb:v3.2` image, storing data with RocksDB on a persistent volume, on the private network with no public URL. `console` serves Surrealist, SurrealDB's official browser console, and reverse-proxies the database API from the same origin, so one HTTPS address gives you both a query workbench and the `wss://.../rpc` endpoint your application connects to. `backup` exports every namespace and database on a schedule to a Railway object storage bucket, so your data survives more than the disk it sits on.

![Console, backup worker and SurrealDB services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1788761038/surrealdb-architecture.png)

## Getting Started with SurrealDB on Railway

Open the public URL of the `console` service and Surrealist loads. There is no account to create — it is a client, and the database's root credentials are the only login. Click **Create connection**, leave the protocol on **WSS**, and enter your Railway domain as the remote address, with no `https://` prefix and no port. Under **Authentication**, keep the **Root** tab and enter the `SURREAL_USER` and `SURREAL_PASS` values from the `surrealdb` service. Save it, and Surrealist opens on the `main` namespace and database the server creates on first boot.

The **Query** view runs SurrealQL. A good first check is `CREATE artist SET name = 'Bonobo';` then `SELECT * FROM artist;` — if the record comes back, the database, the volume and the proxy all work. **Explorer** browses records without a query, **Designer** draws the schema and its graph edges, and **Authentication** is where you define scoped users instead of giving applications root. Your application connects to the same host: `wss:///rpc` for the WebSocket SDKs, or `https:///sql` for plain HTTP. Services inside the project use `http://surrealdb.railway.internal:8000`.

![Surrealist running a SurrealQL graph traversal over artists and albums](https://res.cloudinary.com/rroe4rtk/image/upload/v1788761040/surrealdb-query-graph-traversal.png)

![Surrealist record explorer listing four artist records](https://res.cloudinary.com/rroe4rtk/image/upload/v1788761041/surrealdb-explorer-artist-records.png)

![Surrealist designer showing the album and artist table schemas](https://res.cloudinary.com/rroe4rtk/image/upload/v1788761043/surrealdb-designer-schema.png)

## About Hosting SurrealDB

SurrealDB is built to be the whole data layer of an application. It answers a problem most teams meet in a product's second year: the relational schema is fine, but half the interesting questions are about relationships, and answering them means joining across three systems. Self-host it when you want that consolidation under your own control, when queries are graph-shaped, or when permissions belong in the database rather than in every service that talks to it.

- SurrealQL: SQL-like, with graph traversal, nested records and computed fields
- Document, graph, vector, geospatial, full-text and time-series data in one engine
- Row-level permissions and record access rules defined in the schema itself
- Live queries that push changes to connected clients over WebSocket
- Official SDKs for Rust, JavaScript, Python, Go, Java and .NET

The architecture keeps the roles separate. The database is private, so nothing reaches it but the console and your own services. The console is the only public surface, and because it proxies the database's routes on its own origin, browser clients need no CORS configuration. The backup worker holds no state: it reads through the API and writes elsewhere, which is what makes it useful when a volume is lost.

## Why Deploy SurrealDB on Railway

Railway removes the parts of running a database that are not the database.

- The volume, the private network and TLS are provisioned for you
- One public origin serves the console and your application's API endpoint
- Object storage for backups sits in the same project
- Vertical scaling is a slider, not a migration
- Deploys, logs and metrics live beside the rest of your stack

## Common Use Cases

- Application backends where users, permissions and relationships live in one store rather than a database plus a separate auth service
- Recommendation and knowledge-graph features, where `->edge->` traversals replace recursive CTEs or a second graph database
- Real-time dashboards and collaborative tools driven by live queries over WebSocket
- Retrieval features keeping documents, embeddings and relationships together instead of in a vector store beside a database

## Dependencies for SurrealDB

- `surrealdb/surrealdb:v3.2` — the database server, official image
- `caddy:2-alpine` with `surrealdb/surrealist` — the console, built from [gridalpha/surrealdb-railway](https://github.com/gridalpha/surrealdb-railway)
- `alpine:3.22` — the backup worker, same repository
- A volume mounted at `/data` and one object storage bucket

### Environment Variables Reference

| Variable | Service | Purpose |
|---|---|---|
| `SURREAL_USER` / `SURREAL_PASS` | surrealdb | Root credentials, created on first boot and kept in storage |
| `SURREAL_PATH` | surrealdb | Storage backend and location, `rocksdb:/data/surreal.db` |
| `SURREAL_BIND` | surrealdb | Listen address, `[::]:8000` so private clients reach it |
| `SURREAL_UPSTREAM` | console | Host and port of the database the console proxies |
| `BACKUP_INTERVAL_SECONDS` | backup | Seconds between backup cycles, default one day |
| `BACKUP_RETENTION` | backup | Dumps kept per database before the oldest is deleted |

### Deployment Dependencies

- Source and docs: [surrealdb/surrealdb](https://github.com/surrealdb/surrealdb), [surrealdb.com/docs](https://surrealdb.com/docs)
- Console: [surrealdb/surrealist](https://github.com/surrealdb/surrealist)
- Image: [surrealdb/surrealdb](https://hub.docker.com/r/surrealdb/surrealdb) on Docker Hub

## Hardware Requirements for Self-Hosting SurrealDB

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2–4 vCPU |
| RAM | 512 MB | 2–4 GB |
| Storage | 1 GB volume | 10 GB+, sized to your dataset |
| Runtime | Linux container | Linux container |

RocksDB sizes its block cache from the memory the container is allowed, so more RAM directly increases how much of the working set stays hot.

## Self-Hosting SurrealDB

The server is a single binary with no configuration file: everything is an environment variable or an argument. This runs a persistent instance with Docker:

```
docker run --rm -p 8000:8000 -v surreal:/data \
  -e SURREAL_USER=root -e SURREAL_PASS=change-me \
  surrealdb/surrealdb:v3.2 start rocksdb:/data/surreal.db
```

Any HTTP client can then query it. This is a shell example using curl:

```
curl -u root:change-me \
  -H 'surreal-ns: main' -H 'surreal-db: main' \
  -H 'Accept: application/json' \
  --data 'CREATE artist SET name = "Bonobo";' \
  http://localhost:8000/sql
```

To restore a dump, pipe it into the `/import` route with the target namespace and database in the headers. Objects are keyed `surrealdb///.surql.gz`.

## How Much Does SurrealDB Cost to Self-Host?

The server is free. SurrealDB ships under the Business Source License 1.1, which permits any use except offering it to third parties as a database service, and converts to Apache 2.0 on 1 January 2030 — building a product on it is inside the grant. A paid SurrealDB Cloud and an Enterprise edition for clusters exist, but neither is needed here. On Railway you pay only for the compute, volume and object storage these services use.

## FAQ

**What is SurrealDB?**
A multi-model database written in Rust that stores documents, graphs, vectors and time-series data behind one query language, SurrealQL, over HTTP and WebSocket.

**What does this Railway template deploy?**
Three services: the SurrealDB server with a persistent volume, the Surrealist console on a public URL that also proxies the database API, and a worker backing up every database to object storage.

**Why does the template include an object storage bucket?**
A volume attaches to one service and lives beside the data it holds, so it cannot protect you from losing that service. The backup worker exports through the API and writes the dumps elsewhere.

**How do I connect my application to self-hosted SurrealDB?**
Inside the project, point the SDK at `http://surrealdb.railway.internal:8000`. From outside, use `wss:///rpc` or `https:///sql` on the console's domain, with root or a scoped user.

**Is the database reachable without a password?**
No. Guest access is denied, so unauthenticated queries are rejected with HTTP 403 and a wrong password with 401. Define scoped users under **Authentication** and keep root for administration.

**Can I run SurrealDB as a multi-node cluster on Railway?**
Not in this shape. SurrealDB documents self-hosted clustering as an Enterprise feature running on Kubernetes; the single-node RocksDB deployment here is what its own docs recommend for self-hosted production.


## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/surrealdb