Spacetimedb Rust

Define tables as structs with the #[table] attribute:

#[table(name = users, public)]
pub struct User {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[unique]
    pub email: String,
    pub name: String,
    pub created_at: Timestamp,
}

Constraints

Visibility

Rule: Make tables public only if clients need to subscribe. Keep internal state private.

Multi-Column Indexes

#[table(name = messages, public)]
#[index(btree, name = idx_channel_time, channel_id, sent_at)]
pub struct Message {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub channel_id: u64,
    pub sender: Identity,
    pub text: String,
    pub sent_at: Timestamp,
}

Accessor Naming

SpacetimeDB generates typed accessors from your constraints:

// Primary key → .id()
ctx.db.users().id().find(42);

// Unique field → .email()
ctx.db.users().email().find(&"[email protected]".to_string());

// BTree index → .idx_channel_time()
ctx.db.messages().idx_channel_time().filter(|row| row.channel_id == &1);

Type System

Supported Types

Custom Types

#[derive(SpacetimeType)]
pub struct Position {
    pub x: f64,
    pub y: f64,
    pub z: f64,
}

#[derive(SpacetimeType)]
pub enum Status {
    Active,
    Inactive,
    Banned,
}

Use #[sats(rename = "camelCaseName")] to control cross-language naming.

Reducers

Reducers are transactional functions that mutate tables:

#[reducer]
pub fn create_user(ctx: &ReducerContext, name: String, email: String) -> Result<(), String> {
    // Check for duplicates
    if ctx.db.users().email().find(&email).is_some() {
        return Err("Email already exists".to_string());
    }

    ctx.db.users().insert(User {
        id: 0, // auto_inc fills this
        email,
        name,
        created_at: ctx.timestamp,
    })?;

    Ok(())
}

CRUD Operations

ReducerContext

Error Handling

#[reducer]
pub fn transfer(ctx: &ReducerContext, from: u64, to: u64, amount: f64) -> Result<(), String> {
    let mut sender = ctx.db.accounts().id().find(from)
        .ok_or("Sender not found")?;
    let mut receiver = ctx.db.accounts().id().find(to)
        .ok_or("Receiver not found")?;

    if sender.balance < amount {
        return Err("Insufficient funds".to_string());
    }

    sender.balance -= amount;
    receiver.balance += amount;

    ctx.db.accounts().id().update(sender);
    ctx.db.accounts().id().update(receiver);

    Ok(())
}

Returning Err rolls back the entire transaction. No partial writes.

Good: Proper Error Handling

#[reducer]
pub fn do_something(ctx: &ReducerContext, id: u64) -> Result<(), String> {
    let item = ctx.db.items().id().find(id)
        .ok_or("Item not found")?;
    // ... safe operations
    Ok(())
}

Bad: Panicking in Reducers

#[reducer]
pub fn do_something(ctx: &ReducerContext, id: u64) {
    let item = ctx.db.items().id().find(id).unwrap(); // PANICS the WASM module
    // If the item doesn't exist, the entire module crashes
}

Never use unwrap() or expect() in reducers. Return Result<(), String> and use ?.

Lifecycle Hooks

// Runs once when the module is first published
#[reducer(init)]
pub fn init(ctx: &ReducerContext) -> Result<(), String> {
    // Seed initial data, set up config
    ctx.db.config().insert(Config { key: "version".into(), value: "1.0".into() })?;
    Ok(())
}

// Runs when a client connects
#[reducer(client_connected)]
pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> {
    log::info!("Client connected: {:?}", ctx.sender);
    Ok(())
}

// Runs when a client disconnects
#[reducer(client_disconnected)]
pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> {
    // Clean up presence, mark offline
    if let Some(mut user) = ctx.db.users().identity().find(ctx.sender) {
        user.online = false;
        ctx.db.users().identity().update(user);
    }
    Ok(())
}

Scheduling

Use ScheduleAt to run reducers on a timer:

// Define a schedule table
#[table(name = cleanup_schedule, scheduled(cleanup))]
pub struct CleanupSchedule {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub scheduled_at: ScheduleAt,
}

// The reducer that runs on schedule
#[reducer]
pub fn cleanup(ctx: &ReducerContext, _args: CleanupSchedule) -> Result<(), String> {
    let cutoff = ctx.timestamp - Duration::from_secs(86400);
    for msg in ctx.db.messages().iter().filter(|m| m.sent_at < cutoff) {
        ctx.db.messages().delete(msg);
    }
    Ok(())
}

// Schedule it in init
#[reducer(init)]
pub fn init(ctx: &ReducerContext) -> Result<(), String> {
    ctx.db.cleanup_schedule().insert(CleanupSchedule {
        id: 0,
        scheduled_at: ScheduleAt::Interval(Duration::from_secs(3600)), // Every hour
    })?;
    Ok(())
}

ScheduleAt variants:

• ScheduleAt::Time(timestamp) — Run once at a specific time
• ScheduleAt::Interval(duration) — Run repeatedly at an interval

Views

Read-only computed queries (new in 2.0):

