Deploy and Host SurrealDB on Railway

SurrealDB is an open-source, multi-model database written in Rust. One engine stores documents, graph relations, key-value data, time series and vector embeddings, and you query all of them with SurrealQL, an SQL-like language. Clients connect over HTTP or WebSocket, with official SDKs for JavaScript, Python, Rust, Go and more.

About Hosting SurrealDB

This template runs the official surrealdb/surrealdb v4.0.1 image, pinned by digest, as a single service. Data is stored with SurrealKV, the on-disk engine in SurrealDB 4 (RocksDB was removed in v4), on a Railway volume mounted at /data, so it survives restarts and redeploys. Authentication is on from the first start: a root user is created with a generated 32-character password, and anonymous queries are refused. The public HTTPS domain serves the HTTP API and the WebSocket RPC endpoint that Surrealist and the SDKs use. Other Railway services can connect over the private network instead. Railway checks /health before routing traffic.

Common Use Cases

Backend database for web and mobile apps that mix relational, document and graph data
Vector and full-text search store for AI agents and retrieval-augmented generation (RAG)
Real-time apps that use live queries over WebSocket, with row-level permissions defined in the database

Dependencies for SurrealDB Hosting

The official SurrealDB container image (surrealdb/surrealdb:v4.0.1)
A Railway volume for the SurrealKV data files

Deployment Dependencies

SurrealDB on GitHub: https://github.com/surrealdb/surrealdb
SurrealDB v4.0.1 release: https://github.com/surrealdb/surrealdb/releases/tag/v4.0.1
surreal start options: https://surrealdb.com/docs/surrealdb/cli/start
Environment variables: https://surrealdb.com/docs/surrealdb/cli/env
Surrealist (web UI): https://app.surrealdb.com

Implementation Details

Sign in. The username is root, and the password is the SURREAL_PASS variable on the SurrealDB service. The default namespace and database are both main. The root password is set only when the datastore is first created, so changing SURREAL_PASS later does not change it. Use ALTER USER or DEFINE USER OVERWRITE in SurrealQL instead.

Connect with Surrealist. Open https://app.surrealdb.com, create a connection with protocol wss, enter the value of SURREALDB_WS_URL (for example wss://your-app.up.railway.app/rpc), choose Root authentication, and sign in with root and your password.

Connect from another Railway service. Use the reference variables ${{SurrealDB.SURREALDB_PRIVATE_URL}} (HTTP on the private network, port 8000) and ${{SurrealDB.SURREAL_PASS}}. The service listens on IPv4 and IPv6.

Quick test with curl:

curl -u root:YOUR_PASSWORD -H "Accept: application/json" \
  -H "Surreal-NS: main" -H "Surreal-DB: main" \
  --data "CREATE person SET name = 'Ada'; SELECT * FROM person;" \
  https://your-app.up.railway.app/sql

Notes.

RAILWAY_RUN_UID=0 is required. The image runs as a non-root user, and Railway volumes are owned by root, so without it the server fails with "Permission denied".
/health, /version and /metrics answer without login. /metrics reports only process statistics (CPU, memory, uptime and build version), never your data.
SurrealKV sizes its caches from the service's memory limit. To cap memory use, set SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY and SURREAL_SURREALKV_MAX_MEMTABLE_SIZE (in bytes).
To remove the public endpoint, delete the Railway domain and connect only over the private network.

Why Deploy SurrealDB on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying SurrealDB on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.