Spacetimedb Concepts

SpacetimeDB Core Concepts

SpacetimeDB is a relational database that is also a server. It lets you upload application logic directly into the database via WebAssembly modules, eliminating the traditional web/game server layer entirely.

Critical Rules (Read First)

These five rules prevent the most common SpacetimeDB mistakes:

1. Reducers are transactional — they do not return data to callers. Use subscriptions to read data.
2. Reducers must be deterministic — no filesystem, network, timers, or random. All state must come from tables.
3. Read data via tables/subscriptions — not reducer return values. Clients get data through subscribed queries.
4. Auto-increment IDs are not sequential — gaps are normal, do not use for ordering. Use timestamps or explicit sequence columns.
5. ctx.sender is the authenticated principal — never trust identity passed as arguments. Always use ctx.sender for authorization.

Feature Implementation Checklist

When implementing a feature that spans backend and client:

1. Backend: Define table(s) to store the data
2. Backend: Define reducer(s) to mutate the data
3. Client: Subscribe to the table(s)
4. Client: Call the reducer(s) from UI — do not skip this step
5. Client: Render the data from the table(s)

Common mistake: Building backend tables/reducers but forgetting to wire up the client to call them.

Debugging Checklist

When things are not working:

1. Is SpacetimeDB server running? (spacetime start)
2. Is the module published? (spacetime publish)
3. Are client bindings generated? (spacetime generate)
4. Check server logs for errors (spacetime logs <db-name>)
5. Is the reducer actually being called from the client?

CLI Commands

# Start local SpacetimeDB
spacetime start

# Publish module
spacetime publish <db-name> --project-path <module-path>

# Clear and republish
spacetime publish <db-name> --clear-database -y --project-path <module-path>

# Generate client bindings
spacetime generate --lang <lang> --out-dir <out> --project-path <module-path>

# View logs
spacetime logs <db-name>

What SpacetimeDB Is

SpacetimeDB combines a database and application server into a single deployable unit. Clients connect directly to the database and execute application logic inside it. The system is optimized for real-time applications requiring maximum speed and minimum latency.

Key characteristics:

• In-memory execution: All application state lives in memory for sub-millisecond access
• Persistent storage: Data is automatically persisted to a write-ahead log (WAL) for durability
• Real-time synchronization: Changes are automatically pushed to subscribed clients
• Single deployment: No separate servers, containers, or infrastructure to manage

SpacetimeDB powers BitCraft Online, an MMORPG where the entire game backend (chat, items, resources, terrain, player positions) runs as a single SpacetimeDB module.

The Five Zen Principles

SpacetimeDB is built on five core principles that guide both development and usage:

1. Everything is a Table: Your entire application state lives in tables. No separate cache layer, no Redis, no in-memory state to synchronize. The database IS your state.

2. Everything is Persistent: SpacetimeDB persists everything by default, including full history. Persistence only increases latency, never decreases throughput. Modern SSDs can write 15+ GB/s.

3. Everything is Real-Time: Clients are replicas of server state. Subscribe to data and it flows automatically. No polling, no fetching.

4. Everything is Transactional: Every reducer runs atomically. Either all changes succeed or all roll back. No partial updates, no corrupted state.

