dbos-rust

DBOS Rust Best Practices

Guide for building reliable, fault-tolerant Rust applications with DBOS durable workflows.

When to Apply

Reference these guidelines when:

• Adding DBOS to existing Rust code
• Creating workflows and steps
• Running DBOS calls concurrently inside a workflow
• Using queues for concurrency control
• Implementing workflow communication (events, messages, streams)
• Configuring and launching DBOS applications
• Using the DBOS Client from external applications
• Testing DBOS applications

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Lifecycle	CRITICAL	lifecycle-
2	Workflow	CRITICAL	workflow-
3	Step	HIGH	step-
4	Queue	HIGH	queue-
5	Communication	MEDIUM	comm-
6	Pattern	MEDIUM	pattern-
7	Testing	LOW-MEDIUM	test-
8	Client	MEDIUM	client-
9	Advanced	LOW	advanced-

Critical Rules

Installation

Add the dbos crate (0.6) and Tokio:

cargo add dbos
cargo add tokio --features full
cargo add serde --features derive
cargo add thiserror tracing-subscriber futures
cargo add --dev uuid --features v4

serde is for workflow inputs and outputs, thiserror for workflow error types, tracing-subscriber to see DBOS's logs, futures for joining DBOS calls (try_join_all), and uuid for fresh workflow IDs in tests.

DBOS runs on Tokio by default; smol and async-global-executor are Cargo features (see references/lifecycle-runtimes.md). DBOS for Rust does not support DBOS Conductor or DBOS Cloud.

DBOS Configuration and Launch

A DBOS application MUST create a DBOS instance, register every workflow, and launch before running any workflows:

use dbos::{Config, DBOS};

async fn my_workflow(_: ()) -> dbos::Result<String> {
    Ok("done".to_owned())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    // Reads the system database URL from DBOS_SYSTEM_DATABASE_URL.
    let mut config = Config::from_env("my-app");
    config.app_version = Some("0.1.0".to_owned());
    let dbos = DBOS::new(config);

    // Register every workflow before launch.
    let workflow = dbos.register_workflow("my_workflow", my_workflow)?;
    dbos.launch().await?;

    let result = workflow.run(()).await?;
    println!("{result}");

    dbos.shutdown().await;
    Ok(())
}