SpacetimeDB Documentation

File: README.md Copy Chapter

What is SpacetimeDB? Copy Chapter

SpacetimeDB is a relational database that is also a server. You upload your application logic directly into the database, and clients connect to it without any server in between.

Write your schema and business logic as a module in Rust, C#, TypeScript, or C++. SpacetimeDB compiles it, runs it inside the database, and automatically synchronizes state to connected clients in real-time.

Instead of deploying a web or game server that sits in between your clients and your database, your clients connect directly to the database and execute your application logic in your module. You can write all of your permission and authorization logic right inside your module just as you would in a normal server.

This means that you can write your entire application in a single language and deploy it as a single binary. No more separate webserver, no more containers, no more Kubernetes, no more VMs, no more DevOps, no more caching later. Zero infrastructure to manage.

<figcaption align="center">
    
</figcaption>

SpacetimeDB is optimized for maximum speed and minimum latency. SpacetimeDB provides all the ACID guarantees of a traditional RDBMS, with all the speed of an optimized web server. All application state is held in memory for fast access, while a commit log on disk provides durability and crash recovery. The entire backend of our MMORPG BitCraft Online runs as a single SpacetimeDB module: chat, items, terrain, player positions, everything, synchronized to thousands of players in real-time.

Quick Start Copy Chapter

1. Install Copy Section

# macOS / Linux
curl -sSf https://install.spacetimedb.com | sh

# Windows (PowerShell)
iwr https://windows.spacetimedb.com -useb | iex

2. Log in Copy Section

spacetime login

This opens a browser to authenticate with GitHub. Your identity is linked to your account so you can publish databases.

3. Start developing Copy Section

spacetime dev --template chat-react-ts

That is it. This creates a project from a template, publishes it to Maincloud, and watches for file changes, automatically rebuilding and republishing on save. See pricing for details.

How It Works Copy Chapter

SpacetimeDB modules define tables (your data) and reducers (your logic). Clients connect, call reducers, and subscribe to tables. When data changes, SpacetimeDB pushes updates to subscribed clients automatically.

// Define a table
#[spacetimedb::table(accessor = messages, public)]
pub struct Message {
    #[primary_key]
    #[auto_inc]
    id: u64,
    sender: Identity,
    text: String,
}

// Define a reducer (your API endpoint)
#[spacetimedb::reducer]
pub fn send_message(ctx: &ReducerContext, text: String) {
    ctx.db.messages().insert(Message {
        id: 0,
        sender: ctx.sender,
        text,
    });
}

On the client side, subscribe and get live updates:

const [messages] = useTable(tables.message);
// messages updates automatically when the server state changes.
// No polling. No refetching.

Language Support Copy Chapter

Server Modules Copy Section

Write your database logic in any of these languages:

Client SDKs Copy Section

Connect from any of these platforms:

Running with Docker Copy Chapter

docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start

Building from Source Copy Chapter

If you need features from master that have not been released yet:

# Prerequisites: Rust toolchain with wasm32-unknown-unknown target
curl https://sh.rustup.rs -sSf | sh

git clone https://github.com/clockworklabs/SpacetimeDB
cd SpacetimeDB
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli

Then install the binaries:

macOS / Linux

mkdir -p ~/.local/bin
STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION

cp target/release/spacetimedb-update ~/.local/bin/spacetime
cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION
cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION

# Add to your shell config if not already present:
export PATH="$HOME/.local/bin:$PATH"

# Set the active version:
spacetime version use $STDB_VERSION

Windows (PowerShell)

$stdbDir = "$HOME\AppData\Local\SpacetimeDB"
$stdbVersion = & ".\target\release\spacetimedb-cli" --version |
    Select-String -Pattern 'spacetimedb tool version ([0-9.]+);' |
    ForEach-Object { $_.Matches.Groups[1].Value }
New-Item -ItemType Directory -Path "$stdbDir\bin\$stdbVersion" -Force | Out-Null

