concepts

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