5. Everything is Programmable: Modules are real code (Rust, C#, TypeScript) running inside the database. Full Turing-complete power for any logic.

Tables

Tables store all data in SpacetimeDB. They use the relational model and support SQL queries for subscriptions.

Defining Tables

Tables are defined using language-specific attributes:

Rust:

#[spacetimedb::table(name = player, public)]
pub struct Player {
    #[primary_key]
    #[auto_inc]
    id: u32,
    #[index(btree)]
    name: String,
    #[unique]
    email: String,
}

C#:

[SpacetimeDB.Table(Name = "Player", Public = true)]
public partial struct Player
{
    [SpacetimeDB.PrimaryKey]
    [SpacetimeDB.AutoInc]
    public uint Id;
    [SpacetimeDB.Index.BTree]
    public string Name;
    [SpacetimeDB.Unique]
    public string Email;
}

TypeScript:

const players = table(
  { name: 'players', public: true },
  {
    id: t.u32().primaryKey().autoInc(),
    name: t.string().index('btree'),
    email: t.string().unique(),
  }
);

Table Visibility

• Private tables (default): Only accessible by reducers and the database owner
• Public tables: Exposed for client read access through subscriptions. Writes still require reducers.

Table Design Principles

Organize data by access pattern, not by entity:

Decomposed approach (recommended):

Player          PlayerState         PlayerStats
id         <--  player_id           player_id
name            position_x          total_kills
                position_y          total_deaths
                velocity_x          play_time
                velocity_y

Benefits:

• Reduced bandwidth (clients subscribing to positions do not receive settings updates)
• Cache efficiency (similar update frequencies in contiguous memory)
• Schema evolution (add columns without affecting other tables)
• Semantic clarity (each table has single responsibility)

Reducers

Reducers are transactional functions that modify database state. They are the ONLY way to mutate tables in SpacetimeDB.

Key Properties

• Transactional: Run in isolated database transactions
• Atomic: Either all changes succeed or all roll back
• Isolated: Cannot interact with the outside world (no network, no filesystem)
• Callable: Clients invoke reducers as remote procedure calls

Critical Reducer Rules

1. No global state: Relying on static variables is undefined behavior
2. No side effects: Reducers cannot make network requests or access files
3. Store state in tables: All persistent state must be in tables
4. No return data: Reducers do not return data to callers — use subscriptions
5. Must be deterministic: No random, no timers, no external I/O

Defining Reducers

Rust:

#[spacetimedb::reducer]
pub fn create_user(ctx: &ReducerContext, name: String, email: String) -> Result<(), String> {
    if name.is_empty() {
        return Err("Name cannot be empty".to_string());
    }
    ctx.db.user().insert(User { id: 0, name, email });
    Ok(())
}

C#:

[SpacetimeDB.Reducer]
public static void CreateUser(ReducerContext ctx, string name, string email)
{
    if (string.IsNullOrEmpty(name))
        throw new ArgumentException("Name cannot be empty");
    ctx.Db.User.Insert(new User { Id = 0, Name = name, Email = email });
}

ReducerContext

Every reducer receives a ReducerContext providing:

• ctx.db: Access to all tables (read and write)
• ctx.sender: The Identity of the caller (use this for authorization, never trust args)
• ctx.connection_id: The connection ID of the caller
• ctx.timestamp: The current timestamp

Subscriptions

Subscriptions replicate database rows to clients in real-time. When you subscribe to a query, SpacetimeDB sends matching rows immediately and pushes updates whenever those rows change.

How Subscriptions Work

1. Subscribe: Register SQL queries describing needed data
2. Receive initial data: All matching rows are sent immediately
3. Receive updates: Real-time updates when subscribed rows change
4. React to changes: Use callbacks (onInsert, onDelete, onUpdate) to handle changes

Client-Side Usage

TypeScript:

const conn = DbConnection.builder()
  .withUri('wss://maincloud.spacetimedb.com')
  .withModuleName('my_module')
  .onConnect((ctx) => {
    ctx.subscriptionBuilder()
      .onApplied(() => console.log('Subscription ready!'))
      .subscribe(['SELECT * FROM user', 'SELECT * FROM message']);
  })
  .build();

// React to changes
conn.db.user.onInsert((ctx, user) => console.log(`New user: ${user.name}`));
conn.db.user.onDelete((ctx, user) => console.log(`User left: ${user.name}`));
conn.db.user.onUpdate((ctx, old, new_) => console.log(`${old.name} -> ${new_.name}`));

Subscription Best Practices

1. Group subscriptions by lifetime: Keep always-needed data separate from temporary subscriptions
2. Subscribe before unsubscribing: When updating subscriptions, subscribe to new data first
3. Avoid overlapping queries: Distinct queries returning overlapping data cause redundant processing
4. Use indexes: Queries on indexed columns are efficient; full table scans are expensive

Modules

Modules are WebAssembly bundles containing application logic that runs inside the database.

Module Components

• Tables: Define the data schema
• Reducers: Define callable functions that modify state
• Views: Define read-only computed queries
• Procedures: (Beta) Functions that can have side effects (HTTP requests)

Module Languages

Server-side modules can be written in:

• Rust
• C#
• TypeScript (beta)

Module Lifecycle

1. Write: Define tables and reducers in your chosen language
2. Compile: Build to WebAssembly using the SpacetimeDB CLI
3. Publish: Upload to a SpacetimeDB host with spacetime publish
4. Hot-swap: Republish to update code without disconnecting clients

Identity

Identity is SpacetimeDB's authentication system based on OpenID Connect (OIDC).

Identity Concepts

• Identity: A long-lived, globally unique identifier for a user. Derived from OIDC issuer and subject claims.
• ConnectionId: Identifies a specific client connection. A user may have multiple connections.

Identity in Reducers

#[spacetimedb::reducer]
pub fn do_something(ctx: &ReducerContext) {
    let caller_identity = ctx.sender;  // Who is calling this reducer?
    // Use identity for authorization checks
    // NEVER trust identity passed as a reducer argument
}

Authentication Providers

SpacetimeDB works with any OIDC provider:

• SpacetimeAuth: Built-in managed provider (simple, production-ready)
• Third-party: Auth0, Clerk, Keycloak, Google, GitHub, etc.

SATS (SpacetimeDB Algebraic Type System)

SATS is the type system and serialization format used throughout SpacetimeDB.

Core Types

Serialization Formats

• BSATN: Binary format for module-host communication and row storage
• SATS-JSON: JSON format for HTTP API and WebSocket text protocol

Type Compatibility

Types must implement SpacetimeType to be used in tables and reducers. This is automatic for primitive types and structs using the appropriate attributes.

Client-Server Data Flow

Write Path (Client to Database)

1. Client calls reducer (e.g., ctx.reducers.createUser("Alice"))
2. Request sent over WebSocket to SpacetimeDB host
3. Host validates identity and executes reducer in transaction
4. On success, changes are committed; on error, all changes roll back
5. Subscribed clients receive updates for affected rows

Read Path (Database to Client)

1. Client subscribes with SQL queries (e.g., SELECT * FROM user)
2. Server evaluates query and sends matching rows
3. Client maintains local cache of subscribed data
4. When subscribed data changes, server pushes delta updates
5. Client cache is automatically updated; callbacks fire

Data Flow Diagram

┌─────────────────────────────────────────────────────────┐
│                        CLIENT                           │
│  ┌─────────────┐     ┌─────────────────────────────┐   │
│  │  Reducers   │────>│     Local Cache (Read)      │   │
│  │  (Write)    │     │  - Tables from subscriptions│   │
│  └─────────────┘     │  - Automatically synced     │   │
│         │            └─────────────────────────────┘   │
└─────────│──────────────────────────│───────────────────┘
          │ WebSocket                │ Updates pushed
          v                          │
┌─────────────────────────────────────────────────────────┐
│                     SpacetimeDB                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │                    Module                        │   │
│  │  - Reducers (transactional logic)               │   │
│  │  - Tables (in-memory + persisted)               │   │
│  │  - Subscriptions (real-time queries)            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

When to Use SpacetimeDB

Ideal Use Cases

• Real-time games: MMOs, multiplayer games, turn-based games
• Collaborative applications: Document editing, whiteboards, design tools
• Chat and messaging: Real-time communication with presence
• Live dashboards: Streaming analytics and monitoring
• IoT applications: Sensor data with real-time updates

Key Decision Factors

Choose SpacetimeDB when you need:

• Sub-10ms latency for reads and writes
• Automatic real-time synchronization
• Transactional guarantees for all operations
• Simplified architecture (no separate cache, queue, or server)

Less Suitable For

• Batch analytics: SpacetimeDB is optimized for OLTP, not OLAP
• Large blob storage: Better suited for structured relational data
• Stateless APIs: Traditional REST APIs do not need real-time sync

Comparison to Traditional Architectures

Traditional Stack

Client
   │
   v
Load Balancer
   │
   v
Web/Game Servers (stateless or stateful)
   │
   ├──> Cache (Redis)
   │
   v
Database (PostgreSQL, MySQL)
   │
   v
Message Queue (for real-time)

Pain points:

• Multiple systems to deploy and manage
• Cache invalidation complexity
• State synchronization between servers
• Manual real-time implementation
• Horizontal scaling complexity

SpacetimeDB Stack

Client
   │
   v
SpacetimeDB Host
   │
   v
Module (your logic + tables)

Benefits:

• Single deployment target
• No cache layer needed (in-memory by design)
• Automatic real-time synchronization
• Built-in horizontal scaling (future)
• Transactional guarantees everywhere

Smart Contract Comparison

SpacetimeDB modules are conceptually similar to smart contracts:

• Application logic runs inside the data layer
• Transactions are atomic and verified
• State changes are deterministic

Key differences:

• SpacetimeDB is orders of magnitude faster (no consensus overhead)
• Full relational database capabilities
• No blockchain or cryptocurrency involved
• Designed for real-time, not eventual consistency

Common Patterns

Authentication check in reducer:

#[spacetimedb::reducer]
fn admin_action(ctx: &ReducerContext) -> Result<(), String> {
    let admin = ctx.db.admin().identity().find(&ctx.sender)
        .ok_or("Not an admin")?;
    // ... perform admin action
    Ok(())
}

Moving between tables (state machine):

#[spacetimedb::reducer]
fn login(ctx: &ReducerContext) -> Result<(), String> {
    let player = ctx.db.logged_out_player().identity().find(&ctx.sender)
        .ok_or("Not found")?;
    ctx.db.player().insert(player.clone());
    ctx.db.logged_out_player().identity().delete(&ctx.sender);
    Ok(())
}

Scheduled reducer:

#[spacetimedb::table(name = reminder, scheduled(send_reminder))]
pub struct Reminder {
    #[primary_key]
    #[auto_inc]
    id: u64,
    scheduled_at: ScheduleAt,
    message: String,
}

#[spacetimedb::reducer]
fn send_reminder(ctx: &ReducerContext, reminder: Reminder) {
    // This runs at the scheduled time
    log::info!("Reminder: {}", reminder.message);
}

Editing Behavior

When modifying SpacetimeDB code:

• Make the smallest change necessary
• Do NOT touch unrelated files, configs, or dependencies
• Do NOT invent new SpacetimeDB APIs — use only what exists in docs or this repo