/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 as modules, eliminating the traditional web/game server layer entirely. Rust, C#, and C++ modules compile to WebAssembly, while TypeScript modules run on V8.

---

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 the reducer context (`ctx`) 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 contain 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.