Copy-Item "target\release\spacetimedb-update.exe" "$stdbDir\spacetime.exe"
Copy-Item "target\release\spacetimedb-cli.exe" "$stdbDir\bin\$stdbVersion\"
Copy-Item "target\release\spacetimedb-standalone.exe" "$stdbDir\bin\$stdbVersion\"

# Add to your system PATH: %USERPROFILE%\AppData\Local\SpacetimeDB
# Then in a new shell:
spacetime version use $stdbVersion

Verify with spacetime --version.

Documentation Copy Chapter

Full documentation is available at spacetimedb.com/docs, including:

• Quickstart guides for every supported language and framework
• Core concepts: tables, reducers, subscriptions, authentication
• Tutorials: chat app, Unity multiplayer, Unreal Engine multiplayer
• Deployment guide: publishing to Maincloud
• CLI reference
• SQL reference

License Copy Chapter

SpacetimeDB is licensed under the Business Source License 1.1 (BSL). It converts to the AGPL v3.0 with a linking exception after a few years. The linking exception means you are not required to open-source your own code if you use SpacetimeDB. You only need to contribute back changes to SpacetimeDB itself.

Why did we choose this license?
We chose to license SpacetimeDB under the MariaDB Business Source License for 4 years because we can't compete with AWS while also building our products for them.

We chose GPLv3 with linking exception as the open source license because we want contributions merged back into mainline (just like Linux), but we don't want to make anyone else open source their own code (i.e. linking exception).

File: crates/update/README.md Copy Chapter

⚠️ Internal Crate ⚠️

This crate is intended for internal use only. It is not stable and may change without notice.

File: crates/testing/README.md Copy Chapter

⚠️ Internal Crate ⚠️

This crate is intended for internal use only. It is not stable and may change without notice.

File: crates/table/README.md Copy Chapter

⚠️ Internal Crate ⚠️

This crate is intended for internal use only. It is not stable and may change without notice.

File: crates/subscription/README.md Copy Chapter

⚠️ Unstable Crate ⚠️

The interface of this crate is not stable and may change without notice.

File: crates/standalone/README.md Copy Chapter

⚠️ Unstable Crate ⚠️

The interface of this crate is not stable and may change without notice.

File: crates/sqltest/README.md Copy Chapter

This crate check the conformance of SpacetimeDB to SQL:2016

⚠️ Internal Crate ⚠️

This crate is intended for internal use only. It is not stable and may change without notice.

Setup PG

Create a database called TestSpace

Issues

List of issues in the execution of the conformance test

UNSUPPORTED: issue 1 Copy Chapter

CHARACTERS/OCTETS is not implemented by neither PG nor Sqlite

CREATE TABLE TABLE_E021_01_01_02 ( A CHAR ( 8 CHARACTERS ) )
CREATE TABLE TABLE_E021_01_01_02 ( A CHAR ( 8 OCTETS ) )

UNSUPPORTED: issue 2 Copy Chapter

CHAR VARING is not implemented by neither PG nor Sqlite

CREATE TABLE TABLE_E021_02_01_02 ( A CHAR VARING ( 8 CHARACTERS ) )

UNSUPPORTED: issue 3 Copy Chapter

AS ( C , D ) is a syntax error on PG and Sqlite

SELECT * AS ( C , D ) FROM TABLE_E051_07_01_01

REPLACED: issue 4 Copy Chapter

CURRENT_TIME and timetz type is marked as "Don't use EVER" by PG:
https://wiki.postgresql.org/wiki/Don%27t_Do_This#Don.27t_use_timetz

SELECT CURRENT_TIME

UNSUPPORTED: issue 5 Copy Chapter

CASE 0 WHEN 2 , 2 is a syntax error on PG and Sqlite

SELECT CASE 0 WHEN 2 , 2 THEN 1 END

WRONG: issue 6 Copy Chapter

This expression fail in PG by the lack of a timezone and Sqlite spit out a nonsensical value (1)

SELECT CAST ( CAST ( '01:02:03' AS TIME ) AS TIMESTAMP )

File: crates/snapshot/README.md Copy Chapter

⚠️ Internal Crate ⚠️

This crate is intended for internal use only. It is not stable and may change without notice.