Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
43
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

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

  1. When to Apply
  2. Rule Categories by Priority
  3. Critical Rules
  4. How to Use
  5. References
Original SKILL.md headings · 138 lines, 846 words
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...

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.