Programming · Learning & explanation
rust-server
/rust-server
SpacetimeDB Rust server module SDK reference. Use when writing tables, reducers, or module logic in Rust.
For whom
- Author
- clockworklabs ↗
- Repository
- spacetimedb ↗
- Licence
- AGPL-3.0
- Last repository change
- 12.11.2026
Assessment and security
100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
Deprecation
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
Licence
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
SpacetimeDB Rust server module SDK reference. Use when writing tables, reducers, or module logic in Rust.
Original author description
SpacetimeDB Rust server module SDK reference. Use when writing tables, reducers, or module logic in Rust.
How it works
- Imports
- Tables
- Column Types
- Column Attributes
- Indexes
- Reducers
- DB Operations
- Lifecycle Hooks
- Views
- Client Visibility Filters
Original SKILL.md headings · 499 lines, 2,251 words
SKILL.md preview
---
name: rust-server
description: SpacetimeDB Rust server module SDK reference. Use when writing tables, reducers, or module logic in Rust.
license: Apache-2.0
metadata:
author: clockworklabs
version: "2.0"
role: server
language: rust
cursor_globs: "**/*.rs"
cursor_always_apply: true
---
# SpacetimeDB Rust SDK Reference
## Imports
```rust
use spacetimedb::{
procedure, reducer, table, Filter, Identity, ProcedureContext, Query,
ReducerContext, SpacetimeType, Table, ConnectionId, ScheduleAt,
TimeDuration, Timestamp, Uuid,
};
```
**`Table` is required.** Without it, `ctx.db.*.insert()`, `.iter()`, `.find()` etc. won't compile (`no method named 'insert' found`).
## Tables
`#[spacetimedb::table(...)]` on a `pub struct`. `accessor` must be snake_case:
```rust
#[spacetimedb::table(accessor = entity, public)]
pub struct Entity {
#[primary_key]
#[auto_inc]
pub id: u64,
pub owner: Identity,
pub name: String,
#[index(btree)]
pub active: bool,
}
```
Options: `accessor = snake_case` (required), `public`, `scheduled(reducer_fn)`, `index(...)`
`ctx.db` accessors use the `accessor` name (snake_case).
## Column Types
| Rust type | Notes |
|-----------|-------|
| `u8` / `u16` / `u32` / `u64` / `u128` | unsigned integers |
| `i8` / `i16` / `i32` / `i64` / `i128` | signed integers |
| `spacetimedb::sats::u256` / `spacetimedb::sats::i256` | 256-bit integers |
| `f32` / `f64` | floats |
| `bool` | boolean |
| `String` | text |
| `Vec<T>` | list/array |
| `Identity` | user identity |
| `ConnectionId` | connection handle |
| `Timestamp` | server timestamp (microseconds since epoch) |
| `TimeDuration` | duration in microseconds |
| `Uuid` | UUID |
| `Option<T>` | nullable column |
## Column Attributes
```rust
#[primary_key] // primary key
#[auto_inc] // auto-increment (use 0 as placeholder on insert)
#[unique] // unique constraint
#[index(btree)] // btree index (enables .filter() on this column)
#[default(true)] // migration-safe default for a newly appended column
```
Defaults support compatible addition of a newly appended field. Do not place `#[default(...)]` on primary-key, unique, or auto-increment columns.
## Indexes
Prefer `#[index(btree)]` inline for single-column. Multi-column uses table-level:
```rust
// Inline (preferred for single-column):
#[index(btree)]
pub author_id: u64,
// Access: ctx.db.post().author_id().filter(author_id)
// Multi-column (table-level):
#[spacetimedb::table(accessor = membership, public,
index(accessor = by_group_user, btree(columns = [group_id, user_id]))
)]
pub struct Membership { pub group_id: u64, pub user_id: Identity, ... }
// Access: ctx.db.membership().by_group_user().filter((group_id, &user_id))
```
When you frequently look up rows by multiple columns, prefer a multi-column index over filtering by one column and looping over the results.
## Reducers
```rust
#[spacetimedb::reducer]
pub fn create_entity(ctx: &ReducerContext, name: String) {
ctx.db.entity().insert(Entity { id: 0, owner: ctx.sender(), name, active: true });
}
// Reducers can return Result<(), String> or Result<(), E> where E: Display
#[spacetimedb::reducer]
pub fn validate_entity(ctx: &ReducerContext, name: String) -> Result<(), String> {
if name.is_empty() {
return Err("Name cannot be empty".to_string());
}
ctx.db.entity().try_insert(Entity { id: 0, owner: ctx.sender(), name, active: true })?;
Ok(())
}
```
Note: `insert()` panics on constraint violations. Use `try_insert()` with `?` when returning `Result`.
## DB Operations
```rust
ctx.db.entity().insert(Entity { id: 0, name: "Sample".into() }); // Insert (0 for autoInc)
ctx.db.entity().id().find(entity_id); // Find by PK → Option<Entity>
ctx.db.entity().identity().find(ctx.sender()); // Find by unique column → Option<Entity>
ctx.db.item().author_id().filter(author_id); // Filter by index → iterator
ctx.db.entity().iter(); // All rows → iterator
ctx.db.entity().count(); // Count rows
ctx.db.entity().id().update(Entity { name: new_name, ..existing }); // Update (override + spread)
ctx.db.entity().id().delete(entity_id); // Delete by PK
ctx.db.entity().name().delete("Alice".to_string()); // Delete by indexed String column
```
Note: `iter()` and `filter()` return iterators. Collect to Vec if you need `.sort()`, `.filter()`, `.map()`.
Range queries on btree indexes: `filter(18..=65)`, `filter(18..)`, `filter(..18)`.
String column accessors operate on the column's owned `String` type, not `&str`. Pass a `String` or `&String` to `find` and `delete`; index filters borrow the key, as in `ctx.db.product().category().filter(&"hardware".to_string())`.
## Lifecycle Hooks
```rust
#[spacetimedb::reducer(init)]
pub fn init(ctx: &ReducerContext) { ... }
#[spacetimedb::reducer(client_connected)]
pub fn on_connect(ctx: &ReducerContext) { ... }
#[spacetimedb::reducer(client_disconnected)]
pub fn on_disconnect(ctx: &ReducerContext) { ... }
```
The current connection ID is available through `ctx.connection_id()` (not a public field) and may be absent outside connection-scoped calls.
## Views
```rust
// Anonymous view (same result for all clients):
use spacetimedb::{view, AnonymousViewContext};
#[view(accessor = active_users, public)]
fn active_users(ctx: &AnonymousViewContext) -> Vec<Entity> {
ctx.db.entity().active().filter(true).collect()
}
// Per-user view (result varies by sender):
use spacetimedb::{view, ViewContext};
#[view(accessor = my_profile, public)]
fn my_profile(ctx: &ViewContext) -> Option<Entity> {
ctx.db.entity().identity().find(ctx.sender())
}
```
Procedural-view table handles support indexed `find` and `filter` access, but not full-table `iter()`. Start a procedural view from an appropriate table index.
Declare a procedural view primary key in the view attribute:
```rust
#[view(accessor = catalog_entry, public, primary_key = sku)]
fn catalog_entry(ctx: &AnonymousViewContext) -> Vec<CatalogEntry> { ... }
```
Procedural-view primary keys are explicit schema metadata. Add one only when the view itself is required to expose a primary key; a source table's primary key is not inherited by the view.
Query-builder views use `ViewContext`, `ctx.from`, and return `impl Query<Row>`. Use `filter` for predicates and `right_semijoin` when the result should contain right-side rows that have a matching left-side row:
```rust
ctx.from.article().filter(|article| article.published.eq(true))
ctx.from.subscription().right_semijoin(
ctx.from.account(),
|subscription, account| subscription.account_id.eq(account.id),
)
```
Query-builder comparisons against a `String` column take an owned `String`, for example `row.label.eq("active".to_string())`.
Views can also accept arguments (2.13+), after the context:
```rust
#[spacetimedb::view(accessor = entity_by_id, public)]
pub fn entity_by_id(ctx: &spacetimedb::AnonymousViewContext, id: u64) -> Option<Entity> {
ctx.db.entity().id().find(id)
}
```
Floating-point arguments and primary keys are rejected on argument-bearing views. See client skills for SQL subscription syntax and restrictions.
## Client Visibility Filters
```rust
use spacetimedb::Filter;
#[spacetimedb::client_visibility_filter]
const PRIVATE_NOTE_FILTER: Filter =
Filter::Sql("SELECT * FROM owned_row WHERE owner = :sender");
```
## Reducer Context API
`ReducerContext` (`ctx`) is the only source of sender identity, time, and randomness; stdlib clocks and RNG are unavailable in modules.
```rust
// Auth: ctx.sender() is the caller's Identity
if row.owner != ctx.sender() {
panic!("unauthorized");
// or: return Err(anyhow::anyhow!("unauthorized"));
}
// Server timestamp (deterministic per reducer call)
ctx.db.item().insert(Item { id: 0, owner: ctx.sender(), created_at: ctx.timestamp, .. });
// Timestamp arithmetic
let expiry = ctx.timestamp + TimeDuration::from_micros(delay_micros);
// Deterministic RNG: ctx.random() for a single value, ctx.rng() for the rand::Rng trait
use spacetimedb::rand::Rng;
let n: u32 = ctx.random(); // random u32
let roll: u32 = ctx.rng().gen_range(1..=6); // any rand::Rng method
// Client: Timestamp → milliseconds since epoch
timestamp.to_micros_since_unix_epoch() / 1000
```
## Environment Variables
```rust
#[spacetimedb::env]
pub struct Env {
pub API_KEY: String,
pub LOG_LEVEL: Option<String>,
}
// Inside a root entry point:
// ctx.env.API_KEY() -> String
// ctx.env.LOG_LEVEL() -> Option<String>
// ctx.env.get("LOG_LEVEL") -> Option<String>
```
For constrained values, derive `spacetimedb::EnvironmentValue` on a payload-free enum and use it as a field type (or `Option<Enum>`). `#[env(value = "production")]` on a variant supplies its exact accepted string; without it, the Rust variant name is used. `#[env(values("info", "debug"))]` also constrains `String`/`Option<String>` fields.
See the concepts skill for shared environment and secret-handling rules.
## Scheduled Tables
```rust
#[spacetimedb::table(accessor = tick_timer, scheduled(tick), public)]
pub struct TickTimer {
#[primary_key]
#[auto_inc]
scheduled_id: u64,
scheduled_at: spacetimedb::ScheduleAt,
}
#[spacetimedb::reducer]
pub fn tick(ctx: &ReducerContext, timer: TickTimer) {
// a one-time row is deleted after this runs; an interval row stays
}
// One-time: fires once at a specific time
let at = ScheduleAt::Time(ctx.timestamp + std::time::Duration::from_secs(10));
// Repeating: fires on an interval
let at = ScheduleAt::Interval(std::time::Duration::from_secs(5).into());
ctx.db.tick_timer().insert(TickTimer { scheduled_id: 0, scheduled_at: at });
```
To let only the scheduler run a callback, reject calls where `ctx.sender() != ctx.database_identity()`.
Construct a connection ID from a numeric representation with `ConnectionId::from_u128(value)`.
## Inter-Database Calls (Async IDC)
A reducer calls a reducer in another database by inserting a row into an outbox table. The call is sent only if the transaction commits, runs exactly once, and runs in order with other calls through the same outbox to the same database. The sending reducer doesn't wait for it. Both databases must be on the same server.
Generate receiver bindings by listing the receiving module under `dependencies` in the sending database's `spacetime.json`, then running `spacetime generate <sending-database>`. Rust bindings are written to `src/remote_bindings/`.
```json
{
"database": "lobby",
"module-path": "./lobby",
"dependencies": [{ "name": "game_world", "database": "game-world" }],
"children": [{ "database": "game-world", "module-path": "./game_world" }]
}
```
```rust
mod remote_bindings;
use remote_bindings::game_world;
// Each row is one call to game_world's `admit_player(name: String)` reducer.
#[spacetimedb::table(accessor = admit_player_outbox, outbox(game_world::admit_player))]
pub struct AdmitPlayerOutbox {
#[primary_key]
#[auto_inc]
msg_id: u64, // exactly one u64 auto_inc primary key
#[target]
world: game_world::Identity, // exactly one target, typed by the bindings
name: String, // one column per reducer parameter, same name and type
// #[param(name = name)] player_name: String, // alias a column to a parameter
// Extra columns are allowed. They aren't sent, but on_result can read them.
}
#[spacetimedb::reducer]
pub fn send_to_world(ctx: &ReducerContext, name: String, world: game_world::Identity) {
// Sent if and only if this transaction commits.
ctx.db.admit_player_outbox().insert(AdmitPlayerOutbox { msg_id: 0, world, name });
}
// Optional, at most one per outbox. Private. Runs once per row, then the row is deleted.
#[spacetimedb::reducer(on_result(admit_player_outbox))]
pub fn on_admit_player_result(ctx: &ReducerContext, row: AdmitPlayerOutbox, result: Result<(), String>) {
if let Err(error) = result {
log::warn!("{} was not admitted: {error}", row.name);
}
}
```
- The receiving reducer is an ordinary reducer and needs no changes. In it, `ctx.sender()` is the sending database's identity, so authorize calls by checking it against an allow-list table.
- The receiving database runs `client_connected` and `client_disconnected` around every delivered call, with no JWT. If `client_connected` rejects the sending database, the call is retried forever.
- Outbox rows are insert-only, so a pending call can't be cancelled. A call is never retried once it has a result. To try again, insert a new row, for example from `on_result`.
- Wrap a plain `Identity` to get a target: `game_world::Identity(identity)`.
- Index lookups (`find`, `filter`) on a `game_world::Identity` column don't compile. Iterate and compare instead.
- An outbox table can't also be a scheduled table or an event table.
- After the receiving reducer's parameters change, regenerate the bindings and republish the sending database. Calls built from old bindings fail with a signature mismatch error.
See https://spacetimedb.com/docs/databases/inter-database-communication for details.
## Procedures and HTTP
Procedures use `&mut ProcedureContext` and may return typed values:
```rust
use spacetimedb::{procedure, ProcedureContext, SpacetimeType};
#[derive(SpacetimeType)]
pub struct ResultValue { pub value: String }
#[procedure]
pub fn inspect(_ctx: &mut ProcedureContext, input: String) -> ResultValue {
ResultValue { value: input }
}
```
Outbound HTTP is available through `ctx.http`. Convenience methods such as `get` return a response, and other methods use `Request::builder()` with `ctx.http.send(request)`. `response.status()` returns a `StatusCode`; use `is_success()` to test it or `as_u16()` when a numeric status is needed. Responses are not cloneable, so inspect status and headers before consuming the body with `response.into_body().into_string_lossy()`. Header values use the fallible `to_str()` conversion; they do not provide `as_str()`.
Open short database transactions with `ctx.with_tx(|tx| ...)`. Access tables inside the callback through `tx.db`, not directly on `tx`. It returns the callback's value directly, so do not call `unwrap` or `expect` on the result unless the callback itself returns a `Result`. The callback implements `Fn`, so clone captured owned values when storing them rather than moving them out of the closure. Perform network I/O before opening the transaction.
For an outbound request without a convenience method:
```rust
let request = Request::builder()
.method("POST")
.uri(url)
.body(Body::from_bytes(data))
.unwrap();
let response = ctx.http.send(request).expect("request failed");
```
Scheduled procedures use the ordinary scheduled-table shape, but the scheduled function is marked `#[procedure]` and receives `&mut ProcedureContext` plus the scheduled row.
Inbound HTTP uses handler functions and one router. Handlers are unstable, so enable the `unstable` feature: `spacetimedb = { version = "2.*", features = ["unstable"] }`.
```rust
use spacetimedb::http::{handler, router, Body, HandlerContext, Request, Response, Router};
#[handler]
fn health(_ctx: &mut HandlerContext, _request: Request) -> Response {
Response::builder().status(200).body(Body::from_bytes("ok")).unwrap()
}
#[router]
fn routes() -> Router { Router::new().get("/health", health) }
```
`HandlerContext` does not expose `db`; open database access with `ctx.with_tx(|tx| ...)`. HTTP response bodies must own their data or borrow `'static` data, so convert dynamic borrowed text to an owned `String` before passing it to `Body::from_bytes`.
## Logging
```rust
log::info!("Player connected: {:?}", ctx.sender());
log::warn!("Low health: {}", hp);
log::error!("Failed to find entity");
```
## Custom Types
```rust
#[derive(SpacetimeType)]
pub enum Status { Online, Away, Offline }
#[derive(SpacetimeType)]
pub struct Point { x: f32, y: f32 }
```
## Complete Example
```rust
// src/lib.rs
use spacetimedb::{Identity, ReducerContext, SpacetimeType, Table, Timestamp};
#[spacetimedb::table(accessor = entity, public)]
pub struct Entity {
#[primary_key]
pub identity: Identity,
pub name: String,
pub active: bool,
}
#[spacetimedb::table(accessor = record, public)]
pub struct Record {
#[primary_key]
#[auto_inc]
pub id: u64,
pub owner: Identity,
pub value: u32,
pub created_at: Timestamp,
}
#[spacetimedb::reducer(client_connected)]
pub fn on_connect(ctx: &ReducerContext) {
if let Some(existing) = ctx.db.entity().identity().find(ctx.sender()) {
ctx.db.entity().identity().update(Entity { active: true, ..existing });
}
}
#[spacetimedb::reducer(client_disconnected)]
pub fn on_disconnect(ctx: &ReducerContext) {
if let Some(existing) = ctx.db.entity().identity().find(ctx.sender()) {
ctx.db.entity().identity().update(Entity { active: false, ..existing });
}
}
#[spacetimedb::reducer]
pub fn create_entity(ctx: &ReducerContext, name: String) {
if ctx.db.entity().identity().find(ctx.sender()).is_some() {
panic!("already exists");
}
ctx.db.entity().insert(Entity { identity: ctx.sender(), name, active: true });
}
#[spacetimedb::reducer]
pub fn add_record(ctx: &ReducerContext, value: u32) {
if ctx.db.entity().identity().find(ctx.sender()).is_none() {
panic!("not found");
}
ctx.db.record().insert(Record {
id: 0,
owner: ctx.sender(),
value,
created_at: ctx.timestamp,
});
}
```
## Module Unit Tests
The native in-memory harness is available in 2.12+. Keep the same `spacetimedb` version in normal and dev dependencies, enabling `test-utils` only for tests:
```toml
[dependencies]
spacetimedb = { version = "2.13.0", features = ["unstable"] }
[dev-dependencies]
spacetimedb = { version = "2.13.0", features = ["test-utils"] }
icu_calendar = ">=2.1, <2.2" # temporal_rs requires icu_calendar 2.1.x
```
Run `cargo test` natively, not with a WebAssembly target. For the `create_entity` reducer above:
```rust
#[cfg(test)]
mod tests {
use super::*;
use spacetimedb::test_utils::{TestAuth, TestContext};
#[test]
fn inserts_entity() {
let test = TestContext::new().expect("test database");
test.with_reducer_tx(TestAuth::internal(), |ctx| {
create_entity(ctx, "Alice".to_owned());
Ok::<(), String>(())
}).expect("transaction");
assert_eq!(test.db.entity().count(), 1);
}
}
```
`with_reducer_tx` commits on `Ok` and rolls back on `Err` or panic unwinding; propagate reducer errors with `?` when the reducer returns `Result`. Create a new `TestContext` for each test: cloning shares the database. Use `TestAuth::from_jwt_payload(payload, connection_id)?` for client calls and `TestAuth::internal()` for the database itself. The harness exposes `clock`, `rng`, procedure/view contexts, and query execution. It does not simulate subscriptions, RLS, lifecycle calls, or timers. Invoke lifecycle/scheduled reducers explicitly and retain integration tests for host behavior.
See https://spacetimedb.com/docs/how-to/unit-testing for test setup, HTTP mocking, and current limitations.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · clockworklabs/spacetimedb | 100 | AGPL-3.0 |
| clockworklabs/spacetimedb | 95 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version 1fe637939cdc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95typescript-server
SpacetimeDB TypeScript server module SDK reference. Use when writing tables, reducers, or module logic in TypeScript. - 100cpp-server
SpacetimeDB C++ server module SDK reference. Use when writing tables, reducers, or module logic in C++. - 91spacetimedb-local
Use when running a SpacetimeDB module locally. - 100port-c-module
Guide for porting a C module to Rust. Use this when starting to port a C module to Rust. - 86rust-tests-guidelines
Guidelines for writing Rust tests. Use this when you want to write Rust tests. - 100rust
Guide for Rust programming language. Use when writing Rust code, setting up Rust projects, or needing an overview of Rust development workflows.