The SpacetimeDB Rust client SDK

The SpacetimeDB client SDK for Rust contains all the tools you need to build native clients for SpacetimeDB modules using Rust.

Install the SDK

First, create a new project using cargo new and add the SpacetimeDB SDK to your dependencies:

cargo add spacetimedb 
    

Generate module bindings

Each SpacetimeDB client depends on some bindings specific to your module. Create a module_bindings directory in your project's src directory and generate the Rust interface files using the Spacetime CLI. From your project directory, run:

mkdir -p src/module_bindings
spacetime generate --lang rust \
    --out-dir src/module_bindings \
    --project-path PATH-TO-MODULE-DIRECTORY 
    

Replace PATH-TO-MODULE-DIRECTORY with the path to your SpacetimeDB module.

Declare a mod for the bindings in your client's src/main.rs:

mod module_bindings; 
    

API at a glance

Connect to a database

Function connect

module_bindings::connect(
    spacetimedb_uri: impl TryInto<Uri>,
    db_name: &str,
    credentials: Option<Credentials>,
) -> anyhow::Result<()> 
    

Connect to a database named db_name accessible over the internet at the URI spacetimedb_uri.

If credentials are supplied, they will be passed to the new connection to identify and authenticate the user. Otherwise, a set of Credentials will be generated by the server.

const MODULE_NAME: &str = "my-module-name";

// Connect to a local DB with a fresh identity
connect("http://localhost:3000", MODULE_NAME, None)
    .expect("Connection failed");

// Connect to cloud with a fresh identity.
connect("https://testnet.spacetimedb.com", MODULE_NAME, None)
    .expect("Connection failed");

// Connect with a saved identity
const CREDENTIALS_DIR: &str = ".my-module";
connect(
    "https://testnet.spacetimedb.com",
    MODULE_NAME,
    load_credentials(CREDENTIALS_DIR)
        .expect("Error while loading credentials"),
).expect("Connection failed"); 
    

Function disconnect

spacetimedb_sdk::disconnect() 
    

Gracefully close the current WebSocket connection.

If there is no active connection, this operation does nothing.

connect(SPACETIMEDB_URI, MODULE_NAME, credentials)
    .expect("Connection failed");

run_app();

disconnect(); 
    

Function on_disconnect

spacetimedb_sdk::on_disconnect(
    callback: impl FnMut() + Send + 'static,
) -> DisconnectCallbackId 
    

Register a callback to be invoked when a connection ends.

The callback will be invoked after calling disconnect, or when a connection is closed by the server.

The returned DisconnectCallbackId can be passed to remove_on_disconnect to unregister the callback.

on_disconnect(|| println!("Disconnected!"));

connect(SPACETIMEDB_URI, MODULE_NAME, credentials)
    .expect("Connection failed");

disconnect();

// Will print "Disconnected!" 
    

Function once_on_disconnect

spacetimedb_sdk::once_on_disconnect(
    callback: impl FnOnce() + Send + 'static,
) -> DisconnectCallbackId 
    

Register a callback to be invoked the next time a connection ends.

The callback will be invoked after calling disconnect, or when a connection is closed by the server.

The callback will be unregistered after running.

The returned DisconnectCallbackId can be passed to remove_on_disconnect to unregister the callback.

once_on_disconnect(|| println!("Disconnected!"));

connect(SPACETIMEDB_URI, MODULE_NAME, credentials)
    .expect("Connection failed");

disconnect();

// Will print "Disconnected!"

connect(SPACETIMEDB_URI, MODULE_NAME, credentials)
    .expect("Connection failed");

disconnect();

// Nothing printed this time. 
    

Function remove_on_disconnect

spacetimedb_sdk::remove_on_disconnect(
    id: DisconnectCallbackId,
) 
    

Unregister a previously-registered on_disconnect callback.

If id does not refer to a currently-registered callback, this operation does nothing.

let id = on_disconnect(|| unreachable!());

remove_on_disconnect(id);

disconnect();

// No `unreachable` panic. 
    

Subscribe to queries

Function subscribe

spacetimedb_sdk::subscribe(queries: &[&str]) -> anyhow::Result<()> 
    

Subscribe to a set of queries, to be notified when rows which match those queries are altered.

The queries should be a slice of strings representing SQL queries.

subscribe will return an error if called before establishing a connection with the autogenerated connect function. In that case, the queries are not registered.

subscribe does not return data directly. The SDK will generate types module_bindings::{TABLE} corresponding to each of the tables in your module. These types implement the trait spacetimedb_sdk::table_type::TableType, which contains methods such as TableType::on_insert. Use these methods to receive data from the queries you subscribe to.

A new call to subscribe (or subscribe_owned) will remove all previous subscriptions and replace them with the new queries. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and TableType::on_delete callbacks will be invoked for them.

subscribe(&["SELECT * FROM User;", "SELECT * FROM Message;"])
    .expect("Called `subscribe` before `connect`"); 
    

Function subscribe_owned

spacetimedb_sdk::subscribe_owned(queries: Vec<String>) -> anyhow::Result<()> 
    

Subscribe to a set of queries, to be notified when rows which match those queries are altered.

The queries should be a Vec of Strings representing SQL queries.

A new call to subscribe_owned (or subscribe) will remove all previous subscriptions and replace them with the new queries. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and TableType::on_delete callbacks will be invoked for them.

subscribe_owned will return an error if called before establishing a connection with the autogenerated connect function. In that case, the queries are not registered.

let query = format!("SELECT * FROM User WHERE name = '{}';", compute_my_name());

subscribe_owned(vec![query])
    .expect("Called `subscribe_owned` before `connect`"); 
    

Function on_subscription_applied

spacetimedb_sdk::on_subscription_applied(
    callback: impl FnMut() + Send + 'static,
) -> SubscriptionCallbackId 
    

Register a callback to be invoked the first time a subscription's matching rows becoming available.

The callback will be invoked after a successful subscribe or subscribe_owned call when the initial set of matching rows becomes available.

The returned SubscriptionCallbackId can be passed to remove_on_subscription_applied to unregister the callback.

on_subscription_applied(|| println!("Subscription applied!"));

subscribe(&["SELECT * FROM User;"])
    .expect("Called `subscribe` before `connect`");

sleep(Duration::from_secs(1));

// Will print "Subscription applied!"

subscribe(&["SELECT * FROM User;", "SELECT * FROM Message;"])
    .expect("Called `subscribe` before `connect`");

// Will print again. 
    

Function once_on_subscription_applied

spacetimedb_sdk::once_on_subscription_applied(
    callback: impl FnOnce() + Send + 'static,
) -> SubscriptionCallbackId 
    

Register a callback to be invoked the next time a subscription's matching rows become available.

The callback will be invoked after a successful subscribe or subscribe_owned call when the initial set of matching rows becomes available.

The callback will be unregistered after running.

The returned SubscriptionCallbackId can be passed to remove_on_subscription_applied to unregister the callback.

once_on_subscription_applied(|| println!("Subscription applied!"));

subscribe(&["SELECT * FROM User;"])
    .expect("Called `subscribe` before `connect`");

sleep(Duration::from_secs(1));

// Will print "Subscription applied!"

subscribe(&["SELECT * FROM User;", "SELECT * FROM Message;"])
    .expect("Called `subscribe` before `connect`");

// Nothing printed this time. 
    

Function remove_on_subscription_applied

spacetimedb_sdk::remove_on_subscription_applied(
    id: SubscriptionCallbackId,
) 
    

Unregister a previously-registered on_subscription_applied callback.

If id does not refer to a currently-registered callback, this operation does nothing.

let id = on_subscription_applied(|| println!("Subscription applied!"));

subscribe(&["SELECT * FROM User;"])
    .expect("Called `subscribe` before `connect`");

sleep(Duration::from_secs(1));

// Will print "Subscription applied!"

remove_on_subscription_applied(id);

subscribe(&["SELECT * FROM User;", "SELECT * FROM Message;"])
    .expect("Called `subscribe` before `connect`");

// Nothing printed this time. 
    

Identify a client

Type Identity

spacetimedb_sdk::identity::Identity 
    

A unique public identifier for a client connected to a database.

Type Token

spacetimedb_sdk::identity::Token 
    

A private access token for a client connected to a database.

Type Credentials

spacetimedb_sdk::identity::Credentials 
    

Credentials, including a private access token, sufficient to authenticate a client connected to a database.

Type Address

spacetimedb_sdk::Address 
    

An opaque identifier for a client connection to a database, intended to differentiate between connections from the same Identity.

Function identity

spacetimedb_sdk::identity::identity() -> Result<Identity> 
    

Read the current connection's public Identity.

Returns an error if:

• connect has not yet been called.
• We connected anonymously, and we have not yet received our credentials.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

println!("My identity is {:?}", identity());

// Prints "My identity is Ok(Identity { bytes: [...several u8s...] })" 
    

Function token

spacetimedb_sdk::identity::token() -> Result<Token> 
    

Read the current connection's private Token.

Returns an error if:

• connect has not yet been called.
• We connected anonymously, and we have not yet received our credentials.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

println!("My token is {:?}", token());

// Prints "My token is Ok(Token {string: "...several Base64 digits..." })" 
    

Function credentials

spacetimedb_sdk::identity::credentials() -> Result<Credentials> 
    

Read the current connection's Credentials, including a public Identity and a private Token.

Returns an error if:

• connect has not yet been called.
• We connected anonymously, and we have not yet received our credentials.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

println!("My credentials are {:?}", credentials());

// Prints "My credentials are Ok(Credentials {
//        identity: Identity { bytes: [...several u8s...] },
//        token: Token { string: "...several Base64 digits..."},
// })" 
    

Function address

spacetimedb_sdk::identity::address() -> Result<Address> 
    

Read the current connection's Address.

Returns an error if connect has not yet been called.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

println!("My address is {:?}", address()); 
    

Function on_connect

spacetimedb_sdk::identity::on_connect(
    callback: impl FnMut(&Credentials, Address) + Send + 'static,
) -> ConnectCallbackId 
    

Register a callback to be invoked upon authentication with the database.

The callback will be invoked with the Credentials and Address provided by the database to identify this connection. If Credentials were supplied to connect, those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of Credentials will be generated by the database to identify this user.

The Credentials passed to the callback can be saved and used to authenticate the same user in future connections.

The returned ConnectCallbackId can be passed to remove_on_connect to unregister the callback.

on_connect(
    |creds, addr|
        println!("Successfully connected! My credentials are: {:?} and my address is: {:?}", creds, addr)
);

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

// Will print "Successfully connected! My credentials are: "
// followed by a printed representation of the client's `Credentials`. 
    

Function once_on_connect

spacetimedb_sdk::identity::once_on_connect(
    callback: impl FnOnce(&Credentials, Address) + Send + 'static,
) -> ConnectCallbackId 
    

Register a callback to be invoked once upon authentication with the database.

The callback will be invoked with the Credentials and Address provided by the database to identify this connection. If Credentials were supplied to connect, those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of Credentials will be generated by the database to identify this user.

The Credentials passed to the callback can be saved and used to authenticate the same user in future connections.

The callback will be unregistered after running.

The returned ConnectCallbackId can be passed to remove_on_connect to unregister the callback.

Function remove_on_connect

spacetimedb_sdk::identity::remove_on_connect(id: ConnectCallbackId) 
    

Unregister a previously-registered on_connect or once_on_connect callback.

If id does not refer to a currently-registered callback, this operation does nothing.

let id = on_connect(|_creds, _addr| unreachable!());

remove_on_connect(id);

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

sleep(Duration::from_secs(1));

// No `unreachable` panic. 
    

Function load_credentials

spacetimedb_sdk::identity::load_credentials(
    dirname: &str,
) -> Result<Option<Credentials>> 
    

Load a saved Credentials from a file within ~/dirname, if one exists.

dirname is treated as a directory in the user's home directory. If it contains a file named credentials, that file is treated as a BSATN-encoded Credentials, deserialized and returned. These files are created by save_credentials with the same dirname argument.

Returns Ok(None) if the directory or the credentials file does not exist. Returns Err when IO or deserialization fails. The returned Result may be unwrapped, and the contained Option passed to connect.

const CREDENTIALS_DIR = ".my-module";

let creds = load_credentials(CREDENTIALS_DIR)
    .expect("Error while loading credentials");

connect(SPACETIMEDB_URI, DB_NAME, creds)
    .expect("Failed to connect"); 
    

Function save_credentials

spacetimedb_sdk::identity::save_credentials(
    dirname: &str,
    credentials: &Credentials,
) -> Result<()> 
    

Store a Credentials to a file within ~/dirname, to be later loaded with load_credentials.

dirname is treated as a directory in the user's home directory. The directory is created if it does not already exists. A file within it named credentials is created or replaced, containing creds encoded as BSATN. The saved credentials can be retrieved by load_credentials with the same dirname argument.

Returns Err when IO or serialization fails.

const CREDENTIALS_DIR = ".my-module";

let creds = load_credentials(CREDENTIALS_DIRectory)
    .expect("Error while loading credentials");

on_connect(|creds, _addr| {
    if let Err(e) = save_credentials(CREDENTIALS_DIR, creds) {
        eprintln!("Error while saving credentials: {:?}", e);
    }
});

connect(SPACETIMEDB_URI, DB_NAME, creds)
    .expect("Failed to connect"); 
    

View subscribed rows of tables

Type {TABLE}

module_bindings::{TABLE} 
    

For each table defined by a module, spacetime generate generates a struct in the module_bindings mod whose name is that table's name converted to PascalCase. The generated struct has a field for each of the table's columns, whose names are the column names converted to snake_case.

Method filter_by_{COLUMN}

module_bindings::{TABLE}::filter_by_{COLUMN}(
    value: {COLUMN_TYPE},
) -> impl Iterator<Item = {TABLE}> 
    

For each column of a table, spacetime generate generates a static method on the table struct to filter subscribed rows where that column matches a requested value.

These methods are named filter_by_{COLUMN}, where {COLUMN} is the column name converted to snake_case. The method's return type is an Iterator over the {TABLE} rows which match the requested value.

Method find_by_{COLUMN}

module_bindings::{TABLE}::find_by_{COLUMN}(
    value: {COLUMN_TYPE},
) -> {FILTER_RESULT}<{TABLE}> 
    

