Deploy SurrealDB 4.x

SurrealDB — The multi-model database for AI agents

Develop easier.   Build faster.   Scale quicker.

What is SurrealDB?

SurrealDB is an end-to-end cloud-native database designed for modern applications, including web, mobile, serverless, Jamstack, backend, and traditional applications. With SurrealDB, you can simplify your database and API infrastructure, reduce development time, and build secure, performant apps quickly and cost-effectively.

Key features of SurrealDB include:

• Reduces development time: SurrealDB simplifies your database and API stack by removing the need for most server-side components, allowing you to build secure, performant apps faster and cheaper.
• Real-time collaborative API backend service: SurrealDB functions as both a database and an API backend service, enabling real-time collaboration.
• Support for multiple querying languages: SurrealDB supports SQL querying from client devices, GraphQL, ACID transactions, WebSocket connections, structured and unstructured data, graph querying, full-text indexing, and geospatial querying.
• Granular access control: SurrealDB provides row-level permissions-based access control, giving you the ability to manage data access with precision.

Features

• Database server, or embedded library
• Multi-row, multi-table ACID transactions
• Single-node, or highly-scalable distributed mode
• Record links and directed typed graph connections
• Store structured and unstructured data
• Incrementally computed views for pre-computed advanced analytics
• Realtime-api layer, and security permissions built in
• Store and model data in any way with tables, documents, and graph
• Simple schema definition for frontend and backend development
• Connect and query directly from web-browsers and client devices
• Use embedded JavaScript functions for custom advanced functionality

Documentation

For guidance on development, and administration, see their documentation.

What changed in 4.0 is in the release notes.

Deploy and Host SurrealDB 4.x on Railway

This template runs one SurrealDB 4.x node from the official surrealdb/surrealdb:v4 image. Data is stored with SurrealKV on a Railway volume at /data, backed up daily. A root user and password are generated when you deploy, guest access is denied, and the database is reachable over HTTPS and WebSockets on a public domain and over Railway's private network.

About Hosting SurrealDB 4.x

SurrealDB 4.x is a single binary that serves its HTTP and WebSocket APIs on one port (8000 here). On a single node it stores data with SurrealKV, which is now its only on-disk engine: RocksDB was removed in 4.0. Clusters run on TiKV through a separate surreal-tikv build, which this template doesn't use. Hosting it yourself comes down to a persistent disk for the datastore, TLS in front of the API, and a private route for your app to reach it. On Railway the volume, the TLS-terminated public domain and the private network all come with the template.

Common Use Cases

• AI agents and generative AI apps: memory, vector search, graph context and relational data behind one API.
• Knowledge graphs: typed graph edges and traversal for recommendations and reasoning over linked entities.
• Real-time applications: live queries and change feeds for dashboards, collaborative tools and multiplayer state.
• Multi-tenant SaaS: namespaces, databases and row-level permissions to keep customers apart.
• Backends for static and serverless frontends: query SurrealDB directly over HTTP or WebSockets, with access rules in the database instead of a middleware layer.

Dependencies for SurrealDB 4.x Hosting

The template is self-contained: one service and one volume, nothing else to provision.

• SurrealDB Docker image (surrealdb/surrealdb:v4)
• A Railway volume mounted at /data for the SurrealKV datastore

Deployment Dependencies

• SurrealDB documentation
• SurrealDB 4.0 release notes
• Surrealist, the SurrealDB GUI, for browsing and querying the database
• The latest SurrealDB SDK for your language. 4.0 refuses some value formats that older SDKs send, so upgrade the SDK before you connect.

Implementation Details

Connect with the generated variables:

• SURREAL_URL: public WebSocket endpoint (wss:///rpc)
• SURREAL_HTTP_URL: public HTTP endpoint
• SURREAL_PRIVATE_URL and SURREAL_HTTP_PRIVATE_URL: the same endpoints on the private network
• SURREAL_USER and SURREAL_PASS: the root user

The service name contains a dot, so quote it when you reference these from another service:

${{"SurrealDB 4.x (Latest)".SURREAL_PRIVATE_URL}}

A new instance starts with a main namespace and a main database.

Coming from the 3.x template? SurrealDB 4.0 refuses to start on a 3.x datastore, so switching the image on an existing 3.x service will crash it. Deploy this template next to it and move the data with surreal export from the 3.x instance and surreal import into this one. An in-place upgrade exists behind SURREAL_EXPERIMENTAL_UPGRADE_FROM_3X=true, but it is one-way, needs free space for a second copy of the data, and should only be run after a backup.

Why Deploy SurrealDB 4.x 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 4.x 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.