dbos-rust
/dbos-rust
DBOS Rust SDK (the dbos crate) for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Rust code with DBOS, creating workflows and steps, using queues, using the DBOS Client from external applications, or building Rust applications that need to be resilient to failures.
- Author
- dbos-inc ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 43
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
DBOS Rust SDK (the dbos crate) for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Rust code with DBOS, creating workflows and steps, using queues, using the DBOS Client from external applications, or building Rust applications that need to be resilient to failures.
Original author description
DBOS Rust SDK (the dbos crate) for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Rust code with DBOS, creating workflows and steps, using queues, using the DBOS Client from external applications, or building Rust applications that need to be resilient to failures.
How it works
- When to Apply
- Rule Categories by Priority
- Critical Rules
- How to Use
- References
SKILL.md preview
---
name: dbos-rust
description: DBOS Rust SDK (the dbos crate) for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Rust code with DBOS, creating workflows and steps, using queues, using the DBOS Client from external applications, or building Rust applications that need to be resilient to failures.
license: MIT
metadata:
author: dbos
version: "0.6.0"
organization: DBOS
date: November 2026
abstract: Comprehensive guide for building fault-tolerant Rust applications with DBOS. Covers workflows, steps, queues, communication patterns, the determinism rules async Rust makes easy to break, and best practices for durable execution.
---
# 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:
```bash
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:
```rust
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(())
}
```
An application version is REQUIRED: DBOS for Rust doesn't compute one, so set `config.app_version` (or `DBOS__APPVERSION`) or `launch` fails. When creating a new application, set it to `"0.1.0"` or `env!("CARGO_PKG_VERSION")`. When editing an existing application, leave its configured version alone: changing it is a deployment decision (see `references/advanced-application-versions.md`).
`Config::from_env(app_name)` reads the system database URL from `DBOS_SYSTEM_DATABASE_URL`; DBOS creates the database if it doesn't exist. See `references/lifecycle-config.md` for all configuration options.
`DBOS` is cheap to clone. Outside a workflow, call its methods (`dbos.send`, `dbos.cancel`, `dbos.list_workflows`, queue and schedule management, ...); queue, schedule and app-version management have no free-function forms; from another application, use a `Client` (see `references/client-setup.md`).
### Workflow and Step Structure
A workflow is an `async` function of one input that returns a `dbos::Result`. Any function performing complex operations or accessing external services must run as a step with `dbos::step`:
```rust
async fn generate_random_number(n: u32) -> dbos::Result<u32> {
Ok(rand::random_range(0..n))
}
async fn workflow_function(n: u32) -> dbos::Result<u32> {
// The closure passes arguments into the step function.
let random_number = step("generate_random_number", || generate_random_number(n)).await?;
Ok(random_number)
}
```
Inputs, outputs and error types must implement `serde::Serialize` and `serde::Deserialize`; an application error type must also implement `std::error::Error` (see `references/workflow-errors.md`).
### Key Constraints
- Workflows MUST be deterministic: non-deterministic operations go in steps
- Do NOT race, time out, spawn, or consume in completion order any DBOS call in a workflow body: no `tokio::select!`, `tokio::time::timeout`, `FuturesUnordered`, `buffer_unordered` or `tokio::spawn` around DBOS calls. Use `dbos::select_step!` to race, `tokio::join!` / `futures::future::try_join_all` to run concurrently, and `dbos::sleep` to wait (see `references/workflow-concurrency.md`)
- Every DBOS call takes its step ID where it is built, not where it is awaited; `dbos::patch`, `dbos::deprecate_patch` and a debouncer's `debounce` are the exceptions, so await those on their own, never inside a join
- A workflow's future must be `Send + 'static`: don't hold an `Rc`, a `std::sync::MutexGuard` or a borrow across an `.await` in a workflow body
- To start a child workflow, capture its `WorkflowRef` in the parent's registered closure; a `WorkflowRef` can't be a workflow's input
- Do NOT start or enqueue workflows, or call `dbos::recv`, `dbos::set_event` or `dbos::patch`, from within steps (`Error::InsideStep`)
- Do NOT capture the `DBOS` instance in a workflow closure: use the free functions (`dbos::send`, `dbos::cancel_workflow`, ...), which need none (see `references/workflow-capture.md`)
- All workflows MUST be registered before `launch`; queues are registered and schedules created after it
- Do NOT modify global variables from workflows or steps
- Starting a workflow with an ID already in use returns the existing workflow by default; set `workflow_id_reuse_policy: WorkflowIdReusePolicy::Reject` to get `dbos::sysdb::Error::WorkflowIdInUse` instead (see `references/pattern-idempotency.md`)
- A panic in a workflow does not crash the process: the workflow stays `PENDING`, like a crash, and is recovered on the next launch
- Steps are at-least-once and there is no transactional step: make database writes in steps idempotent
## How to Use
Read individual rule files for detailed explanations and examples:
```
references/lifecycle-config.md
references/workflow-determinism.md
references/workflow-concurrency.md
references/queue-concurrency.md
references/workflow-control.md
```
## References
- https://docs.dbos.dev/
- https://docs.rs/dbos
- https://github.com/dbos-inc/dbos-transact-rust
Files in this package (43)
- AGENTS.md 3 KB
- CLAUDE.md 1 KB
- SKILL.md 7 KB
- references/_sections.md 2 KB
- references/advanced-application-versions.md 1 KB
- references/advanced-interops.md 2 KB
- references/advanced-patching.md 2 KB
- references/advanced-serialization.md 2 KB
- references/advanced-shared-database.md 1 KB
- references/advanced-versioning.md 2 KB
- references/client-enqueue.md 2 KB
- references/client-setup.md 2 KB
- references/comm-events.md 2 KB
- references/comm-messages.md 2 KB
- references/comm-streaming.md 2 KB
- references/lifecycle-config.md 3 KB
- references/lifecycle-runtimes.md 2 KB
- references/pattern-debouncing.md 2 KB
- references/pattern-delayed-execution.md 1 KB
- references/pattern-idempotency.md 2 KB
- references/pattern-scheduled.md 2 KB
- references/pattern-sleep.md 1 KB
- references/queue-basics.md 2 KB
- references/queue-concurrency.md 2 KB
- references/queue-deduplication.md 2 KB
- references/queue-listening.md 1 KB
- references/queue-partitioning.md 2 KB
- references/queue-priority.md 1 KB
- references/queue-rate-limiting.md 1 KB
- references/step-basics.md 2 KB
- references/step-concurrency.md 2 KB
- references/step-retries.md 3 KB
- references/test-setup.md 3 KB
- references/workflow-attributes.md 2 KB
- references/workflow-background.md 1 KB
- references/workflow-capture.md 2 KB
- references/workflow-concurrency.md 5 KB
- references/workflow-constraints.md 3 KB
- references/workflow-control.md 3 KB
- references/workflow-determinism.md 2 KB
- references/workflow-errors.md 2 KB
- references/workflow-introspection.md 1 KB
- references/workflow-timeout.md 2 KB
Versions
The database has no other skills named dbos-rust.
Database snapshot: 13.11.2026 · package version d8d3e9acf1bc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100dbos-golang
DBOS Go SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Go code with DBOS, creating workflows and steps, using queues, using the DBOS Client from external applications, or building Go applications that need to be resilient to failures. - 100dbos-typescript
DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, using DBOSClient from external applications, or building applications that need to be… - 100dbos-golang
DBOS Go SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Go code with DBOS, creating workflows and steps, using queues, using the DBOS Clie... - 100dbos-python
Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows. Use when adding DBOS to existing Python code, creating workflows and steps, or using queues for concurrency control. - 100dbos-python
Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows. Use when adding DBOS to existing Python code, creating workflows and steps, or using queues for concurrency control. - 100dbos-python
DBOS Python SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Python code with DBOS, creating workflows and steps, using queues, using DBOSC...