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

&String

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) {
    // timer row is auto-deleted after this reducer runs
}

// 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 });

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

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:

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.

rust-server

NPX Install

Tags

SKILL.md Content

SpacetimeDB Rust SDK Reference

Imports

Tables

Column Types

Column Attributes

Indexes

Reducers

DB Operations

Lifecycle Hooks

Views

Client Visibility Filters

Reducer Context API

Environment Variables

Scheduled Tables

Inter-Database Calls (Async IDC)

Procedures and HTTP

Logging

Custom Types

Complete Example

Module Unit Tests