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.
Name | Description |
---|---|
Project setup | Configure a Rust crate to use the SpacetimeDB Rust client SDK. |
Generate module bindings | Use the SpacetimeDB CLI to generate module-specific types and interfaces. |
DbConnection type |
A connection to a remote database. |
DbContext trait |
Methods for interacting with the remote database. Implemented by DbConnection and various event context types. |
EventContext type |
DbContext available in row callbacks. |
ReducerEventContext type |
DbContext available in reducer callbacks. |
SubscriptionEventContext type |
DbContext available in subscription-related callbacks. |
ErrorContext type |
DbContext available in error-related callbacks. |
Access the client cache | Make local queries against subscribed rows, and register row callbacks to run when subscribed rows change. |
Observe and invoke reducers | Send requests to the database to run reducers, and register callbacks to run when notified of reducers. |
Identify a client | Types for identifying users and client connections. |
Project setup
First, create a new project using cargo new
and add the SpacetimeDB SDK to your dependencies:
cargo add spacetimedb_sdk
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;
Type `DbConnection`
module_bindings::DbConnection
A connection to a remote database is represented by the module_bindings::DbConnection
type. This type is generated per-module, and contains information about the types, tables and reducers defined by your module.
Name | Description |
---|---|
Connect to a module | Construct a DbConnection . |
Advance the connection | Poll the DbConnection , or set up a background worker to run it. |
Access tables and reducers | Access subscribed rows in the client cache, request reducer invocations, and register callbacks. |
Connect to a module
impl DbConnection {
fn builder() -> DbConnectionBuilder;
}
Construct a DbConnection
by calling DbConnection::builder()
and chaining configuration methods, then calling .build()
. You must at least specify with_uri
, to supply the URI of the SpacetimeDB to which you published your module, and with_module_name
, to supply the human-readable SpacetimeDB domain name or the raw Identity
which identifies the module.
Name | Description |
---|---|
with_uri method |
Set the URI of the SpacetimeDB instance which hosts the remote database. |
with_module_name method |
Set the name or Identity of the remote database. |
on_connect callback |
Register a callback to run when the connection is successfully established. |
on_connect_error callback |
Register a callback to run if the connection is rejected or the host is unreachable. |
on_disconnect callback |
Register a callback to run when the connection ends. |
with_token method |
Supply a token to authenticate with the remote database. |
build method |
Finalize configuration and connect. |
Method `with_uri`
impl DbConnectionBuilder {
fn with_uri(self, uri: impl TryInto<Uri>) -> Self;
}
Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module.
Method `with_module_name`
impl DbConnectionBuilder {
fn with_module_name(self, name_or_identity: impl ToString) -> Self;
}
Configure the SpacetimeDB domain name or Identity
of the remote module which identifies it within the SpacetimeDB instance or cluster.
Callback `on_connect`
impl DbConnectionBuilder {
fn on_connect(self, callback: impl FnOnce(&DbConnection, Identity, &str)) -> DbConnectionBuilder;
}
Chain a call to .on_connect(callback)
to your builder to register a callback to run when your new DbConnection
successfully initiates its connection to the remote module. The callback accepts three arguments: a reference to the DbConnection
, the Identity
by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to with_token
to authenticate the same user in future connections.
This interface may change in an upcoming release as we rework SpacetimeDB's authentication model.
Callback `on_connect_error`
impl DbConnectionBuilder {
fn on_connect_error(
self,
callback: impl FnOnce(&ErrorContext, spacetimedb_sdk::Error),
) -> DbConnectionBuilder;
}
Chain a call to .on_connect_error(callback)
to your builder to register a callback to run when your connection fails.
A known bug in the SpacetimeDB Rust client SDK currently causes this callback never to be invoked. on_disconnect
callbacks are invoked instead.
Callback `on_disconnect`
impl DbConnectionBuilder {
fn on_disconnect(
self,
callback: impl FnOnce(&ErrorContext, Option<spacetimedb_sdk::Error>),
) -> DbConnectionBuilder;
}
Chain a call to .on_disconnect(callback)
to your builder to register a callback to run when your DbConnection
disconnects from the remote module, either as a result of a call to disconnect
or due to an error.
Method `with_token`
impl DbConnectionBuilder {
fn with_token(self, token: Option<impl ToString>>) -> Self;
}
Chain a call to .with_token(token)
to your builder to provide an OpenID Connect compliant JSON Web Token to authenticate with, or to explicitly select an anonymous connection. If this method is not called or None
is passed, SpacetimeDB will generate a new Identity
and sign a new private access token for the connection.
Method `build`
impl DbConnectionBuilder {
fn build(self) -> Result<DbConnection, spacetimedb_sdk::Error>;
}
After configuring the connection and registering callbacks, attempt to open the connection.
Advance the connection and process messages
In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the DbConnection
spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the DbConnection
will never advance, and no callbacks will ever be invoked.
Name | Description |
---|---|
run_threaded method |
Spawn a thread to process messages in the background. |
run_async method |
Process messages in an async task. |
frame_tick method |
Process messages on the main thread without blocking. |
Method `run_threaded`
impl DbConnection {
fn run_threaded(&self) -> std::thread::JoinHandle<()>;
}
run_threaded
spawns a thread which will continuously advance the connection, sleeping when there is no work to do. The thread will panic if the connection disconnects erroneously, or return if it disconnects as a result of a call to disconnect
.
Method `run_async`
impl DbConnection {
async fn run_async(&self) -> Result<(), spacetimedb_sdk::Error>;
}
run_async
will continuously advance the connection, await
-ing when there is no work to do. The task will return an Err
if the connection disconnects erroneously, or return Ok(())
if it disconnects as a result of a call to disconnect
.
Method `frame_tick`
impl DbConnection {
fn frame_tick(&self) -> Result<(), spacetimedb_sdk::Error>;
}
frame_tick
will advance the connection until no work remains, then return rather than blocking or await
-ing. Games might arrange for this message to be called every frame. frame_tick
returns Ok
if the connection remains active afterwards, or Err
if the connection disconnected before or during the call.
Access tables and reducers
Field `db`
struct DbConnection {
pub db: RemoteTables,
/* other members */
}
The db
field of the DbConnection
provides access to the subscribed view of the remote database's tables. See Access the client cache.
Field `reducers`
struct DbConnection {
pub reducers: RemoteReducers,
/* other members */
}
The reducers
field of the DbConnection
provides access to reducers exposed by the remote module. See Observe and invoke reducers.
Trait `DbContext`
trait spacetimedb_sdk::DbContext {
/* methods */
}
DbConnection
, EventContext
, ReducerEventContext
, SubscriptionEventContext
and ErrorContext
all implement DbContext
. DbContext
has methods for inspecting and configuring your connection to the remote database, including ctx.db()
, a trait-generic alternative to reading the .db
property on a concrete-typed context object.
The DbContext
trait is implemented by connections and contexts to every module. This means that its DbView
and Reducers
are associated types.
Name | Description |
---|---|
RemoteDbContext trait |
Module-specific DbContext extension trait with associated types bound. |
db method |
Trait-generic alternative to the db field of DbConnection . |
reducers method |
Trait-generic alternative to the reducers field of DbConnection . |
disconnect method |
End the connection. |
Subscribe to queries | Register SQL queries to receive updates about matching rows. |
Read connection metadata | Access the connection's Identity and ConnectionId |
Trait `RemoteDbContext`
trait module_bindings::RemoteDbContext
: spacetimedb_sdk::DbContext</* Associated type constraints */> {}
Each module's module_bindings
exports a trait RemoteDbContext
which extends DbContext
, with the associated types DbView
and Reducers
bound to the types defined for that module. This can be more convenient when creating functions that can be called from any callback for a specific module, but which access the database or invoke reducers, and so must know the type of the DbView
or Reducers
.
Method `db`
trait DbContext {
fn db(&self) -> &Self::DbView;
}
When operating in trait-generic contexts, it is necessary to call the ctx.db()
method, rather than accessing the ctx.db
field, as Rust traits cannot expose fields.
Example
fn print_users(ctx: &impl RemoteDbContext) {
for user in ctx.db().user().iter() {
println!("{}", user.name);
}
}
Method `reducers`
trait DbContext {
fn reducerrs(&self) -> &Self::Reducers;
}
When operating in trait-generic contexts, it is necessary to call the ctx.reducers()
method, rather than accessing the ctx.reducers
field, as Rust traits cannot expose fields.
Example
fn call_say_hello(ctx: &impl RemoteDbContext) {
ctx.reducers.say_hello();
}
Method `disconnect`
trait DbContext {
fn disconnect(&self) -> spacetimedb_sdk::Result<()>;
}
Gracefully close the DbConnection
. Returns an Err
if the connection is already disconnected.
Subscribe to queries
Name | Description |
---|---|
SubscriptionBuilder type |
Builder-pattern constructor to register subscribed queries. |
SubscriptionHandle type |
Manage an active subscripion. |
Type `SubscriptionBuilder`
spacetimedb_sdk::SubscriptionBuilder
Name | Description |
---|---|
ctx.subscription_builder() constructor |
Begin configuring a new subscription. |
on_applied callback |
Register a callback to run when matching rows become available. |
on_error callback |
Register a callback to run if the subscription fails. |
subscribe method |
Finish configuration and subscribe to one or more SQL queries. |
subscribe_to_all_tables method |
Convenience method to subscribe to the entire database. |
Constructor `ctx.subscription_builder()`
trait DbContext {
fn subscription_builder(&self) -> SubscriptionBuilder;
}
Subscribe to queries by calling ctx.subscription_builder()
and chaining configuration methods, then calling .subscribe(queries)
.
Callback `on_applied`
impl SubscriptionBuilder {
fn on_applied(self, callback: impl FnOnce(&SubscriptionEventContext)) -> Self;
}
Register a callback to run when the subscription is applied and the matching rows are inserted into the client cache.
Callback `on_error`
impl SubscriptionBuilder {
fn on_error(self, callback: impl FnOnce(&ErrorContext, spacetimedb_sdk::Error)) -> Self;
}
Register a callback to run if the subscription is rejected or unexpectedly terminated by the server. This is most frequently caused by passing an invalid query to subscribe
.
Method `subscribe`
impl SubscriptionBuilder {
fn subscribe(self, queries: impl IntoQueries) -> SubscriptionHandle;
}
Subscribe to a set of queries. queries
should be a string or an array, vec or slice of strings.
See the SpacetimeDB SQL Reference for information on the queries SpacetimeDB supports as subscriptions.
Method `subscribe_to_all_tables`
impl SubscriptionBuilder {
fn subscribe_to_all_tables(self);
}
Subscribe to all rows from all public tables. This method is provided as a convenience for simple clients. The subscription initiated by subscribe_to_all_tables
cannot be canceled after it is initiated. You should subscribe
to specific queries if you need fine-grained control over the lifecycle of your subscriptions.
Type `SubscriptionHandle`
module_bindings::SubscriptionHandle
A SubscriptionHandle
represents a subscribed query or a group of subscribed queries.
The SubscriptionHandle
does not contain or provide access to the subscribed rows. Subscribed rows of all subscriptions by a connection are contained within that connection's ctx.db
. See Access the client cache.
Name | Description |
---|---|
is_ended method |
Determine whether the subscription has ended. |
is_active method |
Determine whether the subscription is active and its matching rows are present in the client cache. |
unsubscribe method |
Discard a subscription. |
unsubscribe_then method |
Discard a subscription, and register a callback to run when its matching rows are removed from the client cache. |
Method `is_ended`
impl SubscriptionHandle {
fn is_ended(&self) -> bool;
}
Returns true if this subscription has been terminated due to an unsubscribe call or an error.
Method `is_active`
impl SubscriptionHandle {
fn is_active(&self) -> bool;
}
Returns true if this subscription has been applied and has not yet been unsubscribed.
Method `unsubscribe`
impl SubscriptionHandle {
fn unsubscribe(&self) -> Result<(), spacetimedb_sdk::Error>;
}
Terminate this subscription, causing matching rows to be removed from the client cache. Any rows removed from the client cache this way will have on_delete
callbacks run for them.
Unsubscribing is an asynchronous operation. Matching rows are not removed from the client cache immediately. Use unsubscribe_then
to run a callback once the unsubscribe operation is completed.
Returns an error if the subscription has already ended, either due to a previous call to unsubscribe
or unsubscribe_then
, or due to an error.
Method `unsubscribe_then`
impl SubscriptionHandle {
fn unsubscribe_then(
self,
on_end: impl FnOnce(&SubscriptionEventContext),
) -> Result<(), spacetimedb_sdk::Error>;
}
Terminate this subscription, and run the on_end
callback when the subscription is ended and its matching rows are removed from the client cache. Any rows removed from the client cache this way will have on_delete
callbacks run for them.
Returns an error if the subscription has already ended, either due to a previous call to unsubscribe
or unsubscribe_then
, or due to an error.
Read connection metadata
Method `identity`
trait DbContext {
fn identity(&self) -> Identity;
}
Get the Identity
with which SpacetimeDB identifies the connection. This method may panic if the connection was initiated anonymously and the newly-generated Identity
has not yet been received, i.e. if called before the on_connect
callback is invoked.
Method `try_identity`
trait DbContext {
fn try_identity(&self) -> Option<Identity>;
}
Like DbContext::identity
, but returns None
instead of panicking if the Identity
is not yet available.
Method `connection_id`
trait DbContext {
fn connection_id(&self) -> ConnectionId;
}
Get the ConnectionId
with which SpacetimeDB identifies the connection.
Method `is_active`
trait DbContext {
fn is_active(&self) -> bool;
}
true
if the connection has not yet disconnected. Note that a connection is_active
when it is constructed, before its on_connect
callback is invoked.
Type `EventContext`
module_bindings::EventContext
An EventContext
is a DbContext
augmented with a field event: Event
. EventContext
s are passed as the first argument to row callbacks on_insert
, on_delete
and on_update
.
Name | Description |
---|---|
event field |
Enum describing the cause of the current row callback. |
db field |
Provides access to the client cache. |
reducers field |
Allows requesting reducers run on the remote database. |
Event enum |
Possible events which can cause a row callback to be invoked. |
Field `event`
struct EventContext {
pub event: spacetimedb_sdk::Event<module_bindings::Reducer>,
/* other fields */
}
The Event
contained in the EventContext
describes what happened to cause the current row callback to be invoked.
Field `db`
struct EventContext {
pub db: RemoteTables,
/* other members */
}
The db
field of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.
Field `reducers`
struct EventContext {
pub reducers: RemoteReducers,
/* other members */
}
The reducers
field of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.
Enum `Event`
spacetimedb_sdk::Event<module_bindings::Reducer>
Name | Description |
---|---|
Reducer variant |
A reducer ran in the remote database. |
SubscribeApplied variant |
A new subscription was applied to the client cache. |
UnsubscribeApplied variant |
A previous subscription was removed from the client cache after a call to unsubscribe . |
SubscribeError variant |
A previous subscription was removed from the client cache due to an error. |
UnknownTransaction variant |
A transaction ran in the remote database, but was not attributed to a known reducer. |
ReducerEvent struct |
Metadata about a reducer run. Contained in Event::Reducer and ReducerEventContext . |
Status enum |
Completion status of a reducer run. |
Reducer enum |
Module-specific generated enum with a variant for each reducer defined by the module. |
Variant `Reducer`
spacetimedb_sdk::Event::Reducer(spacetimedb_sdk::ReducerEvent<module_bindings::Reducer>)
Event when we are notified that a reducer ran in the remote module. The ReducerEvent
contains metadata about the reducer run, including its arguments and termination Status
.
This event is passed to row callbacks resulting from modifications by the reducer.
Variant `SubscribeApplied`
spacetimedb_sdk::Event::SubscribeApplied
Event when our subscription is applied and its rows are inserted into the client cache.
This event is passed to row on_insert
callbacks resulting from the new subscription.
Variant `UnsubscribeApplied`
spacetimedb_sdk::Event::UnsubscribeApplied
Event when our subscription is removed after a call to SubscriptionHandle::unsubscribe
or SubscriptionHandle::unsubscribe_then
and its matching rows are deleted from the client cache.
This event is passed to row on_delete
callbacks resulting from the subscription ending.
Variant `SubscribeError`
spacetimedb_sdk::Event::SubscribeError(spacetimedb_sdk::Error)
Event when a subscription ends unexpectedly due to an error.
This event is passed to row on_delete
callbacks resulting from the subscription ending.
Variant `UnknownTransaction`
Event when we are notified of a transaction in the remote module which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings.
This event is passed to row callbacks resulting from modifications by the transaction.
Struct `ReducerEvent`
spacetimedb_sdk::ReducerEvent<module_bindings::Reducer>
A ReducerEvent
contains metadata about a reducer run.
struct spacetimedb_sdk::ReducerEvent<R> {
/// The time at which the reducer was invoked.
timestamp: SystemTime,
/// Whether the reducer committed, was aborted due to insufficient energy, or failed with an error message.
status: Status,
/// The `Identity` of the SpacetimeDB actor which invoked the reducer.
caller_identity: Identity,
/// The `ConnectionId` of the SpacetimeDB actor which invoked the reducer,
/// or `None` for scheduled reducers.
caller_connection_id: Option<ConnectionId>,
/// The amount of energy consumed by the reducer run, in eV.
/// (Not literal eV, but our SpacetimeDB energy unit eV.)
///
/// May be `None` if the module is configured not to broadcast energy consumed.
energy_consumed: Option<u128>,
/// The `Reducer` enum defined by the `module_bindings`, which encodes which reducer ran and its arguments.
reducer: R,
// ...private fields
}
Enum `Status`
spacetimedb_sdk::Status
Name | Description |
---|---|
Committed variant |
The reducer ran successfully. |
Failed variant |
The reducer errored. |
OutOfEnergy variant |
The reducer was aborted due to insufficient energy. |
Variant `Committed`
spacetimedb_sdk::Status::Committed
The reducer returned successfully and its changes were committed into the database state. An Event::Reducer
passed to a row callback must have this status in its ReducerEvent
.
Variant `Failed`
spacetimedb_sdk::Status::Failed(Box<str>)
The reducer returned an error, panicked, or threw an exception. The enum payload is the stringified error message. Formatting of the error message is unstable and subject to change, so clients should use it only as a human-readable diagnostic, and in particular should not attempt to parse the message.
Variant `OutOfEnergy`
The reducer was aborted due to insufficient energy balance of the module owner.
Enum `Reducer`
module_bindings::Reducer
The module bindings contains an enum Reducer
with a variant for each reducer defined by the module. Each variant has a payload containing the arguments to the reducer.
Type `ReducerEventContext`
A ReducerEventContext
is a DbContext
augmented with a field event: ReducerEvent
. ReducerEventContext
s are passed as the first argument to reducer callbacks.
Name | Description |
---|---|
event field |
ReducerEvent containing reducer metadata. |
db field |
Provides access to the client cache. |
reducers field |
Allows requesting reducers run on the remote database. |
Field `event`
struct ReducerEventContext {
pub event: spacetimedb_sdk::ReducerEvent<module_bindings::Reducer>,
/* other fields */
}
The ReducerEvent
contained in the ReducerEventContext
has metadata about the reducer which ran.
Field `db`
struct ReducerEventContext {
pub db: RemoteTables,
/* other members */
}
The db
field of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.
Field `reducers`
struct ReducerEventContext {
pub reducers: RemoteReducers,
/* other members */
}
The reducers
field of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.
Type `SubscriptionEventContext`
A SubscriptionEventContext
is a DbContext
. Unlike the other context types, SubscriptionEventContext
doesn't have an event
field. SubscriptionEventContext
s are passed to subscription on_applied
and unsubscribe_then
callbacks.
Name | Description |
---|---|
db field |
Provides access to the client cache. |
reducers field |
Allows requesting reducers run on the remote database. |
Field `db`
struct SubscriptionEventContext {
pub db: RemoteTables,
/* other members */
}
The db
field of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.
Field `reducers`
struct SubscriptionEventContext {
pub reducers: RemoteReducers,
/* other members */
}
The reducers
field of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.
Type `ErrorContext`
An ErrorContext
is a DbContext
augmented with a field event: spacetimedb_sdk::Error
. ErrorContext
s are to connections' on_disconnect
and on_connect_error
callbacks, and to subscriptions' on_error
callbacks.
Name | Description |
---|---|
event field |
The error which caused the current error callback. |
db field |
Provides access to the client cache. |
reducers field |
Allows requesting reducers run on the remote database. |
Field `event`
struct ErrorContext {
pub event: spacetimedb_sdk::Error,
/* other fields */
}
Field `db`
struct ErrorContext {
pub db: RemoteTables,
/* other members */
}
The db
field of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.
Field `reducers`
struct ErrorContext {
pub reducers: RemoteReducers,
/* other members */
}
The reducers
field of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.
Access the client cache
All DbContext
implementors, including DbConnection
and EventContext
, have fields .db
, which in turn has methods for accessing tables in the client cache. The trait method DbContext::db(&self)
can also be used in contexts with an impl DbContext
rather than a concrete-typed EventContext
or DbConnection
.
Each table defined by a module has an accessor method, whose name is the table name converted to snake_case
, on this .db
field. The methods are defined via extension traits, which rustc
or your IDE should help you identify and import where necessary. The table accessor methods return table handles, which implement Table
, may implement TableWithPrimaryKey
, and have methods for searching by unique index.
Name | Description |
---|---|
Table trait |
Provides access to subscribed rows of a specific table within the client cache. |
TableWithPrimaryKey trait |
Extension trait for tables which have a column designated as a primary key. |
Unique constraint index access | Seek a subscribed row by the value in its unique or primary key column. |
BTree index access | Not supported. |
Trait `Table`
spacetimedb_sdk::Table
Implemented by all table handles.
Name | Description |
---|---|
Row associated type |
The type of rows in the table. |
count method |
The number of subscribed rows in the table. |
iter method |
Iterate over all subscribed rows in the table. |
on_insert callback |
Register a callback to run whenever a row is inserted into the client cache. |
on_delete callback |
Register a callback to run whenever a row is deleted from the client cache. |
Associated type `Row`
trait spacetimedb_sdk::Table {
type Table::Row;
}
The type of rows in the table.
Method `count`
trait spacetimedb_sdk::Table {
fn count(&self) -> u64;
}
Returns the number of rows of this table resident in the client cache, i.e. the total number which match any subscribed query.
Method `iter`
trait spacetimedb_sdk::Table {
fn iter(&self) -> impl Iterator<Item = Self::Row>;
}
An iterator over all the subscribed rows in the client cache, i.e. those which match any subscribed query.
Callback `on_insert`
trait spacetimedb_sdk::Table {
type InsertCallbackId;
fn on_insert(&self, callback: impl FnMut(&EventContext, &Self::Row)) -> Self::InsertCallbackId;
fn remove_on_insert(&self, callback: Self::InsertCallbackId);
}
The on_insert
callback runs whenever a new row is inserted into the client cache, either when applying a subscription or being notified of a transaction. The passed EventContext
contains an Event
which can identify the change which caused the insertion, and also allows the callback to interact with the connection, inspect the client cache and invoke reducers.
Registering an on_insert
callback returns a callback id, which can later be passed to remove_on_insert
to cancel the callback. Newly registered or canceled callbacks do not take effect until the following event.
Callback `on_delete`
trait spacetimedb_sdk::Table {
type DeleteCallbackId;
fn on_delete(&self, callback: impl FnMut(&EventContext, &Self::Row)) -> Self::DeleteCallbackId;
fn remove_on_delete(&self, callback: Self::DeleteCallbackId);
}
The on_delete
callback runs whenever a previously-resident row is deleted from the client cache. Registering an on_delete
callback returns a callback id, which can later be passed to remove_on_delete
to cancel the callback. Newly registered or canceled callbacks do not take effect until the following event.
Trait `TableWithPrimaryKey`
spacetimedb_sdk::TableWithPrimaryKey
Implemented for table handles whose tables have a primary key.
Name | Description |
---|---|
on_update callback |
Register a callback to run whenever a subscribed row is replaced with a new version. |
Callback `on_update`
trait spacetimedb_sdk::TableWithPrimaryKey {
type UpdateCallbackId;
fn on_update(&self, callback: impl FnMut(&EventContext, &Self::Row, &Self::Row)) -> Self::UpdateCallbackId;
fn remove_on_update(&self, callback: Self::UpdateCallbackId);
}
The on_update
callback runs whenever an already-resident row in the client cache is updated, i.e. replaced with a new row that has the same primary key. Registering an on_update
callback returns a callback id, which can later be passed to remove_on_update
to cancel the callback. Newly registered or canceled callbacks do not take effect until the following event.
Unique constraint index access
For each unique constraint on a table, its table handle has a method whose name is the unique column name which returns a unique index handle. The unique index handle has a method .find(desired_val: &Col) -> Option<Row>
, where Col
is the type of the column, and Row
the type of rows. If a row with desired_val
in the unique column is resident in the client cache, .find
returns it.
BTree index access
The SpacetimeDB Rust client SDK does not support non-unique BTree indexes.
Observe and invoke reducers
All DbContext
implementors, including DbConnection
and EventContext
, have fields .reducers
, which in turn has methods for invoking reducers defined by the module and registering callbacks on it. The trait method DbContext::reducers(&self)
can also be used in contexts with an impl DbContext
rather than a concrete-typed EventContext
or DbConnection
.
Each reducer defined by the module has three methods on the .reducers
:
- An invoke method, whose name is the reducer's name converted to snake case, like
set_name
. This requests that the module run the reducer. - A callback registation method, whose name is prefixed with
on_
, likeon_set_name
. This registers a callback to run whenever we are notified that the reducer ran, including successfully committed runs and runs we requested which failed. This method returns a callback id, which can be passed to the callback remove method. - A callback remove method, whose name is prefixed with
remove_on_
, likeremove_on_set_name
. This cancels a callback previously registered via the callback registration method.
Identify a client
Type `Identity`
spacetimedb_sdk::Identity
A unique public identifier for a client connected to a database.
Type `ConnectionId`
spacetimedb_sdk::ConnectionId
An opaque identifier for a client connection to a database, intended to differentiate between connections from the same Identity
.