From 7288b331fe90202b1dea671ea9f4c7f0e45ae6b1 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 21:53:03 -0500 Subject: [PATCH 1/6] Expand FAQ for 2.0 launch Comprehensive FAQ covering: - General questions (what is SpacetimeDB, is it only for games, licensing) - Comparisons (vs Mirror/Photon, vs Firebase/Supabase, vs Postgres) - Architecture (persistence, real-time sync, reducers, modules) - Development (getting started, spacetime dev, Unity/Unreal/React) - Deployment (production, hot-swapping, migrations) - Troubleshooting (common errors) --- .../00100-getting-started/00500-faq.md | 212 +++++++++++++++++- 1 file changed, 202 insertions(+), 10 deletions(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index 91eae1d188a..8b84feb6cab 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -3,18 +3,210 @@ title: FAQ slug: /intro/faq --- +## General -1. What is SpacetimeDB? - It's a cloud platform within a database that's fast enough to run real-time applications. +### What is SpacetimeDB? -1. How do I use SpacetimeDB? - Install the `spacetime` command line tool, choose your favorite language, import the SpacetimeDB library, write your module, compile it to WebAssembly, and upload it to the SpacetimeDB cloud platform. Once it's uploaded you can call functions directly on your application and subscribe to changes in application state. +SpacetimeDB is a database that is also a server. You upload your application logic (called a "module") directly into the database, and clients connect to it without any server in between. It's a relational database with tables, queries, and transactions — but your business logic runs inside it as stored procedures on steroids. -1. How do I get/install SpacetimeDB? - Just install our command line tool and then upload your application to the cloud. +### How is SpacetimeDB different from a traditional backend? -1. How do I create a new database with SpacetimeDB? - Follow our [Quick Start](/) guide! +In a traditional stack, you deploy a web server (Node, Django, Rails, etc.) that sits between your clients and your database. You write API endpoints, manage connection pooling, handle caching, and deploy infrastructure. -1. How do I create a Unity game with SpacetimeDB? - Follow our [Unity Tutorial](/docs/tutorials/unity) guide! \ No newline at end of file +With SpacetimeDB, you skip all of that. Your module *is* the backend. Clients connect directly to the database, call reducers (like RPC endpoints), and subscribe to real-time data updates. No separate server, no REST API, no GraphQL layer. + +``` +Traditional: SpacetimeDB: +Client → Server → Database Client → SpacetimeDB (database + logic) +``` + +### Is SpacetimeDB only for games? + +No. SpacetimeDB is designed for any real-time application: games, chat apps, collaboration tools, dashboards, IoT, or anything that benefits from low-latency state synchronization. Games are a demanding use case that proves SpacetimeDB's performance — our own MMORPG [BitCraft Online](https://bitcraftonline.com) runs entirely on SpacetimeDB — but the same architecture works for any application. + +### Is SpacetimeDB a blockchain / smart contract platform? + +No. SpacetimeDB has nothing to do with blockchain. The concept is similar to smart contracts in that your logic runs inside the database, but SpacetimeDB is a centralized relational database optimized for speed. It's orders of magnitude faster than any smart contract system. + +### Is SpacetimeDB open source? + +SpacetimeDB is source-available under the [Business Source License 1.1 (BSL)](https://github.com/clockworklabs/SpacetimeDB/blob/master/LICENSE.txt). It converts to the AGPL v3.0 (with a linking exception) after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB — you only need to contribute back changes to SpacetimeDB itself. + +### Can I self-host SpacetimeDB? + +Yes. You can run SpacetimeDB on your own infrastructure using `spacetime start`, or with Docker: + +```bash +docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start +``` + +You can also use the hosted SpacetimeDB cloud (maincloud) at no cost during the current beta period. + +--- + +## How does SpacetimeDB compare to... + +### How is SpacetimeDB different from Mirror / Netcode / Photon / other networking libraries? + +Networking libraries like Mirror, Netcode for GameObjects, and Photon handle the transport layer — sending messages between clients and a server you build and deploy yourself. You're still responsible for writing server logic, managing state, handling persistence, and deploying infrastructure. + +SpacetimeDB replaces the entire server. Your game state lives in tables, your game logic lives in reducers, and SpacetimeDB automatically synchronizes state to clients in real-time. You don't write networking code, serialization code, or deploy servers. + +| | Networking Libraries | SpacetimeDB | +|---|---|---| +| **Server logic** | You write and deploy it | Runs inside the database | +| **State management** | You manage it | Tables with auto-sync | +| **Persistence** | You add a database | Built in | +| **Real-time sync** | You implement it | Automatic via subscriptions | +| **Infrastructure** | You deploy and scale it | Managed or self-hosted | + +### How is SpacetimeDB different from Firebase / Supabase? + +Firebase and Supabase are Backend-as-a-Service platforms. They give you a database with an API layer on top, but your application logic still runs elsewhere (cloud functions, edge functions, or your own server). Complex business logic is awkward to express as database triggers or serverless functions. + +SpacetimeDB lets you write your entire application as a module in a real programming language (Rust, C#, TypeScript) that runs inside the database. You get full transactional guarantees, direct table access, and real-time subscriptions — without the cold starts, execution limits, or awkward abstractions of serverless functions. + +### How is SpacetimeDB different from a regular database (PostgreSQL, MySQL)? + +A traditional database stores data and lets you query it. Your application logic runs in a separate server that connects to the database over the network. + +SpacetimeDB holds all data in memory for sub-millisecond access, runs your application logic inside the database as WebAssembly modules, and pushes real-time updates to connected clients automatically. It's purpose-built for real-time applications, not batch processing or analytics. + +--- + +## Architecture + +### How does data persistence work? + +SpacetimeDB holds all data in memory for fast access, but persists everything to a commit log (similar to a write-ahead log). On restart, the database replays the commit log to recover its exact state. You get the speed of in-memory computing with the durability of a traditional database. + +### How does real-time sync work? + +Clients subscribe to SQL queries that specify what data they care about. SpacetimeDB evaluates these subscriptions and pushes incremental updates whenever the underlying data changes. On the client side, the SDK maintains a local cache that mirrors the server state — you query this cache directly with no round trips. + +```typescript +// Client subscribes to nearby players +ctx.subscribe("SELECT * FROM players WHERE distance(x, y, ?, ?) < 100", myX, myY); + +// The local cache updates automatically +const nearbyPlayers = ctx.db.players; +``` + +### Are reducers like REST endpoints? + +Reducers are more like transactional RPC calls. A client calls a reducer by name with arguments, the reducer runs inside a database transaction, and either all changes commit or none do. Unlike REST, there's no HTTP overhead, no JSON serialization, and no need to design URL routes. Clients call reducers through auto-generated, type-safe bindings. + +### What happens if a reducer fails? + +The entire transaction rolls back. No partial updates, no corrupted state. The database remains exactly as it was before the reducer was called. You can throw errors or return `Err` freely — SpacetimeDB handles the cleanup. + +### What languages can I write modules in? + +Server-side modules can be written in: +- **Rust** +- **C#** +- **TypeScript** (new in 2.0) +- **C++** (new in 2.0) + +Client SDKs are available for: +- **Rust** +- **C#** (including Unity) +- **TypeScript** (including React, Vue, Svelte, Angular, and more) +- **C++** (Unreal Engine) + +### What is a "module"? + +A module is your application's server-side code compiled to WebAssembly (or bundled as JavaScript for TypeScript modules). It defines your tables, reducers, views, and procedures. You upload it to SpacetimeDB with `spacetime publish`, and it runs inside the database. Think of it as your entire backend in a single deployable unit. + +--- + +## Development + +### How do I get started? + +1. Install the CLI: `curl -sSf https://install.spacetimedb.com | sh` +2. Start a local instance: `spacetime start` +3. Create a project: `spacetime init --lang rust` (or `csharp`, `typescript`) +4. Write your module, publish it: `spacetime publish my-app` +5. Generate client bindings: `spacetime generate --lang typescript --out-dir src/module_bindings` +6. Connect from your client using the generated code + +See the [quickstart guides](/quickstart) for step-by-step tutorials. + +### What is `spacetime dev`? + +`spacetime dev` is the development workflow command. It watches your module for changes, automatically rebuilds and republishes it, generates client bindings, and optionally starts your client dev server. It's like `npm run dev` but for your entire full-stack application. + +### Do I need to write SQL? + +Only for client-side subscriptions (telling the client what data to sync). Your server-side module code uses native language APIs to query and modify tables — no SQL needed on the server side. + +### Can I use SpacetimeDB with Unity? + +Yes. SpacetimeDB has a C# client SDK that works with Unity. The SDK maintains a local cache of your subscribed data and provides callbacks for changes. See the [Unity tutorial](/tutorials/unity) for a complete walkthrough. + +### Can I use SpacetimeDB with Unreal Engine? + +Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. See the [Unreal quickstart](/quickstart/unreal) for details. + +### Can I use SpacetimeDB with React / Vue / Angular / Svelte? + +Yes. The TypeScript SDK includes framework-specific integrations for React, Vue, Angular, Svelte, and more. These provide reactive hooks/composables that automatically update your UI when database state changes. + +### How do I handle authentication? + +SpacetimeDB uses the [OpenID Connect](https://openid.net/developers/how-connect-works/) standard. You can use SpacetimeDB's built-in auth provider (SpacetimeAuth), or integrate with any OpenID Connect provider (Google, Auth0, etc.). Every reducer call includes the caller's `Identity`, which you can use for authorization logic. + +### What are Views? + +Views are read-only functions that compute derived data from your tables. They're like SQL views but written in your module's language. Clients can subscribe to views just like tables, and they update automatically when the underlying data changes. + +### What are Procedures? + +Procedures are like reducers but with additional capabilities — they can make HTTP requests to external services and manually manage transactions. They're currently in beta. Use reducers for most use cases; use procedures when you need to interact with the outside world. + +--- + +## Deployment & Operations + +### How do I deploy to production? + +You can deploy to the SpacetimeDB cloud (maincloud) with: + +```bash +spacetime publish my-app --server maincloud +``` + +Or self-host SpacetimeDB and publish to your own server. + +### Can I update my module without downtime? + +Yes. When you `spacetime publish` an update, SpacetimeDB hot-swaps the module code. Connected clients are **not** disconnected — they seamlessly continue with the new logic. This is possible because all state lives in tables, not in the server process. + +### How do I handle schema migrations? + +When you publish an updated module, SpacetimeDB compares the new schema with the existing one and performs automatic migrations for compatible changes (adding tables, adding columns with defaults, etc.). For breaking changes, you may need to publish with `--delete-data` during development or implement manual migration logic in your `init` reducer. + +### Is there a size limit for databases? + +SpacetimeDB holds all data in memory, so the practical limit is the available RAM on the host. On the hosted cloud, resource limits depend on your plan. For self-hosted deployments, you control the hardware. + +### How much does SpacetimeDB cost? + +SpacetimeDB is free to use during the current beta period, including the hosted cloud. Pricing for production workloads will be announced separately. + +--- + +## Troubleshooting + +### I'm getting a 401/403 when publishing — what's wrong? + +Database names are **global** on maincloud. If someone else already published a database with that name, you'll get an authorization error. Try a more unique name. + +### My `spacetime generate` command gives a confusing error + +If your module's `init` reducer panics (e.g., due to a unique constraint violation), `spacetime generate` may show an unhelpful error like `EOF while parsing a value`. Fix the runtime error in your module first, then generate again. + +### How do I reset my database during development? + +Use `spacetime publish my-app --delete-data` to clear all data and republish. Or use `spacetime dev` which handles this automatically with the `--delete-data=on-conflict` flag. From cc587e77771f3537a649cf9cb6c24928fdbe13ce Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:11:20 -0500 Subject: [PATCH 2/6] docs: address review feedback on FAQ - Remove blockchain/smart-contract section - Fix subscription syntax to use correct API (subscriptionBuilder) - Fix performance claim (sub-microsecond + 100-1000x faster) - Add type-safe query builder mentions - Note HTTP calling for procedures - Group tables/reducers/views/procedures into Core Concepts section - Add Maincloud details with link to pricing page - Replace all emdashes with standard punctuation - Write in textbook style throughout New sections added per review: - Authentication & Authorization (OIDC, Identity as user ID, password storage warning, localhost identity creation, identity-filtered subscriptions) - Schema & Migrations (add/remove columns, add tables, indexes, incremental migration pattern) - Room/match-based game architecture - Hot-swap publishing and clearing databases - Version mismatch troubleshooting (module lib, client SDK, pre-1.0 upgrades) --- .../00100-getting-started/00500-faq.md | 179 +++++++++++++----- 1 file changed, 136 insertions(+), 43 deletions(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index 8b84feb6cab..4693fa4e220 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -7,13 +7,13 @@ slug: /intro/faq ### What is SpacetimeDB? -SpacetimeDB is a database that is also a server. You upload your application logic (called a "module") directly into the database, and clients connect to it without any server in between. It's a relational database with tables, queries, and transactions — but your business logic runs inside it as stored procedures on steroids. +SpacetimeDB is a database that is also a server. You upload your application logic (called a "module") directly into the database, and clients connect to it without any server in between. It is a relational database with tables, queries, and transactions, but your business logic runs inside it as stored procedures on steroids. ### How is SpacetimeDB different from a traditional backend? In a traditional stack, you deploy a web server (Node, Django, Rails, etc.) that sits between your clients and your database. You write API endpoints, manage connection pooling, handle caching, and deploy infrastructure. -With SpacetimeDB, you skip all of that. Your module *is* the backend. Clients connect directly to the database, call reducers (like RPC endpoints), and subscribe to real-time data updates. No separate server, no REST API, no GraphQL layer. +With SpacetimeDB, you skip all of that. Your module is the backend. Clients connect directly to the database, call reducers (like RPC endpoints), and subscribe to real-time data updates. No separate server, no REST API, no GraphQL layer. ``` Traditional: SpacetimeDB: @@ -22,15 +22,11 @@ Client → Server → Database Client → SpacetimeDB (database + logic) ### Is SpacetimeDB only for games? -No. SpacetimeDB is designed for any real-time application: games, chat apps, collaboration tools, dashboards, IoT, or anything that benefits from low-latency state synchronization. Games are a demanding use case that proves SpacetimeDB's performance — our own MMORPG [BitCraft Online](https://bitcraftonline.com) runs entirely on SpacetimeDB — but the same architecture works for any application. - -### Is SpacetimeDB a blockchain / smart contract platform? - -No. SpacetimeDB has nothing to do with blockchain. The concept is similar to smart contracts in that your logic runs inside the database, but SpacetimeDB is a centralized relational database optimized for speed. It's orders of magnitude faster than any smart contract system. +No. SpacetimeDB is designed for any real-time application: games, chat apps, collaboration tools, dashboards, IoT, or anything that benefits from low-latency state synchronization. Games are a demanding use case that proves SpacetimeDB's performance. Our own MMORPG [BitCraft Online](https://bitcraftonline.com) runs entirely on SpacetimeDB. The same architecture works for any application. ### Is SpacetimeDB open source? -SpacetimeDB is source-available under the [Business Source License 1.1 (BSL)](https://github.com/clockworklabs/SpacetimeDB/blob/master/LICENSE.txt). It converts to the AGPL v3.0 (with a linking exception) after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB — you only need to contribute back changes to SpacetimeDB itself. +SpacetimeDB is source-available under the [Business Source License 1.1 (BSL)](https://github.com/clockworklabs/SpacetimeDB/blob/master/LICENSE.txt). It converts to the AGPL v3.0 (with a linking exception) after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB. You only need to contribute back changes to SpacetimeDB itself. ### Can I self-host SpacetimeDB? @@ -40,7 +36,7 @@ Yes. You can run SpacetimeDB on your own infrastructure using `spacetime start`, docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start ``` -You can also use the hosted SpacetimeDB cloud (maincloud) at no cost during the current beta period. +You can also use the hosted SpacetimeDB cloud (Maincloud). See the [Deployment & Operations](#deployment--operations) section below for details. --- @@ -48,9 +44,9 @@ You can also use the hosted SpacetimeDB cloud (maincloud) at no cost during the ### How is SpacetimeDB different from Mirror / Netcode / Photon / other networking libraries? -Networking libraries like Mirror, Netcode for GameObjects, and Photon handle the transport layer — sending messages between clients and a server you build and deploy yourself. You're still responsible for writing server logic, managing state, handling persistence, and deploying infrastructure. +Networking libraries like Mirror, Netcode for GameObjects, and Photon handle the transport layer: sending messages between clients and a server you build and deploy yourself. You are still responsible for writing server logic, managing state, handling persistence, and deploying infrastructure. -SpacetimeDB replaces the entire server. Your game state lives in tables, your game logic lives in reducers, and SpacetimeDB automatically synchronizes state to clients in real-time. You don't write networking code, serialization code, or deploy servers. +SpacetimeDB replaces the entire server. Your game state lives in tables, your game logic lives in reducers, and SpacetimeDB automatically synchronizes state to clients in real-time. You do not write networking code, serialization code, or deploy servers. | | Networking Libraries | SpacetimeDB | |---|---|---| @@ -64,13 +60,37 @@ SpacetimeDB replaces the entire server. Your game state lives in tables, your ga Firebase and Supabase are Backend-as-a-Service platforms. They give you a database with an API layer on top, but your application logic still runs elsewhere (cloud functions, edge functions, or your own server). Complex business logic is awkward to express as database triggers or serverless functions. -SpacetimeDB lets you write your entire application as a module in a real programming language (Rust, C#, TypeScript) that runs inside the database. You get full transactional guarantees, direct table access, and real-time subscriptions — without the cold starts, execution limits, or awkward abstractions of serverless functions. +SpacetimeDB lets you write your entire application as a module in a real programming language (Rust, C#, TypeScript) that runs inside the database. You get full transactional guarantees, direct table access, and real-time subscriptions without the cold starts, execution limits, or awkward abstractions of serverless functions. ### How is SpacetimeDB different from a regular database (PostgreSQL, MySQL)? A traditional database stores data and lets you query it. Your application logic runs in a separate server that connects to the database over the network. -SpacetimeDB holds all data in memory for sub-millisecond access, runs your application logic inside the database as WebAssembly modules, and pushes real-time updates to connected clients automatically. It's purpose-built for real-time applications, not batch processing or analytics. +SpacetimeDB holds all data in memory for sub-microsecond access, runs your application logic inside the database as WebAssembly modules, and pushes real-time updates to connected clients automatically. It is purpose-built for real-time applications, not batch processing or analytics. For certain benchmarks, SpacetimeDB can be between 100 and 1000 times faster than a traditional database. + +--- + +## Core Concepts + +### What is a "module"? + +A module is your application's server-side code compiled to WebAssembly (or bundled as JavaScript for TypeScript modules). It defines your tables, reducers, views, and procedures. You upload it to SpacetimeDB with `spacetime publish`, and it runs inside the database. Think of it as your entire backend in a single deployable unit. + +### What are tables? + +Tables are the core data storage in SpacetimeDB. You define them in your module using your language's type system. Tables support primary keys, unique constraints, and indexes. Clients can subscribe to tables and receive real-time updates when rows change. + +### What are reducers? + +Reducers are functions that modify your database state. They run inside a database transaction: either all changes commit or none do. Clients call reducers through auto-generated, type-safe bindings. Think of them as transactional RPC endpoints. + +### What are views? + +Views are read-only functions that compute derived data from your tables. They are like SQL views but written in your module's language. Clients can subscribe to views just like tables, and they update automatically when the underlying data changes. See [Views](/functions/views) for details. + +### What are procedures? + +Procedures are similar to reducers but with additional capabilities. They can make HTTP requests to external services and manually manage transactions. Clients can also call procedures over HTTP. Procedures are currently in beta. Use reducers for most cases; use procedures when you need to interact with the outside world. In the future, procedures will be configurable as HTTP endpoints. See [Procedures](/functions/procedures) for details. --- @@ -82,23 +102,26 @@ SpacetimeDB holds all data in memory for fast access, but persists everything to ### How does real-time sync work? -Clients subscribe to SQL queries that specify what data they care about. SpacetimeDB evaluates these subscriptions and pushes incremental updates whenever the underlying data changes. On the client side, the SDK maintains a local cache that mirrors the server state — you query this cache directly with no round trips. +Clients subscribe to SQL queries that specify what data they care about. SpacetimeDB evaluates these subscriptions and pushes incremental updates whenever the underlying data changes. On the client side, the SDK maintains a local cache that mirrors the server state. You query this cache directly with no round trips. ```typescript -// Client subscribes to nearby players -ctx.subscribe("SELECT * FROM players WHERE distance(x, y, ?, ?) < 100", myX, myY); +// Client subscribes using the type-safe query builder +conn.subscriptionBuilder().subscribe(tables.players); + +// Or with a raw SQL query +conn.subscriptionBuilder().subscribe("SELECT * FROM players WHERE team = 'red'"); // The local cache updates automatically -const nearbyPlayers = ctx.db.players; +const players = ctx.db.players; ``` ### Are reducers like REST endpoints? -Reducers are more like transactional RPC calls. A client calls a reducer by name with arguments, the reducer runs inside a database transaction, and either all changes commit or none do. Unlike REST, there's no HTTP overhead, no JSON serialization, and no need to design URL routes. Clients call reducers through auto-generated, type-safe bindings. +Reducers are more like transactional RPC calls. A client calls a reducer by name with arguments, the reducer runs inside a database transaction, and either all changes commit or none do. Unlike REST, there is no HTTP overhead, no JSON serialization, and no need to design URL routes. Clients call reducers through auto-generated, type-safe bindings. ### What happens if a reducer fails? -The entire transaction rolls back. No partial updates, no corrupted state. The database remains exactly as it was before the reducer was called. You can throw errors or return `Err` freely — SpacetimeDB handles the cleanup. +The entire transaction rolls back. No partial updates, no corrupted state. The database remains exactly as it was before the reducer was called. You can throw errors or return `Err` freely. SpacetimeDB handles the cleanup. ### What languages can I write modules in? @@ -114,9 +137,7 @@ Client SDKs are available for: - **TypeScript** (including React, Vue, Svelte, Angular, and more) - **C++** (Unreal Engine) -### What is a "module"? - -A module is your application's server-side code compiled to WebAssembly (or bundled as JavaScript for TypeScript modules). It defines your tables, reducers, views, and procedures. You upload it to SpacetimeDB with `spacetime publish`, and it runs inside the database. Think of it as your entire backend in a single deployable unit. +SpacetimeDB 2.0 also includes a **type-safe query builder** for client-side subscriptions, so you do not have to write raw SQL strings if you prefer not to. --- @@ -135,11 +156,11 @@ See the [quickstart guides](/quickstart) for step-by-step tutorials. ### What is `spacetime dev`? -`spacetime dev` is the development workflow command. It watches your module for changes, automatically rebuilds and republishes it, generates client bindings, and optionally starts your client dev server. It's like `npm run dev` but for your entire full-stack application. +`spacetime dev` is the development workflow command. It watches your module for changes, automatically rebuilds and republishes it, generates client bindings, and optionally starts your client dev server. It is like `npm run dev` but for your entire full-stack application. ### Do I need to write SQL? -Only for client-side subscriptions (telling the client what data to sync). Your server-side module code uses native language APIs to query and modify tables — no SQL needed on the server side. +Only for client-side subscriptions (telling the client what data to sync). Your server-side module code uses native language APIs to query and modify tables. No SQL is needed on the server side. On the client side, you can also use the type-safe query builder instead of raw SQL. ### Can I use SpacetimeDB with Unity? @@ -151,19 +172,66 @@ Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. ### Can I use SpacetimeDB with React / Vue / Angular / Svelte? -Yes. The TypeScript SDK includes framework-specific integrations for React, Vue, Angular, Svelte, and more. These provide reactive hooks/composables that automatically update your UI when database state changes. +Yes. The TypeScript SDK includes framework-specific integrations for React, Vue, Angular, Svelte, and more. These provide reactive hooks and composables that automatically update your UI when database state changes. + +--- + +## Authentication & Authorization + +### How do I implement auth in my app? + +SpacetimeDB uses [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) for authentication. Every reducer call includes the caller's `Identity`, which you can use for authorization logic in your module. You have several options for identity providers: + +- **[SpacetimeAuth](/spacetimeauth)**: A fully managed OIDC provider built specifically for SpacetimeDB. The easiest way to get started. +- **Third-party providers**: Any OIDC-compliant provider works, including [Auth0](https://auth0.com/), [Clerk](https://clerk.com/), [Keycloak](https://www.keycloak.org/), Google, GitHub, and others. + +See [Authentication](/authentication) for full details. + +### Can I use `Identity` as a 1-to-1 mapping with users? + +Yes, and this is the recommended approach. Each authenticated user receives a stable `Identity` that persists across sessions. You can store user profiles keyed by `Identity` and use it as your primary user identifier. If you use an OIDC provider (such as SpacetimeAuth, Auth0, or Clerk), the `Identity` is derived from the provider's tokens, so the same user always gets the same `Identity`. + +### Can I store passwords in a private table and have users log in by calling a reducer? -### How do I handle authentication? +No. SpacetimeDB does not currently support private reducer arguments. Any subscriber to your module can observe reducer arguments. Use OIDC-based authentication instead, where the identity provider handles credential verification and issues tokens that SpacetimeDB validates. -SpacetimeDB uses the [OpenID Connect](https://openid.net/developers/how-connect-works/) standard. You can use SpacetimeDB's built-in auth provider (SpacetimeAuth), or integrate with any OpenID Connect provider (Google, Auth0, etc.). Every reducer call includes the caller's `Identity`, which you can use for authorization logic. +### How do I create a new localhost identity? -### What are Views? +Send a `POST /v1/identity` request to your SpacetimeDB instance. The response includes a new identity and token. See the [HTTP API reference](/http/identity#post-v1identity) for details. -Views are read-only functions that compute derived data from your tables. They're like SQL views but written in your module's language. Clients can subscribe to views just like tables, and they update automatically when the underlying data changes. +### How do I subscribe to data related to a specific `Identity`? -### What are Procedures? +Write a subscription query that filters by the identity's hex representation: -Procedures are like reducers but with additional capabilities — they can make HTTP requests to external services and manually manage transactions. They're currently in beta. Use reducers for most use cases; use procedures when you need to interact with the outside world. +```typescript +conn.subscriptionBuilder().subscribe( + `SELECT * FROM messages WHERE sender = 0x${identityHex}` +); +``` + +--- + +## Schema & Migrations + +### How do I handle schema migrations? + +When you publish an updated module, SpacetimeDB compares the new schema with the existing one and performs automatic migrations for compatible changes (adding tables, adding columns with defaults, etc.). For breaking changes, you may need to publish with `--delete-data` during development. See [Automatic Migrations](/databases/automatic-migrations) for details on what changes are supported. + +### How do I add a column to an existing table? + +SpacetimeDB does not currently support adding or removing columns from existing tables through automatic migration. Use the [incremental migration pattern](/databases/incremental-migrations) instead: create a new table with the desired schema and lazily migrate rows from the old table as they are accessed. + +### How do I remove a column from an existing table? + +The same approach as adding a column: use [incremental migrations](/databases/incremental-migrations). Create a new table without the column and migrate data incrementally. + +### How do I add a new table? + +You can simply add the table definition to your module and republish. SpacetimeDB creates new tables automatically during publish. + +### How do I add or remove indexes? + +You can add or remove indexes by updating the table definition and republishing. Note that removing an index may break client subscription queries that depend on it. --- @@ -171,42 +239,67 @@ Procedures are like reducers but with additional capabilities — they can make ### How do I deploy to production? -You can deploy to the SpacetimeDB cloud (maincloud) with: +You can deploy to [SpacetimeDB Maincloud](https://spacetimedb.com/pricing), our fully managed serverless platform: ```bash spacetime publish my-app --server maincloud ``` -Or self-host SpacetimeDB and publish to your own server. +Maincloud handles infrastructure, scaling, replication, and backups. It scales to zero when idle, so you only pay for what you use. There is a free tier with 2,500 TeV of energy credit per month, a Pro tier at $25/month with 100,000 TeV, and Team and Enterprise tiers for larger workloads. See the [pricing page](https://spacetimedb.com/pricing) for full details. + +You can also self-host SpacetimeDB and publish to your own server. ### Can I update my module without downtime? -Yes. When you `spacetime publish` an update, SpacetimeDB hot-swaps the module code. Connected clients are **not** disconnected — they seamlessly continue with the new logic. This is possible because all state lives in tables, not in the server process. +Yes. When you `spacetime publish` an update, SpacetimeDB hot-swaps the module code. Connected clients are not disconnected. They seamlessly continue with the new logic. This is possible because all state lives in tables, not in the server process. -### How do I handle schema migrations? +### How do I clear my database? + +Use the `-c` (or `--delete-data`) flag when publishing: + +```bash +spacetime publish my-app -c +``` -When you publish an updated module, SpacetimeDB compares the new schema with the existing one and performs automatic migrations for compatible changes (adding tables, adding columns with defaults, etc.). For breaking changes, you may need to publish with `--delete-data` during development or implement manual migration logic in your `init` reducer. +This deletes all data and re-runs the `init` reducer. ### Is there a size limit for databases? -SpacetimeDB holds all data in memory, so the practical limit is the available RAM on the host. On the hosted cloud, resource limits depend on your plan. For self-hosted deployments, you control the hardware. +SpacetimeDB holds all data in memory, so the practical limit is the available RAM on the host. On Maincloud, resource limits depend on your plan. For self-hosted deployments, you control the hardware. -### How much does SpacetimeDB cost? +### How do I build a room-based or match-based game? -SpacetimeDB is free to use during the current beta period, including the hosted cloud. Pricing for production workloads will be announced separately. +SpacetimeDB databases are lightweight and fast to create. The recommended pattern is to use an external orchestration service that creates and destroys SpacetimeDB databases for each room or match. Each database runs an independent instance of your module with its own state. --- ## Troubleshooting -### I'm getting a 401/403 when publishing — what's wrong? +### I'm getting a 401/403 when publishing. What is wrong? -Database names are **global** on maincloud. If someone else already published a database with that name, you'll get an authorization error. Try a more unique name. +Database names are global on Maincloud. If someone else already published a database with that name, you will get an authorization error. Try a more unique name. ### My `spacetime generate` command gives a confusing error -If your module's `init` reducer panics (e.g., due to a unique constraint violation), `spacetime generate` may show an unhelpful error like `EOF while parsing a value`. Fix the runtime error in your module first, then generate again. +If your module's `init` reducer panics (for example, due to a unique constraint violation on re-publish), `spacetime generate` may show an unhelpful error like "EOF while parsing a value at line 1 column 0". Fix the runtime error in your module first, then generate again. ### How do I reset my database during development? -Use `spacetime publish my-app --delete-data` to clear all data and republish. Or use `spacetime dev` which handles this automatically with the `--delete-data=on-conflict` flag. +Use `spacetime publish my-app --delete-data` to clear all data and republish. Or use `spacetime dev`, which handles this automatically with the `--delete-data=on-conflict` flag. + +### I updated SpacetimeDB and now I cannot publish! + +If you upgraded from a pre-1.0 version, your local data format may be incompatible. Delete your local SpacetimeDB data directory and start fresh: + +```bash +rm -rf ~/.spacetime +spacetime start +``` + +### I got a weird error when compiling my module! + +Make sure you are using the same version of the SpacetimeDB module library (e.g., `spacetimedb` Rust crate, `@clockworklabs/spacetimedb-sdk` npm package, or `SpacetimeDB.ClientSDK` NuGet package) as the version of the SpacetimeDB host you are publishing to. Version mismatches between the module library and the host are a common source of confusing compilation or publish errors. + +### I got a weird error when compiling my client! + +Make sure the version of the client SDK you are using matches the version of `spacetime generate` that produced your bindings. If you recently updated SpacetimeDB, re-run `spacetime generate` to regenerate your bindings, and update your client SDK to the matching version. From 38b4d47314759ff85c4bc152ca120a980f10618c Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:21:50 -0500 Subject: [PATCH 3/6] docs: address second round of review comments - Fix 'add column' answer: SpacetimeDB now supports adding columns to the end of tables with default values - Add warning to localhost identity: non-expiring token, dev-only - Remove outdated pre-1.0 upgrade troubleshooting question - Fix npm package name: spacetimedb (not @clockworklabs/spacetimedb-sdk) - Simplify password storage answer (remove 'currently' qualifier) --- .../00100-getting-started/00500-faq.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index 4693fa4e220..b9d3ec877a5 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -193,12 +193,16 @@ Yes, and this is the recommended approach. Each authenticated user receives a st ### Can I store passwords in a private table and have users log in by calling a reducer? -No. SpacetimeDB does not currently support private reducer arguments. Any subscriber to your module can observe reducer arguments. Use OIDC-based authentication instead, where the identity provider handles credential verification and issues tokens that SpacetimeDB validates. +No. Reducer arguments are visible to subscribers. Use OIDC-based authentication instead, where the identity provider handles credential verification and issues tokens that SpacetimeDB validates. ### How do I create a new localhost identity? Send a `POST /v1/identity` request to your SpacetimeDB instance. The response includes a new identity and token. See the [HTTP API reference](/http/identity#post-v1identity) for details. +:::warning +Identities issued by SpacetimeDB acting as its own identity provider are tied to a single token that does not expire. If that token is lost, there is no way to recover or re-authenticate as that identity. This approach is recommended for **development only**. For production applications, use an external OIDC provider (SpacetimeAuth, Auth0, Clerk, etc.) which provides proper token lifecycle management. +::: + ### How do I subscribe to data related to a specific `Identity`? Write a subscription query that filters by the identity's hex representation: @@ -219,11 +223,11 @@ When you publish an updated module, SpacetimeDB compares the new schema with the ### How do I add a column to an existing table? -SpacetimeDB does not currently support adding or removing columns from existing tables through automatic migration. Use the [incremental migration pattern](/databases/incremental-migrations) instead: create a new table with the desired schema and lazily migrate rows from the old table as they are accessed. +SpacetimeDB supports adding new columns to the end of a table, provided the new columns have [default values](/tables#default-values). This is handled automatically when you republish your module. For more complex changes (reordering columns, changing types), use the [incremental migration pattern](/databases/incremental-migrations): create a new table with the desired schema and lazily migrate rows from the old table as they are accessed. ### How do I remove a column from an existing table? -The same approach as adding a column: use [incremental migrations](/databases/incremental-migrations). Create a new table without the column and migrate data incrementally. +Removing columns is not supported through automatic migration. Use [incremental migrations](/databases/incremental-migrations) instead: create a new table without the column and migrate data incrementally. ### How do I add a new table? @@ -287,18 +291,9 @@ If your module's `init` reducer panics (for example, due to a unique constraint Use `spacetime publish my-app --delete-data` to clear all data and republish. Or use `spacetime dev`, which handles this automatically with the `--delete-data=on-conflict` flag. -### I updated SpacetimeDB and now I cannot publish! - -If you upgraded from a pre-1.0 version, your local data format may be incompatible. Delete your local SpacetimeDB data directory and start fresh: - -```bash -rm -rf ~/.spacetime -spacetime start -``` - ### I got a weird error when compiling my module! -Make sure you are using the same version of the SpacetimeDB module library (e.g., `spacetimedb` Rust crate, `@clockworklabs/spacetimedb-sdk` npm package, or `SpacetimeDB.ClientSDK` NuGet package) as the version of the SpacetimeDB host you are publishing to. Version mismatches between the module library and the host are a common source of confusing compilation or publish errors. +Make sure you are using the same version of the SpacetimeDB module library (e.g., `spacetimedb` Rust crate, `spacetimedb` npm package, or `SpacetimeDB.ClientSDK` NuGet package) as the version of the SpacetimeDB host you are publishing to. Version mismatches between the module library and the host are a common source of confusing compilation or publish errors. ### I got a weird error when compiling my client! From acf6ecf8a12c58e8bf1efa0943120c3fae032177 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:28:24 -0500 Subject: [PATCH 4/6] docs: fix password FAQ - reducer args no longer visible in 2.0 Reducer arguments are no longer exposed to subscribers in SpacetimeDB 2.0 (Event Tables replaced old reducer callbacks). Updated the password FAQ to reflect this while still recommending OIDC over DIY auth. --- docs/docs/00100-intro/00100-getting-started/00500-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index b9d3ec877a5..eae371f4cec 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -193,7 +193,7 @@ Yes, and this is the recommended approach. Each authenticated user receives a st ### Can I store passwords in a private table and have users log in by calling a reducer? -No. Reducer arguments are visible to subscribers. Use OIDC-based authentication instead, where the identity provider handles credential verification and issues tokens that SpacetimeDB validates. +This is not recommended. While SpacetimeDB 2.0 no longer exposes reducer arguments to subscribers (the old reducer callback system has been replaced by [Event Tables](/tables/event-tables)), storing and verifying passwords in your module means implementing your own authentication logic, which is error-prone and unnecessary. Use OIDC-based authentication instead, where the identity provider handles credential verification and issues tokens that SpacetimeDB validates. ### How do I create a new localhost identity? From 5271c1ae36148599696db1c501d80497f4f5fda3 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 22:49:27 -0500 Subject: [PATCH 5/6] docs: fix broken links in FAQ - /quickstart -> /quickstarts/react - /quickstart/unreal -> /quickstarts/c-plus-plus - /spacetimeauth -> /core-concepts/authentication/spacetimeauth - /authentication -> /core-concepts/authentication --- docs/docs/00100-intro/00100-getting-started/00500-faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index eae371f4cec..923f60e16c3 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -152,7 +152,7 @@ SpacetimeDB 2.0 also includes a **type-safe query builder** for client-side subs 5. Generate client bindings: `spacetime generate --lang typescript --out-dir src/module_bindings` 6. Connect from your client using the generated code -See the [quickstart guides](/quickstart) for step-by-step tutorials. +See the [quickstart guides](/quickstarts/react) for step-by-step tutorials. ### What is `spacetime dev`? @@ -168,7 +168,7 @@ Yes. SpacetimeDB has a C# client SDK that works with Unity. The SDK maintains a ### Can I use SpacetimeDB with Unreal Engine? -Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. See the [Unreal quickstart](/quickstart/unreal) for details. +Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. See the [Unreal quickstart](/quickstarts/c-plus-plus) for details. ### Can I use SpacetimeDB with React / Vue / Angular / Svelte? @@ -182,10 +182,10 @@ Yes. The TypeScript SDK includes framework-specific integrations for React, Vue, SpacetimeDB uses [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) for authentication. Every reducer call includes the caller's `Identity`, which you can use for authorization logic in your module. You have several options for identity providers: -- **[SpacetimeAuth](/spacetimeauth)**: A fully managed OIDC provider built specifically for SpacetimeDB. The easiest way to get started. +- **[SpacetimeAuth](/core-concepts/authentication/spacetimeauth)**: A fully managed OIDC provider built specifically for SpacetimeDB. The easiest way to get started. - **Third-party providers**: Any OIDC-compliant provider works, including [Auth0](https://auth0.com/), [Clerk](https://clerk.com/), [Keycloak](https://www.keycloak.org/), Google, GitHub, and others. -See [Authentication](/authentication) for full details. +See [Authentication](/core-concepts/authentication) for full details. ### Can I use `Identity` as a 1-to-1 mapping with users? From 0cc510c6b1bfb6d6fb935e39c499a41297f7fcc8 Mon Sep 17 00:00:00 2001 From: clockwork-labs-bot Date: Mon, 16 Feb 2026 23:31:12 -0500 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20fix=20broken=20anchor=20/tables#def?= =?UTF-8?q?ault-values=20=E2=86=92=20/tables/default-values?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/00100-intro/00100-getting-started/00500-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index 923f60e16c3..456e281d7a7 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -223,7 +223,7 @@ When you publish an updated module, SpacetimeDB compares the new schema with the ### How do I add a column to an existing table? -SpacetimeDB supports adding new columns to the end of a table, provided the new columns have [default values](/tables#default-values). This is handled automatically when you republish your module. For more complex changes (reordering columns, changing types), use the [incremental migration pattern](/databases/incremental-migrations): create a new table with the desired schema and lazily migrate rows from the old table as they are accessed. +SpacetimeDB supports adding new columns to the end of a table, provided the new columns have [default values](/tables/default-values). This is handled automatically when you republish your module. For more complex changes (reordering columns, changing types), use the [incremental migration pattern](/databases/incremental-migrations): create a new table with the desired schema and lazily migrate rows from the old table as they are accessed. ### How do I remove a column from an existing table?