concepts

name	concepts
description	Understand SpacetimeDB architecture and core concepts. Use when learning SpacetimeDB or making architectural decisions.
license	Apache-2.0
metadata	{"author":"clockworklabs","version":"2.0","role":"shared","language":"all","cursor_globs":"**/*","cursor_always_apply":true}

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

1. Reducers are transactional. They do not return data to callers. Use subscriptions to read data.
2. Reducers must be deterministic. Do not use filesystem, network, external clocks, or external random sources in reducers. Use ReducerContext for SpacetimeDB-provided timestamp and deterministic random values.
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.

---

Feature Implementation Checklist

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
5. Client: Render the data from the table(s)

---

Debugging Checklist

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?

---

Tables

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

Organize data by access pattern, not by entity:

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

Reducers

Reducers are transactional functions that modify database state. They run atomically, cannot interact with the outside world, and do not return data to callers. See the language-specific server skills for syntax.

Event Tables

Event tables broadcast reducer-specific data to clients. Rows are never stored in the client cache (count() returns 0, iter() yields nothing); only onInsert callbacks fire.

Subscriptions

Subscriptions replicate database rows to clients in real-time.

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)

Best practices:

• Group subscriptions by lifetime
• Subscribe before unsubscribing when updating subscriptions
• Avoid overlapping queries
• Use indexes for efficient queries

Modules

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

• Tables: Define the data schema
• Reducers: Define callable functions that modify state
• Event Tables: Broadcast reducer-specific data to clients
• Views: Read-only functions that expose computed subsets of data to clients
• Procedures: (Unstable) Functions that can have side effects (HTTP requests, ctx.withTx)

Server-side modules can be written in: Rust, C#, TypeScript, C++

Lifecycle: Write → Compile → Publish (spacetime publish) → Hot-swap (republish without disconnecting clients)

Identity

• Identity: A long-lived, globally unique identifier for a user.
• ConnectionId: Identifies a specific client connection.
• Always use ctx.sender / ctx.Sender / ctx.sender() for authorization.

SpacetimeDB works with many OIDC providers, including SpacetimeAuth (built-in), Auth0, Clerk, Keycloak, Google, and GitHub.