#[table(name = active_users, public)]
#[view(query = "SELECT * FROM users WHERE online = true")]
pub struct ActiveUser {
    pub id: u64,
    pub name: String,
    pub online: bool,
}

Clients subscribe to views like regular tables. The view auto-updates when underlying data changes.

Performance warning: Views track a "read set" and re-evaluate when ANY table in the read set changes. For high-frequency updates, this can be expensive. Prefer direct subscriptions with filtered queries over views when write volume is high.

When to Use Views vs Subscriptions vs Procedures

Procedures

HTTP-callable functions with manual transaction control (new in 2.0):

#[reducer(procedure)]
pub fn get_stats(ctx: &ReducerContext) -> Result<String, String> {
    let user_count = ctx.db.users().count();
    let msg_count = ctx.db.messages().count();
    Ok(format!(r#"{{"users":{},"messages":{}}}"#, user_count, msg_count))
}

Use procedures for:

• HTTP API endpoints (GET-style queries)
• Operations that don't need real-time subscriptions
• Integration with external services

Event Tables

Transient tables for signaling — rows exist only during the transaction:

#[table(name = notification_events, public)]
#[event]
pub struct NotificationEvent {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub user_id: u64,
    pub message: String,
}

Clients can only register onInsert callbacks for event tables (no onDelete/onUpdate). Use for notifications, toasts, ephemeral signals.

Row-Level Security

Experimental (unstable). API may change.

Restrict which rows a client can see based on their identity:

#[table(name = private_messages, public)]
#[rls(filter = "sender = :sender OR recipient = :sender")]
pub struct PrivateMessage {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub sender: Identity,
    pub recipient: Identity,
    pub text: String,
}

:sender is the subscribing client's identity. Multiple #[rls] attributes are OR'd.

Known limitation: RLS + subscription + complex joins can produce unexpected results (issue #2810). Test thoroughly.

Testing

There is no spacetime test command (issue #2788). Use these workarounds:

1. Unit test pure logic — Extract business logic into plain Rust functions, test with #[cfg(test)]
2. Integration test against local instance — spacetime dev, then run client-side tests that call reducers
3. Separate test database — spacetime publish test-my-app for isolated testing
4. RLS testing — Use --anonymous flag to test as different identities

// Extract testable logic
fn validate_transfer(balance: f64, amount: f64) -> Result<(), String> {
    if amount <= 0.0 { return Err("Amount must be positive".into()); }
    if balance < amount { return Err("Insufficient funds".into()); }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_validate_transfer() {
        assert!(validate_transfer(100.0, 50.0).is_ok());
        assert!(validate_transfer(100.0, 150.0).is_err());
        assert!(validate_transfer(100.0, -10.0).is_err());
    }
}

Migration Strategy

See spacetimedb-concepts for the full migration philosophy.

Safe Changes (auto-migrated)

• Add a new table
• Add a column with a default value
• Add an index

Breaking Changes (require --delete-data)

• Remove a column
• Change a column type
• Remove a table with data

Incremental Migration Pattern

// Step 1: Create new table alongside old
#[table(name = users_v2, public)]
pub struct UserV2 {
    #[primary_key]
    pub id: u64,
    pub email: String,
    pub display_name: String, // renamed from 'name'
    pub role: UserRole,       // new field
}

// Step 2: Lazy migration reducer
#[reducer]
pub fn migrate_user(ctx: &ReducerContext, user_id: u64) -> Result<(), String> {
    if let Some(old) = ctx.db.users().id().find(user_id) {
        if ctx.db.users_v2().id().find(user_id).is_none() {
            ctx.db.users_v2().insert(UserV2 {
                id: old.id,
                email: old.email,
                display_name: old.name,
                role: UserRole::Member,
            })?;
        }
    }
    Ok(())
}

Performance

Index Strategy

// Good: indexed query
ctx.db.messages().idx_channel_time().filter(|m| m.channel_id == &channel_id);

// Bad: full table scan
ctx.db.messages().iter().filter(|m| m.channel_id == channel_id);

Rule: If you filter on a field, add #[index(btree)] to it.

Table Decomposition

Split hot and cold data:

// Good: separate hot (frequently read) from cold (rarely read) data
#[table(name = user_profiles, public)]
pub struct UserProfile {
    #[primary_key]
    pub user_id: u64,
    pub name: String,
    pub avatar_url: String,
}

#[table(name = user_settings)]
pub struct UserSettings {
    #[primary_key]
    pub user_id: u64,
    pub theme: String,
    pub notifications_enabled: bool,
}

Batching

When inserting many rows, do it in a single reducer call:

#[reducer]
pub fn bulk_insert(ctx: &ReducerContext, items: Vec<ItemData>) -> Result<(), String> {
    for item in items {
        ctx.db.items().insert(Item::from(item))?;
    }
    Ok(()) // Single transaction for all inserts
}

Common Pitfalls

References

• Tables Reference
• Reducers Reference
• Cheat Sheet
• Performance Best Practices
• Automatic Migrations