Skip to content

Docs: Expand FAQ for 2.0 launch#4314

Queued
clockwork-labs-bot wants to merge 6 commits intomasterfrom
bot/faq-update
Queued

Docs: Expand FAQ for 2.0 launch#4314
clockwork-labs-bot wants to merge 6 commits intomasterfrom
bot/faq-update

Conversation

@clockwork-labs-bot
Copy link
Collaborator

Rewrites the FAQ from 5 basic questions to a comprehensive guide covering:

  • General — What is SpacetimeDB, is it only for games, is it blockchain, licensing, self-hosting
  • Comparisons — vs Mirror/Photon/networking libs, vs Firebase/Supabase, vs PostgreSQL
  • Architecture — Data persistence, real-time sync, reducers vs REST, module languages, views, procedures
  • Development — Getting started, spacetime dev, SQL usage, Unity/Unreal/React/framework support, auth
  • Deployment — Production publishing, hot-swapping modules, schema migrations, size limits, pricing
  • Troubleshooting — Global database names (401/403), confusing generate errors, resetting databases

Content drawn from README, architecture docs, Zen of SpacetimeDB, and common user questions from GitHub issues and Discord.

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)
Copy link
Contributor

@cloutiertyler cloutiertyler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left some comments, please make sure to address all the questions listed here:

  • How do I implement auth in my app?
    • Can I use Identity as a 1-to-1 with users? (We'd like you to, yes. Use this as an opportunity to talk about OIDC. Link to an OIDC-compliant provider users can use, ideally.)
    • Can I store passwords (or hashes thereof) in a private table, and have users log in by calling a reducer? (No, we don't have private reducer arguments, so any subscriber can see your password.)
    • How do I create a new localhost identity? (POST /identity.)
  • How do I hotswap-publish? (It's easy.)
  • How do I clear my database? (With -c.)
  • How do I do migrations?
    • ...Add a column to a table? (Can't RN; redirect to "incremental migrations" for now.)
    • ...Remove a column from a table? (Same as above.)
    • ...Add a new table? (You can just do that.)
    • ...Add or remove indices? (You can just do that, though removing indices may break subscription queries.)
  • How do I build a room- or match-based game? (You need an external service which creates and destroys StDB databases.)
  • I updated SpacetimeDB (from a pre-1.0 version) and now I can't publish! (Delete your local data.)
  • I got a weird error when I tried to publish! (Make sure you're using the same version of the module library as your host.)
  • I got a weird error when I tried to compile my client! (Make sure you're using the same version of the client SDK as your spacetime generate codegen.)
  • How do I subscribe to things related to a specific Identity? (Write a query that filters with 0x{identity_hex}.)

- 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)
- 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)
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.
- /quickstart -> /quickstarts/react
- /quickstart/unreal -> /quickstarts/c-plus-plus
- /spacetimeauth -> /core-concepts/authentication/spacetimeauth
- /authentication -> /core-concepts/authentication
@clockwork-labs-bot clockwork-labs-bot added this pull request to the merge queue Feb 17, 2026
Any commits made after this event will not be merged.
github-merge-queue bot pushed a commit that referenced this pull request Feb 17, 2026
Rewrites the FAQ from 5 basic questions to a comprehensive guide
covering:

- **General** — What is SpacetimeDB, is it only for games, is it
blockchain, licensing, self-hosting
- **Comparisons** — vs Mirror/Photon/networking libs, vs
Firebase/Supabase, vs PostgreSQL
- **Architecture** — Data persistence, real-time sync, reducers vs REST,
module languages, views, procedures
- **Development** — Getting started, `spacetime dev`, SQL usage,
Unity/Unreal/React/framework support, auth
- **Deployment** — Production publishing, hot-swapping modules, schema
migrations, size limits, pricing
- **Troubleshooting** — Global database names (401/403), confusing
generate errors, resetting databases

Content drawn from README, architecture docs, Zen of SpacetimeDB, and
common user questions from GitHub issues and Discord.

---------

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants