SpacetimeDB Documentation
Installation
You can run SpacetimeDB as a standalone database server via the spacetime CLI tool.
You can find the instructions to install the CLI tool for your platform here.
To get started running your own standalone instance of SpacetimeDB check out our Getting Started Guide.
What is SpacetimeDB?
SpacetimeDB is a database that is also a server.
SpacetimeDB is a full-featured relational database system that lets you run your application logic inside the database. You no longer need to deploy a separate web or game server. Several programming languages are supported, including C# and Rust. You can still write authorization logic, just like you would in a traditional server.
This means that you can write your entire application in a single language and deploy it as a single binary. No more microservices, no more containers, no more Kubernetes, no more Docker, no more VMs, no more DevOps, no more infrastructure, no more ops, no more servers.
This is similar to "smart contracts", except that SpacetimeDB is a database and has nothing to do with blockchain. Because it isn't a blockchain, it can be dramatically faster than many "smart contract" systems.
In fact, it's so fast that we've been able to write the entire backend of our MMORPG BitCraft Online as a single SpacetimeDB database. Everything in the game -- chat messages, items, resources, terrain, and player locations -- is stored and processed by the database. SpacetimeDB automatically mirrors relevant state to connected players in real-time.
SpacetimeDB is optimized for maximum speed and minimum latency, rather than batch processing or analytical workloads. It is designed for real-time applications like games, chat, and collaboration tools.
Speed and latency is achieved by holding all of your application state in memory, while persisting data to a commit log which is used to recover data after restarts and system crashes.
State Mirroring
SpacetimeDB can generate client code in a variety of languages. This creates a client library custom-designed to talk to your database. It provides easy-to-use interfaces for connecting to the database and submitting requests. It can also automatically mirror state from your database to client applications.
You write SQL queries specifying what information a client is interested in -- for instance, the terrain and items near a player's avatar. SpacetimeDB will generate types in your client language for the relevant tables, and feed clients a stream of live updates whenever the database state changes. Note that this is a read-only mirror -- the only way to change the database is to submit requests, which are validated on the server.
Language Support
Module Libraries
Every SpacetimeDB database contains a collection of stored procedures called a module. Modules can be written in C# or Rust. They specify a database schema and the business logic that responds to client requests. Modules are administered using the spacetime CLI tool.
Client-side SDKs
Clients are applications that connect to SpacetimeDB databases. The spacetime CLI tool supports automatically generating interface code that makes it easy to interact with a particular database.
Unity
SpacetimeDB was designed first and foremost as the backend for multiplayer Unity games. To learn more about using SpacetimeDB with Unity, jump on over to the SpacetimeDB Unity Tutorial.
Key architectural concepts
Host
A SpacetimeDB host is a server that hosts databases. You can run your own host, or use the SpacetimeDB maincloud. Many databases can run on a single host.
Database
A SpacetimeDB database is an application that runs on a host.
A database exports tables, which store data, and reducers, which allow clients to make requests.
A database's schema and business logic is specified by a piece of software called a module. Modules can be written in C# or Rust.
(Technically, a SpacetimeDB module is a WebAssembly module that imports a specific low-level WebAssembly ABI and exports a small number of special functions. However, the SpacetimeDB server-side libraries hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a special CLI tool is used to deploy the application.)
Table
A SpacetimeDB table is a SQL database table. Tables are declared in a module's native language. For instance, in C#, a table is declared like so:
[SpacetimeDB.Table(Name = "players", Public = true)]
public partial struct Player
{
[SpacetimeDB.PrimaryKey]
uint playerId;
string name;
uint age;
Identity user;
} The contents of a table can be read and updated by reducers.
Tables marked public can also be read by clients.
Reducer
A reducer is a function exported by a database. Connected clients can call reducers to interact with the database. This is a form of remote procedure call. A reducer can be written in C# like so:
[SpacetimeDB.Reducer]
public static void SetPlayerName(ReducerContext ctx, uint playerId, string name)
{
// ...
} And a C# client can call that reducer:
void Main() {
// ...setup code, then...
Connection.Reducer.SetPlayerName(57, "Marceline");
} These look mostly like regular function calls, but under the hood, the client sends a request over the internet, which the database processes and responds to.
The ReducerContext passed into a reducer includes information about the caller's identity and address. The database can reject any request it doesn't approve of.
Client
A client is an application that connects to a database. A client logs in using an identity and receives an address to identify the connection. After that, it can call reducers and query public tables.
Clients are written using the client-side SDKs. The spacetime CLI tool allows automatically generating code that works with the client-side SDKs to talk to a particular database.
Clients are regular software applications that developers can choose how to deploy (through Steam, app stores, package managers, or any other software deployment method, depending on the needs of the application.)
Identity
A SpacetimeDB Identity identifies someone interacting with a module. It is a long lived, public, globally valid identifier that will always refer to the same end user, even across different connections.
A user's Identity is attached to every reducer call they make, and you can use this to decide what they are allowed to do.
Modules themselves also have Identities. When you spacetime publish a module, it will automatically be issued an Identity to distinguish it from other modules. Your client application will need to provide this Identity when connecting to the host.
Identities are issued using the OpenID Connect specification. Database developers are responsible for issuing Identities to their end users. OpenID Connect lets users log in to these accounts through standard services like Google and Facebook.
Address
An Address identifies client connections to a SpacetimeDB module.
A user has a single Identity, but may open multiple connections to your module. Each of these will receive a unique Address.
Energy
Energy is the currency used to pay for data storage and compute operations in a SpacetimeDB host.
FAQ
What is SpacetimeDB? It's a cloud platform within a database that's fast enough to run real-time games.
How do I use SpacetimeDB? Install the
spacetimecommand line tool, choose your favorite language, import the SpacetimeDB library, write your module, compile it to WebAssembly, and upload it to the SpacetimeDB cloud platform. Once it's uploaded you can call functions directly on your application and subscribe to changes in application state.How do I get/install SpacetimeDB? Just install our command line tool and then upload your application to the cloud.
How do I create a new database with SpacetimeDB? Follow our Quick Start guide!
How do I create a Unity game with SpacetimeDB? Follow our Unity Tutorial guide!