douglance/spacetimedb/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.

1. 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.

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

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

1. 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)