Audited all registered routes in `database.rs` and `identity.rs` against
the HTTP API documentation.
## Fixes
**database.md:**
- `/v1/database/:name_or_identity` publish: `POST` → `PUT` (code has
`db_put: put(publish::<S>)`)
- `DELETE` row in summary table: anchor pointed to POST section instead
of DELETE section
- Typo: `Updgrade` → `Upgrade` in WebSocket subscribe headers
**identity.md:**
- Removed `POST /v1/identity/:identity/set-email` — documented but has
no handler registered in `IdentityRoutes` (dead documentation)
## Routes in code but intentionally not documented (internal/unstable)
- `POST /v1/database/:noi/pre_publish`
- `PUT /v1/database/:noi/reset`
- `GET /v1/database/:noi/unstable/timestamp`
These are used internally by the CLI and are not part of the public API.
---------
Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
## Summary
This PR creates a comprehensive self-hosted JWT key rotation how-to for
SpacetimeDB with reproducible defaults, identity-preserving rotation
guidance, and host-scoped data migration runbooks. It is written for
both operators and automation workflows, with explicit guardrails for
production-like VM environments.
## Key Changes
- Adds a top-level assumptions/risk section for a multi-host topology
(`prod`, `test`, `dev`, optional `local`) including backup prerequisites
before rotation or sync.
- Defines an opinionated, end-to-end path contract for keys:
- host source: `./.generated/spacetimedb-keys`
- runtime mount: `/etc/spacetimedb`
- startup args pinned to `/etc/spacetimedb/id_ecdsa` and
`/etc/spacetimedb/id_ecdsa.pub`
- Includes reproducible quickstart scaffolding:
- OpenSSL commands for compatible ES256/P-256 key generation
- non-container and Docker startup examples
- rotation/verify command sequence and marker checks
- Documents one unified tooling surface around `spacetimedb-tooling.ts`
for:
- rotate (`--dry-run`, `--yes`)
- verify (`--verify-only`)
- token continuity (`--resign-token-only`)
- explicit token/key path overrides (`--publisher-cli-toml-path`,
`--private-key-path`)
- Clarifies 401 vs 403 behavior and why identity drift causes publish
failures after rotation.
- Covers all rotation strategies in one place:
- clean-slate rotation (stateless/dev)
- identity-preserving rotation (stateful)
- OIDC-backed identity model for production
- Adds host-scoped migration runbooks for staged sync (`prod -> test ->
dev`) with destination-side token re-signing semantics (run on
destination host context, including SSH examples).
- Explicitly separates conceptual topology guidance from currently
implemented sync primitives in reference tooling to avoid over-claiming.
- Adds operational guardrails for sync promotions:
- `rsync --delete` is destructive
- stop/start ordering around sync
- required acceptance gates: key parity, destination re-sign,
restart/redeploy, publish marker validation
- Expands verification and automation content:
- PEM/parity/fingerprint/newline checks
- AI/automation contract with inputs, outputs, required command order,
and success/failure markers
- troubleshooting flow for `InvalidSignature` and ownership mismatch
errors
## Why This Matters
The most common failure mode in self-hosted fleets is identity drift:
signatures validate, but `spacetime publish` still fails with `403
Forbidden` because destination ownership no longer matches the
publishing identity after key rotation or data movement.
The updated how-to makes these operator requirements explicit:
1. preserve identity continuity across rotations and host promotions
2. re-sign destination tokens after `rsync` in destination host context
3. treat restart/redeploy and publish markers as promotion gates
Following this runbook prevents regressions where key material is
correct but publish still fails due to stale signatures or owner
mismatch state.
## Why JWT Key Rotation Is Essential for Self-Hosters
In self-hosted deployments, operators are the signing authority.
Rotation is both a security control and an operational correctness
requirement.
### Security value
- reduces exposure window for compromised private keys
- invalidates old/stolen tokens after rotation
- mitigates risk from snapshots, backups, clones, and long-lived VM
access
### Operational value
- keeps key material consistent across multi-VM environments
- reduces publish outages after promotion/sync operations
- prevents avoidable `401`/`403` failures in routine release workflows
## Scope
- docs-only change
- public-safe examples only (no internal org names, private vault IDs,
or private secret prefixes)
- includes non-container and Docker workflows, self-publish/versioning
guidance, and marker-based validation (`PUBLISH_SUCCESS`,
`PUBLISH_FAILED`)
- includes data migration workflow guidance (`rsync` + destination
re-sign + restart/redeploy + publish checks)
---------
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Fixes#1972
Adds client-side log level filtering to `spacetime logs`:
- `--level <LEVEL>` / `-l <LEVEL>`: Show only logs at the specified
severity or higher. Valid values: `trace`, `debug`, `info`, `warn`,
`error`, `panic`. Default: show all logs (no filtering).
- `--level-exact`: When combined with `--level`, show only logs at
exactly the specified level.
Severity order (most to least): panic > error > warn > info > debug >
trace.
Examples:
```
spacetime logs mydb --level warn # Show only warn, error, and panic
spacetime logs mydb --level info # Show info and above
spacetime logs mydb --level error --level-exact # Show only errors
```
Filtering is done client-side.
---------
Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Closes https://github.com/clockworklabs/SpacetimeDB/issues/4496.
The docs refer to a block mentioning `/v1/publish` but we don't have
such a block in our example config. What we actually have is:
```
# Block all other routes explicitly. Only localhost can use these routes. If you want to open your
# server up so that anyone can publish to it you should comment this section out.
location / {
allow 127.0.0.1;
deny all;
}
```
# API and ABI breaking changes
None.
# Expected complexity level and risk
1.
# Testing
None
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Contains 2 changes to documentation:
* Updates Unity Client Blackholio tutorial, part 2, with a corrected
`call` command. `Debug` became `debug` to match the automatic case
conversion that now occurs. Originally found and reported by discord
user `chrispavs`
* Updates Unity Client Blackholio tutorial, part 2, with the `out-dir`
path to match the path given in the [Entering the
Game](https://spacetimedb.com/docs/tutorials/unity/part-3#entering-the-game)
of `step 3`.
# API and ABI breaking changes
None
# Expected complexity level and risk
1 - Docs correction
# Testing
- [X] Tested all `blackholio` tutorial steps using C# server and Unity
client
In the `init` reducer, `ctx.sender` is the **module owner** — the
identity of the user who published the database. This is the only
lifecycle reducer where the owner identity is automatically provided.
Added a tip to the lifecycle docs showing:
- That `ctx.sender` in `init` is the owner
- How to store it in a table for later authorization checks
- Examples in TypeScript, C#, and Rust
Closes#3229
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
The 'Option 2: overwrite the name of individual tables' section of the
2.0 migration guide had an empty TypeScript tab. Adds a complete example
using `table()` with an explicit `name` property to preserve the
pre-conversion table name.
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
# Description of Changes
LLM benchmark updates for local development:
- **Local SDK paths**: Templates use relative paths to workspace crates
(`crates/bindings`, `crates/bindings-csharp`,
`crates/bindings-typescript`) instead of published packages, so the
bench runs against local SDK changes.
- **NODEJS_DIR support**: On Windows (e.g. nvm4w), if `pnpm` is not on
PATH, the bench uses `NODEJS_DIR` to locate `pnpm` and prepends it to
PATH for subprocesses.
- **Refactor**: Extracted `relative_to_workspace()` in `templates.rs`
and removed noisy `NODEJS_DIR` logging in `publishers.rs`.
- **Benchmark results**: Updated `docs/llms/llm-comparison-details.json`
and `docs/llms/llm-comparison-summary.json`.
# API and ABI breaking changes
None.
# Expected complexity level and risk
**2** — Local-only changes to the benchmark tool. Templates now require
local SDKs to be built (especially TypeScript: `pnpm build` in
`crates/bindings-typescript`). No impact on published SDKs or runtime.
# Testing
- [ ] Run `cargo llm run --lang rust --modes docs --providers openai`
from repo root
- [ ] Run TypeScript benchmarks with `pnpm build` in
`crates/bindings-typescript` first
- [ ] On Windows with nvm4w, set `NODEJS_DIR` if `pnpm` is not on PATH
and run TypeScript benchmarks
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Fixes a missing word in the Unity and Unreal tutorial part-3 docs.
**Before:** `specify a specific at which to call a reducer once`
**After:** `specify a specific **time** at which to call a reducer once`
Fixed in 4 files (current docs + v1.12.0 versioned docs), 6 occurrences
total.
Spotted by Tyler.
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Now that scheduled reducers are private, this warning is no longer
necessary.
# Description of Changes
- removed Security Considerations section from Schedule Tables
documentation
Signed-off-by: Tao Tien <29749622+taotien@users.noreply.github.com>
Co-authored-by: joshua-spacetime <josh@clockworklabs.io>
# Description of Changes
- Rename `Spacerace` to `Referrals` for docs nav item to align with
updated naming
<!-- Please describe your change, mention any related tickets, and so on
here. -->
# Screenshots
- After:
<img width="1510" height="49" alt="image"
src="https://github.com/user-attachments/assets/3bdbe6ec-8a51-4686-9292-28c38b6d14d9"
/>
- Before:
<img width="1460" height="47" alt="image"
src="https://github.com/user-attachments/assets/5c70b0ef-d5fc-42fa-9dc9-5fd4f034d415"
/>
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Docs displays correctly
# Description of Changes
This change is needed since the AI halicunates that the name is schedule
for some dam reason every time in the llm tests. while it is scheduled
https://github.com/clockworklabs/SpacetimeDB/blob/e2f8a607593f8e2e446df06d84b21e26af2bfc68/docs/llms/docs-benchmark-details.json#L90
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [ ] Run the LLM benchmark and see if this fixes it
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
# Description of Changes
Some examples in our cheat-sheet incorrectly used a `filter` method on a
unique index. Unique indexes expose `find`, and non-unique indexes
expose `find`. This commit updates the cheatsheet to use the appropriate
index seek methods.
# API and ABI breaking changes
N/a
# Expected complexity level and risk
N/a
# Testing
N/a
# Reviewers
Does the C++ code work as written, or do you have to do something
horrible to do with ranges?
# Description of Changes
* Updates `00500-views.md` with:
* Changes returned value to a nullable value, to match the return type
defintion.
* Wraps sample code in `public partial class Module` so pasting it in to
IDE will not return errors.
* Updates `00500-cheat-sheet.md` with:
* Changes reducer names to not start with `On` to avoid error `STDB0010:
Reducer method OnConnect starts with 'On', which is a reserved prefix.`
* Adds `Accessor` values to views.
* Updates `Filter()` returned value to use `.ToList()` and the return
type to use `List<Player>` rather than `IEnumerable<Player>` to avoid
error, due to needing a return type to be `Vec<T>` or `Option<T>`.
* Updated `Coddgen.Test` to include tests verifying current behavior of
`IEnumerable<T>`, to aid in future update to allow a return type of
`IEnumerable<T>` to be allowed and converted internally to the required
type.
# API and ABI breaking changes
None
# Expected complexity level and risk
1 – documentation-only edits with no behavioral impact.
# Testing
- [X] Changed code blocks tested locally to ensure formatting resolved
in IDE.
# Description of Changes
<!-- Please describe your change, mention any related tickets, and so on
here. -->
- Right now if you go to the docs https://spacetimedb.com/docs/ and you
click on spacerace in the upper right it will 404. This PR fixes this
issue.
# API and ABI breaking changes
None
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1 - just a docs update
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
```
cd docs
npm install
npm run dev
```
- [x] spacerace button works in docs
# Description of Changes
Fix AI assistant rules links in llms.txt, they were missing a `/docs`
# API and ABI breaking changes
None.
# Expected complexity level and risk
0.0001
# Testing
Clicked the link
## Summary
Multiple fixes and improvements to `spacetime dev`, `spacetime publish`,
`spacetime init`, and templates:
### CLI fixes
- **Fix `spacetime dev` watch path and .env.local handling** for
templates with a `spacetimedb/` subdirectory
- **Validate package manager availability** before installing
dependencies — re-prompts if the selected PM isn't on PATH
- **Remove JS/TS beta warning** from `spacetime publish`
- **Remove unstable warning** from `spacetime init`
- **Remove unused `spacetime energy` command** (can be re-added later
when properly implemented)
- **Fix `tsc` detection on Windows** — `set_extension(".cmd")` produced
`tsc..cmd` (double dot); fixed to `set_extension("cmd")`
- **Add `typescript` as devDependency** to all server template
`spacetimedb/package.json` files so `tsc` is available during build
- **Strip `\?\` extended-length path prefix** from user-facing output in
both `dev` and `publish` commands (produced by `fs::canonicalize()` on
Windows)
- **Fix publish reporting success when user declines** non-local server
prompt — changed `return Ok(())` to `bail!()` consistent with other
abort cases
- **Forward stdin to client process** in `spacetime dev` so interactive
CLI templates work
### Template fixes
- **Fix Angular template environment variables** — Angular's esbuild
builder doesn't support `import.meta.env`, so we use a dev script to
generate `environment.local.ts` with Angular's native `fileReplacements`
pattern
- **Fix TanStack Start template** — rename `createRouter` to `getRouter`
(v1.121+ breaking change), upgrade to React 19, and add
`@vitejs/plugin-react` for automatic JSX runtime support
- **Fix `moduleResolution` in remix-ts and nextjs-ts** server tsconfigs
— change from `"node"` to `"bundler"` to support subpath exports like
`spacetimedb/server`
- **Fix browser-ts template** — convert from static HTML + IIFE bundle
to standard Vite dev server app so it works with `spacetime dev` and
reads env vars from `.env.local`
- **Add `deno` as devDependency** to deno-ts template (matches how
bun-ts includes bun)
- **Convert basic-ts from empty web app to CLI app** matching basic-rs —
connect, subscribe to person table, print on insert
## Test plan
- [x] `cargo test -p spacetimedb-cli` — all 133 tests pass
- [ ] `spacetime dev --template angular-ts` — verify Angular app
connects with correct database name
- [ ] `spacetime dev --template react-ts` — verify React template still
works
- [ ] `spacetime dev --template tanstack-ts` — verify TanStack Start
template loads without errors
- [ ] `spacetime dev --template remix-ts` — verify Remix template builds
and runs
- [ ] `spacetime dev --template nextjs-ts` — verify Next.js template
still works
- [ ] `spacetime dev --template browser-ts` — verify Vite dev server
starts and app connects
- [ ] `spacetime dev --template bun-ts` — verify Bun CLI template runs
interactively
- [ ] `spacetime dev --template basic-ts` — verify CLI connects and
prints on insert
- [ ] Verify no `\?\` prefix in any displayed paths on Windows
- [ ] Verify no `tsc not found` warning when building server modules
- [ ] Select unavailable package manager at init prompt — verify
re-prompt
- [ ] Decline non-local server prompt — verify clean error instead of
"Published successfully!"
---------
Co-authored-by: Piotr Sarnacki <drogus@gmail.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
## Summary
Enable confirmed reads by default for all WebSocket subscriptions and
SQL queries. This is a 2.0 breaking change that improves data integrity.
### What changed
Previously, subscription updates and SQL results were sent to clients
immediately, before the transaction was confirmed durable. A server
crash could cause clients to have observed data that was lost.
Now the server defaults to `confirmed=true`. Clients receive updates
only after durability is confirmed. This adds a small latency cost but
guarantees that any data a client receives will survive a server
restart.
### Changes
**Server (2 files, 2 lines each):**
- `subscribe.rs`: `SubscribeQueryParams.confirmed` defaults to `true`
- `database.rs`: `SqlQueryParams.confirmed` defaults to `true`
**Documentation:**
- Migration guide updated with "Confirmed Reads Enabled by Default"
section
- Added to overview list and quick migration checklist
### Opt-out
Clients can opt out by explicitly passing `?confirmed=false` in the
WebSocket URL or using `.withConfirmedReads(false)` /
`.WithConfirmedReads(false)` / `.with_confirmed_reads(false)` in SDKs.
### Smoketest impact
Smoketests that don't explicitly pass `--confirmed` will now get
confirmed reads via the server default. This should not cause failures
-- confirmed reads only add a small wait for durability confirmation
before sending results. The `confirmed_reads.py` smoketest explicitly
passes `--confirmed` and continues to work as before.
### SDK impact
No SDK changes needed. SDKs only send the `confirmed` query parameter
when explicitly set by the user. When not set, the server default
applies -- which is now `true`.
---------
Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
- Update llm benchmark results based on latest testing
- Clean up details file to remove old models
- Regenerated the summary file
# API and ABI breaking changes
- None
# Expected complexity level and risk
- 1
# Testing
- Verify the new summary file loads correctly on the website.
# Description of Changes
* Updates directory tree to reflect the actual results of running
`spacetime dev --template basic-cs my-spacetime-app` with no additional
arguments.
* Updates the `Add` -> `add` reducer call to use lower-case to match the
default when no override is specified.
* Updates the `SayHello` -> `say_hello` reducer call to use lower-case
to match the default when no override is specified.
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
- [X] Walked through every step with a local server to test behavior.
This involved.
* Cleared all local cache and rebuilding the CLI.
* Rebuilding the DLLs
* From my test project directory, running:
`D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe
dev --template basic-cs my-spacetime-app` and selecting the default
values.
* This threw an error because, I believe, it was not using the local
DLLs.
* Going into each `.csproj` to ensure they are using the local versions
of the files.
* Running the remaining commands, while targeting the local CLI
executables:
* Note: `local` server is mapped to `127.0.0.1:3000`
```
D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe publish -s local my-spacetime-app
D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe call -s local my-spacetime-app add Alice
D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe sql -s local my-spacetime-app "SELECT * FROM Person"
D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe call -s local my-spacetime-app say_hello
D:\Projects\ClockworkLabs\SpacetimeDB\target\debug\spacetimedb-cli.exe logs -s local my-spacetime-app
```
# Description of Changes
Docs will now go to version 2.0.0 by default, and there is a banner with
a link to the newer docs if someone is viewing the v1 docs.
# Expected complexity level and risk
1. Biggest risk here is breaking links.
# Testing
I tested this locally, and checked that links are working.
There is also a broken link checker in the CI.
# Description of Changes
Removes left over references to the query builder's `.build()` method as
well as some stale C# references from `llms.md`.
Only rust and C# docs needed updating.
# API and ABI breaking changes
None
# Expected complexity level and risk
1. Small docs update
# Testing
N/A
## Summary
- Update the `QuickstartLinks` component on the Getting Started
(`/docs`) page to show all 16 quickstart guides instead of just 4
(TypeScript, C#, Rust, React)
- The component now uses `useDocsVersion()` to filter items based on the
active doc version, so v1.12 only shows quickstarts that exist in that
version while v2.0 shows all 16
- Add new SVG logos for Vue, Nuxt, Svelte, Angular, TanStack Start,
Deno, and C++
- Replace existing logos (React, Next.js, Node.js, Bun, Remix, HTML5)
with consistent monochrome `currentColor` versions sourced from the
spacetime-web homepage
- Fix Rust logo visibility in dark mode by removing hardcoded
`style="color: black;"`
## Test plan
- [ ] Verify the Getting Started page on v2.0.0-rc1 shows all 16
quickstart cards
- [ ] Verify the Getting Started page on v1.12.0 shows only the
quickstarts that exist in that version (react, vue, svelte, typescript,
rust, c-sharp)
- [ ] Verify all card links navigate to the correct quickstart page
- [ ] Verify logos are visible in both light and dark mode
# Description of Changes
- Node.js: Use esbuild instead of tsx
- Node.js: Remove interactive CLI since it doesn't work with `spacetime
dev`
- Next.js: Fix onError callback to use single argument (ctx) and use
ctx.event for the error.
- Next.js: Replace lint-disable comment with `_connection` for the
unused variable.
- Updated quickstart docs to use proper `withDatabaseName`
# API and ABI breaking changes
None.
# Expected complexity level and risk
**Complexity: 1–2.** Small tooling, type, and lint tweaks. Low risk.
# Testing
- [ ] Build affected templates (e.g. `pnpm build` in nextjs-ts).
- [ ] Lint passes.
# Description of Changes
Expanded and reorganized the 2.0 migration guide, and also deleted a
file that was in the wrong place. (The word "migration" is
overloaded...)
# API and ABI breaking changes
N/a
# Expected complexity level and risk
Like, 1 I guess, since this isn't code? But we should be careful to get
this right.
# Testing
- [x] Pasted all 2.0 Rust examples into a project based on the
`basic-rs` template and got 'em to build.
- This required filling in some code outside the examples (defining
`play_damage_animation`, binding `target` and `amount`), and changing
one table name that was used in two examples, but otherwise everything
is valid.
- I didn't test the 1.0 examples.
---------
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: = <cloutiertyler@gmail.com>
# Description of Changes
This change cuts a version of the docs from 1.12.0
(e45cf891c2), and saves it under
`docs/versioned_docs/version-1.12.0`.
If you go to the docs page, it will redirect to the 1.12.0 docs, which
has a banner at the top for trying the prerelease docs:
<img width="1027" height="283" alt="Screenshot 2026-02-20 at 12 07
39 PM"
src="https://github.com/user-attachments/assets/8ff3d622-b693-469a-980a-01c34d0506b8"
/>
If you select the prelease docs, there is a warning banner at the top:
<img width="886" height="299" alt="Screenshot 2026-02-20 at 12 08 52 PM"
src="https://github.com/user-attachments/assets/5508a635-765e-40cc-ad2a-cbbed7f779dd"
/>
# Expected complexity level and risk
This only changes docs.
# Testing
I've testing by running this locally.
# Description of Changes
Deno quickstart template now uses `package.json` instead of `deno.json`
so `spacetime dev` can run it. Added `templates/deno-ts/package.json`,
removed `deno.json`, and updated the Deno quickstart doc.
# API and ABI breaking changes
None.
# Expected complexity level and risk
**1** — Template and docs only.
# Testing
- [ ] `spacetime dev --template deno-ts` and confirm client runs.
- [ ] Spot-check updated Deno quickstart doc.
# Description of Changes
This PR introduces a possibility to skip passing a DB name to various
commands if there is a config file with one database defined
# API and ABI breaking changes
This changes the behaviour of several CLI commands:
1. call
2. subscribe
3. sql
4. describe
5. logs
6. delete
# Expected complexity level and risk
4 - it's tricky to get all of the combinations of CLI arguments right
# Testing
I've tested the simplest cases manually.
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
# Description of Changes
Update the Default casing policy to `snake_case` for `RawModuleDefV10`.
Messy PR contains changes at different places, so that CI can pass:
Here are the main changes as follows:
- `bindings-macro` & `bindings` crate: `name` macro in Indexes for
canonical name and supply it to `RawModuleDefV10` via `ExplicitNames`.
- `bindings-typescript`:
- Changes has been reviewed through this PR -
https://github.com/clockworklabs/SpacetimeDB/pull/4308.
- `binding-csharp`: a single line change to pass `sourceName` of index
instead of null.
- `codegen`:
- Changes has been merged from branch -
https://github.com/clockworklabs/SpacetimeDB/pull/4337.
- Except a fix in rust codegen to use canonical name in Query buillder
instead of accessor.
- `lib/db/raw_def`: Extends `RawDefModuleV10` structure to support case
conversion.
- `schema` crate:
- `validate/v9` - Nothing itself should change or changes in v9
validation logic but the file contains a `CoreValidator` which is shared
with `validate/v10`. No test have t be updated to `validate/v9` which
ensures we aren't regressing it.
- `validate/v10`: This is the main meat, look at the new tests added in
bottom to understand what it does.
- Rest of the files are either test updates or module bindings.
## Testing:
1. Extensive unit tests have been added to verify generated `ModuleDef`
is correct.
2. I have done some e2e testing to verify rust codegen with rust and
typescript modules.
3. I would have like to do more testing for other codegens , I am
continue doing .
I have removed `sql.py` smoketest, as that seems to be already migated
in new framework and was headache to update.
## Expected complexity level and risk
4, It could have side-effect which aren't easily visible.
- - -
---------
Signed-off-by: Shubham Mishra <shivam828787@gmail.com>
Co-authored-by: rekhoff <r.ekhoff@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
Co-authored-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Noa <coolreader18@gmail.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@clockworklabs.io>
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Phoebe Goldman <phoebe@clockworklabs.io>
## Summary
- Fix `spacetime dev` failing on C# projects by watching the module
directory itself instead of hardcoded `spacetimedb_dir/src/` (which
doesn't exist for C# templates)
- Add layered file-watch filtering to avoid triggering rebuilds on build
artifacts:
1. Always-ignore dirs (`target/`, `bin/`, `obj/`, `node_modules/`, etc.)
2. Always-watch exceptions (`.env.local`, `spacetime.*.local.json`)
3. `.gitignore` rules from global, project, and module levels
- Suppress init's generic "Next steps" message when called from
`spacetime dev`, print a dev-appropriate `cd` hint instead when a new
project is created in a subdirectory
- Update 12 quickstart docs to tell users to open a new terminal and `cd
my-spacetime-app` before running CLI commands
## Test plan
- [x] `cargo build -p spacetimedb-cli` compiles successfully
- [ ] `spacetime dev --template basic-cs` no longer errors with "Input
watch path is neither a file nor a directory"
- [ ] Modifying a `.cs` file in `spacetimedb/` triggers a rebuild
- [ ] Build artifacts in `obj/`/`bin/` do not trigger rebuilds
- [ ] Rust projects (`spacetimedb/src/` exists) continue to work as
before
- [ ] `spacetime dev --template basic-cs` from a non-project directory
prints the "Tip: cd" hint, not the generic "Next steps"
- [ ] `spacetime init` standalone still prints "Next steps" as before
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
<!-- Please describe your change, mention any related tickets, and so on
here. -->
- For the quickstarts we don't want to pass a database name during
`spacetime dev --template ...`
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
None - this is just docs
# Expected complexity level and risk
None - this is just docs
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] All quickstarts no longer pass a database name during `spacetime
dev --template ...`
# Description of Changes
This patch does the following:
- Adds api reference docs for the module-side query builder in the view
docs
- Merges the client sdk and subscription docs pages
- Keeps subscription and client overview docs high-level (moved all api
docs to the language reference docs)
- Replaces SQL examples in the docs with the query builder
- Replaces SQL subscriptions in the templates with the query builder
Note, the last commit in this patch set transitions the templates over
to use the query builder instead of SQL subscriptions. This will break
them temporarily until #4000 merges.
Also note, a lot of this was AI assisted. It can still be improved upon,
but it's in a better state than it was.
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1
# Testing
N/A
---------
Signed-off-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
- Added a shared component with a message for C++ on the version pinning
- Updated every doc that has a C++ tab to include the new message
# API and ABI breaking changes
N/A
# Expected complexity level and risk
2 - Small document change but used a shared component
# Testing
- [x] Tested locally with pnpm dev
- [x] Hosted on my personal site to double check the shared component
# Description of Changes
The maximum http timeout (500ms) was too low for the OpenAI API to have
time to respond, so I raised it, and verified that the rust and
typescript examples work. Csharp wasn't building at all for some reason
(`Workload installation failed: Unable to load the service index for
source https://api.nuget.org/v3/index.json.`?)
# Expected complexity level and risk
1
# Testing
- [x] Manually tested these changes
# Description of Changes
- Updated all markdown files that call out `#[spacetimedb::table(name`
to `#[spacetimedb::table(accessor`
- Updated the LLM details on the same change
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1 - Small rework in documentation to use the new
# Testing
- [x] Did a small double check on name vs accessor locally
- [x] Codex tested all the LLM answers
# Description of Changes
- Updated the tutorials to use `accessor` in place of `name` for Rust
table definitions
- Removed incorrect file listings for Connect reducer as it's now
private
- Fixed a bug in the Unreal tutorial to bind to correct method for error
handling
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1- Documentation update only
# Testing
- [x] Tested the connect error build for Unreal
- [x] Discovered these issues through manual test of the tutorials
# Description of Changes
Updates the Chat App tutorial
`docs/docs/00100-intro/00300-tutorials/00100-chat-app.md`
* TypeScript (React) code snippet fixes
* Updated the initial `App.tsx` snippet to use `import type * as Types
from './module_bindings/types'` and type `systemMessages` as
`Types.Message[]`, matching the current template-generated bindings.
* Updated the placeholder `onlineUsers` / `offlineUsers` types in the
initial snippet to `Types.User[]`.
* Updated the `main.tsx` connection snippet with the template behavior
by sourcing `HOST` / `DB_NAME` from
`import.meta.env.VITE_SPACETIMEDB_HOST` / `VITE_SPACETIMEDB_DB_NAME` if
available.
* Removed an TypeScript example that referenced reducer event wiring
(`conn.reducers.onSendMessage(...)`) that doesn’t exist in the current
TS generated bindings.
* Updated the follow-up instruction text so the “replace `const
onlineUsers: ...`” and “replace `const offlineUsers: ...`” guidance
matches the updated `Types.User[]` placeholders in the earlier snippet.
* The tutorial section says arguments are JSON; the CLI will auto-quote
string args based on reducer parameter types, so the simple form
`send_message 'Hello, World!'` remains valid and is kept.
* Added C# Client SDK step to update `.csproj` file with `net8.0` and a
filter for code in the `spacetimedb` (server module) subdirectory.
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1
# Testing
- [x] Performed documented operations locally.
# Description of Changes
A few small changes to pin the version:
- Updated the CMakeLists back from 2.0.0 to 1.12.0
- Updated the Unreal Blackholio tutorial documentation to target the
1.12.0 branch and not master
- Updated the Unreal Blackholio tutorial to call out 2.0 is coming soon
- Disabled the upgrade-version tool code path for C++ upgrades, but left
logic in place for the near future
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1 - Docs change, config change, and blocking update path for C++
# Testing
- [x] Reviewed the docs
- [x] Tested update command locally
- [x] Tested `spacetime init` for `basic-cpp` and successfully built
# Description of Changes
Use `accessor =` rather than `name =` in Rust code snippet which defines
event table.
Add `schema` call and `export default` to TypeScript code snippet which
defines event table. I'm not sure this is better, and it's certainly
more cluttered, but the example as written you can't just copy/paste
into your module code.
# API and ABI breaking changes
N/a
# Expected complexity level and risk
Docs only
# Testing
Described elsewhere.
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>
Rewrites the Maincloud deployment guide from a bare-bones stub into a
comprehensive page. Addresses all three points from #3108 plus a
community request for the connection URI.
**New content:**
1. **Finding your module on the dashboard** - Direct URL
(`spacetimedb.com/my-module`) and profile page navigation
2. **Database lifecycle** - Running vs suspended states, automatic
suspension after inactivity, automatic resumption on first request
3. **Next steps section** - Links to dashboard, SpacetimeAuth setup,
quickstart guides, and usage monitoring
**Also added:**
- Prerequisites section (CLI install + `spacetime login` to link web
account)
- Publishing workflow (initial publish, hot-swap updates,
`--delete-data`)
- Client connection code examples for TypeScript, C#, Rust, and C++ with
the Maincloud host URL (`https://maincloud.spacetimedb.com`) - per
community request in #3108
- Database deletion instructions
- Link to pricing page
Closes#3108
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
# Description of Changes
Implementation of #4295
Convert existing `Name` attribute to `Accessor` to support new Canonical
Case conversation of 2.0
# API and ABI breaking changes
Yes, in C# modules, we no longer use the attribute name `Name`, it
should now be `Accessor`
# Expected complexity level and risk
1
# Testing
- [X] Build and tested locally
- [X] Ran regression tests locally
# Description of Changes
In the typescript quickstart example, this includes the server and
module name in the local storage variable name that we use for the auth
token.
This fixes an otherwise annoying issue people run into if they start
running the quickstart locally, then try to run it on maincloud. If they
have already run the app with a local server, their browser will store
the locally signed token, which will get rejected by maincloud.
# Expected complexity level and risk
1.
# Testing
I was able to connect to my local quickstart, then change the variables
to point to a module on maincloud, and I didn't get any errors.
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
## Description of Changes
This PR primarily affects the `bindings-macro` and `schema` crates to
review:
### Core changes
1. Replaces the `name` macro with `accessor` for **Tables, Views,
Procedures, and Reducers** in Rust modules.
2. Extends `RawModuleDefV10` with a new section for:
* case conversion policies
* explicit names
New sections are not validated in this PR so not functional.
3. Updates index behavior:
* Index names are now always **system-generated** for clients. Which
will be fixed in follow-up PR when we start validating RawModuleDef with
explicit names.
* The `accessor` name for an index is used only inside the module.
## Breaking changes (API/ABI)
1. **Rust modules**
* The `name` macro must be replaced with `accessor`.
2. **Client bindings (all languages)**
* Index names are now system-generated instead of using explicitly
provided names.
**Complexity:** 3
A follow-up PR will reintroduce explicit names with support for case
conversion.
---------
Co-authored-by: rekhoff <r.ekhoff@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
clockwork-labs-bot