For each unique column of a table (those annotated #[unique] and #[primarykey]), spacetime generate generates a static method on the table struct to seek a subscribed row where that column matches a requested value.

These methods are named find_by_{COLUMN}, where {COLUMN} is the column name converted to snake_case. The method's return type is Option<{TABLE}>.

Trait TableType

spacetimedb_sdk::table::TableType 
    

Every generated table struct implements the trait TableType.

Method count

TableType::count() -> usize 
    

Return the number of subscribed rows in the table, or 0 if there is no active connection.

This method acquires a global lock.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

on_subscription_applied(|| println!("There are {} users", User::count()));

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// Will the number of `User` rows in the database. 
    

Method iter

TableType::iter() -> impl Iterator<Item = Self> 
    

Iterate over all the subscribed rows in the table.

This method acquires a global lock, but the iterator does not hold it.

This method must heap-allocate enough memory to hold all of the rows being iterated over. TableType::filter allocates significantly less, so prefer it when possible.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

on_subscription_applied(|| for user in User::iter() {
    println!("{:?}", user);
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// Will print a line for each `User` row in the database. 
    

Method filter

TableType::filter(
    predicate: impl FnMut(&Self) -> bool,
) -> impl Iterator<Item = Self> 
    

Iterate over the subscribed rows in the table for which predicate returns true.

This method acquires a global lock, and the predicate runs while the lock is held. The returned iterator does not hold the lock.

The predicate is called eagerly for each subscribed row in the table, even if the returned iterator is never consumed.

This method must heap-allocate enough memory to hold all of the matching rows, but does not allocate space for subscribed rows which do not match the predicate.

Client authors should prefer calling tables' generated filter_by_{COLUMN} methods when possible rather than calling TableType::filter.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

on_subscription_applied(|| {
    for user in User::filter(|user| user.age >= 30
                                    && user.country == Country::USA) {
        println!("{:?}", user);
    }
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// Will print a line for each `User` row in the database
// who is at least 30 years old and who lives in the United States. 
    

Method find

TableType::find(
    predicate: impl FnMut(&Self) -> bool,
) -> Option<Self> 
    

Locate a subscribed row for which predicate returns true, if one exists.

This method acquires a global lock.

If multiple subscribed rows match predicate, one is chosen arbitrarily. The choice may not be stable across different calls to find with the same predicate.

Client authors should prefer calling tables' generated find_by_{COLUMN} methods when possible rather than calling TableType::find.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

on_subscription_applied(|| {
    if let Some(tyler) = User::find(|user| user.first_name == "Tyler"
                                           && user.surname == "Cloutier") {
        println!("Found Tyler: {:?}", tyler);
    } else {
        println!("Tyler isn't registered :(");
    }
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// Will tell us whether Tyler Cloutier is registered in the database. 
    

Method on_insert

TableType::on_insert(
    callback: impl FnMut(&Self, Option<&ReducerEvent>) + Send + 'static,
) -> InsertCallbackId<Self> 
    

Register an on_insert callback for when a subscribed row is newly inserted into the database.

The callback takes two arguments:

• row: &Self, the newly-inserted row value.
• reducer_event: Option<&ReducerEvent>, the ReducerEvent which caused this row to be inserted, or None if this row is being inserted while initializing a subscription.

The returned InsertCallbackId can be passed to remove_on_insert to remove the callback.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

User::on_insert(|user, reducer_event| {
    if let Some(reducer_event) = reducer_event {
        println!("New user inserted by reducer {:?}: {:?}", reducer_event, user);
    } else {
        println!("New user received during subscription update: {:?}", user);
    }
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// Will print a note whenever a new `User` row is inserted. 
    

Method remove_on_insert

TableType::remove_on_insert(id: InsertCallbackId<Self>) 
    

Unregister a previously-registered on_insert callback.

If id does not refer to a currently-registered callback, this operation does nothing.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

let id = User::on_insert(|_, _| unreachable!());

User::remove_on_insert(id);

subscribe(&["SELECT * FROM User;"])
    .unwrap();

sleep(Duration::from_secs(1));

// No `unreachable` panic. 
    

Method on_delete

TableType::on_delete(
    callback: impl FnMut(&Self, Option<&ReducerEvent>) + Send + 'static,
) -> DeleteCallbackId<Self> 
    

Register an on_delete callback for when a subscribed row is removed from the database.

The callback takes two arguments:

• row: &Self, the previously-present row which is no longer resident in the database.
• reducer_event: Option<&ReducerEvent>, the ReducerEvent which caused this row to be deleted, or None if this row was previously subscribed but no longer matches the new queries while initializing a subscription.

The returned DeleteCallbackId can be passed to remove_on_delete to remove the callback.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

User::on_delete(|user, reducer_event| {
    if let Some(reducer_event) = reducer_event {
        println!("User deleted by reducer {:?}: {:?}", reducer_event, user);
    } else {
        println!("User no longer subscribed during subscription update: {:?}", user);
    }
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

// Invoke a reducer which will delete a `User` row.
delete_user_by_name("Tyler Cloutier".to_string());

sleep(Duration::from_secs(1));

// Will print a note whenever a `User` row is inserted,
// including "User deleted by reducer ReducerEvent::DeleteUserByName(
//     DeleteUserByNameArgs { name: "Tyler Cloutier" }
// ): User { first_name: "Tyler", surname: "Cloutier" }" 
    

Method remove_on_delete

TableType::remove_on_delete(id: DeleteCallbackId<Self>) 
    

Unregister a previously-registered on_delete callback.

If id does not refer to a currently-registered callback, this operation does nothing.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

let id = User::on_delete(|_, _| unreachable!());

User::remove_on_delete(id);

subscribe(&["SELECT * FROM User;"])
    .unwrap();

// Invoke a reducer which will delete a `User` row.
delete_user_by_name("Tyler Cloutier".to_string());

sleep(Duration::from_secs(1));

// No `unreachable` panic. 
    

Trait TableWithPrimaryKey

spacetimedb_sdk::table::TableWithPrimaryKey 
    

Generated table structs with a column designated #[primarykey] implement the trait TableWithPrimaryKey.

Method on_update

TableWithPrimaryKey::on_update(
    callback: impl FnMut(&Self, &Self, Option<&Self::ReducerEvent>) + Send + 'static,
) -> UpdateCallbackId<Self> 
    

Register an on_update callback for when an existing row is modified.

The callback takes three arguments:

• old: &Self, the previous row value which has been replaced in the database.
• new: &Self, the updated row value which is now resident in the database.
• reducer_event: Option<&ReducerEvent>, the ReducerEvent which caused this row to be inserted.

The returned UpdateCallbackId can be passed to remove_on_update to remove the callback.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

User::on_update(|old, new, reducer_event| {
    println!("User updated by reducer {:?}: from {:?} to {:?}", reducer_event, old, new);
});

subscribe(&["SELECT * FROM User;"])
    .unwrap();

// Prints a line whenever a `User` row is updated by primary key. 
    

Method remove_on_update

TableWithPrimaryKey::remove_on_update(id: UpdateCallbackId<Self>) 
    

Unregister a previously-registered on_update callback.

If id does not refer to a currently-registered callback, this operation does nothing.

connect(SPACETIMEDB_URI, DB_NAME, None)
    .expect("Failed to connect");

let id = User::on_update(|_, _, _| unreachable!);

User::remove_on_update(id);

subscribe(&["SELECT * FROM User;"])
    .unwrap();

// No `unreachable` panic. 
    

Observe and request reducer invocations

Type ReducerEvent

module_bindings::ReducerEvent 
    

spacetime generate defines an enum ReducerEvent with a variant for each reducer defined by a module. The variant's name will be the reducer's name converted to PascalCase, and the variant will hold an instance of the autogenerated reducer arguments struct for that reducer.

on_insert, on_delete and on_update callbacks accept an Option<&ReducerEvent> which identifies the reducer which caused the row to be inserted, deleted or updated.

Type {REDUCER}Args

module_bindings::{REDUCER}Args 
    

For each reducer defined by a module, spacetime generate generates a struct whose name is that reducer's name converted to PascalCase, suffixed with Args. The generated struct has a field for each of the reducer's arguments, whose names are the argument names converted to snake_case.

For reducers which accept a ReducerContext as their first argument, the ReducerContext is not included in the arguments struct.

Function {REDUCER}

module_bindings::{REDUCER}({ARGS...}) 
    

For each reducer defined by a module, spacetime generate generates a function which sends a request to the database to invoke that reducer. The generated function's name is the reducer's name converted to snake_case.

For reducers which accept a ReducerContext as their first argument, the ReducerContext is not included in the generated function's argument list.

Function on_{REDUCER}

module_bindings::on_{REDUCER}(
    callback: impl FnMut(&Identity, Option<Address>, Status, {&ARGS...}) + Send + 'static,
) -> ReducerCallbackId<{REDUCER}Args> 
    

For each reducer defined by a module, spacetime generate generates a function which registers a FnMut callback to run each time the reducer is invoked. The generated functions are named on_{REDUCER}, where {REDUCER} is the reducer's name converted to snake_case.

The callback always accepts three arguments:

• caller_id: &Identity, the Identity of the client which invoked the reducer.
• caller_address: Option<Address>, the Address of the client which invoked the reducer. This may be None for scheduled reducers.

In addition, the callback accepts a reference to each of the reducer's arguments.

Clients will only be notified of reducer runs if either of two criteria is met:

• The reducer inserted, deleted or updated at least one row to which the client is subscribed.
• The reducer invocation was requested by this client, and the run failed.

The on_{REDUCER} function returns a ReducerCallbackId<{REDUCER}Args>, where {REDUCER}Args is the generated reducer arguments struct. This ReducerCallbackId can be passed to the generated remove_on_{REDUCER} function to cancel the callback.

Function once_on_{REDUCER}

module_bindings::once_on_{REDUCER}(
    callback: impl FnOnce(&Identity, Option<Address>, &Status, {&ARGS...}) + Send + 'static,
) -> ReducerCallbackId<{REDUCER}Args> 
    

For each reducer defined by a module, spacetime generate generates a function which registers a FnOnce callback to run the next time the reducer is invoked. The generated functions are named once_on_{REDUCER}, where {REDUCER} is the reducer's name converted to snake_case.

The callback accepts the same arguments as an on-reducer callback, but may be a FnOnce rather than a FnMut.

The callback will be invoked in the same circumstances as an on-reducer callback.

The once_on_{REDUCER} function returns a ReducerCallbackId<{REDUCER}Args>, where {REDUCER}Args is the generated reducer arguments struct. This ReducerCallbackId can be passed to the generated remove_on_{REDUCER} function to cancel the callback.

Function remove_on_{REDUCER}

module_bindings::remove_on_{REDUCER}(id: ReducerCallbackId<{REDUCER}Args>) 
    

For each reducer defined by a module, spacetime generate generates a function which unregisters a previously-registered on-reducer or once-on-reducer callback.

If id does not refer to a currently-registered callback, this operation does nothing.

Type Status

spacetimedb_sdk::reducer::Status 
    

An enum whose variants represent possible reducer completion statuses.

A Status is passed as the second argument to on_{REDUCER} and once_on_{REDUCER} callbacks.

Variant Status::Committed

The reducer finished successfully, and its row changes were committed to the database.

Variant Status::Failed(String)

The reducer failed, either by panicking or returning an Err.

Variant Status::OutOfEnergy

The reducer was canceled because the module owner had insufficient energy to allow it to run to completion.