Dbos Python

1---
2name: dbos-python
3description: 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 DBOSClient from external applications, or building applications that need to be resilient to failures.
4risk: safe
5source: https://docs.dbos.dev/
6license: MIT
7metadata:
8  author: dbos
9  version: "1.0.0"
10  organization: DBOS
11  date: January 2026
12  abstract: Comprehensive guide for building fault-tolerant Python applications with DBOS. Covers workflows, steps, queues, communication patterns, and best practices for durable execution.
13---
14 
15# DBOS Python Best Practices
16 
17Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows.
18 
19## When to Use
20 
21Reference these guidelines when:
22- Adding DBOS to existing Python code
23- Creating workflows and steps
24- Using queues for concurrency control
25- Implementing workflow communication (events, messages, streams)
26- Configuring and launching DBOS applications
27- Using DBOSClient from external applications
28- Testing DBOS applications
29 
30## Rule Categories by Priority
31 
32| Priority | Category | Impact | Prefix |
33|----------|----------|--------|--------|
34| 1 | Lifecycle | CRITICAL | `lifecycle-` |
35| 2 | Workflow | CRITICAL | `workflow-` |
36| 3 | Step | HIGH | `step-` |
37| 4 | Queue | HIGH | `queue-` |
38| 5 | Communication | MEDIUM | `comm-` |
39| 6 | Pattern | MEDIUM | `pattern-` |
40| 7 | Testing | LOW-MEDIUM | `test-` |
41| 8 | Client | MEDIUM | `client-` |
42| 9 | Advanced | LOW | `advanced-` |
43 
44## Critical Rules
45 
46### DBOS Configuration and Launch
47 
48A DBOS application MUST configure and launch DBOS inside its main function:
49 
50```python
51import os
52from dbos import DBOS, DBOSConfig
53 
54@DBOS.workflow()
55def my_workflow():
56    pass
57 
58if __name__ == "__main__":
59    config: DBOSConfig = {
60        "name": "my-app",
61        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
62    }
63    DBOS(config=config)
64    DBOS.launch()
65```
66 
67### Workflow and Step Structure
68 
69Workflows are comprised of steps. Any function performing complex operations or accessing external services must be a step:
70 
71```python
72@DBOS.step()
73def call_external_api():
74    return requests.get("https://api.example.com").json()
75 
76@DBOS.workflow()
77def my_workflow():
78    result = call_external_api()
79    return result
80```
81 
82### Key Constraints
83 
84- Do NOT call `DBOS.start_workflow` or `DBOS.recv` from a step
85- Do NOT use threads to start workflows - use `DBOS.start_workflow` or queues
86- Workflows MUST be deterministic - non-deterministic operations go in steps
87- Do NOT create/update global variables from workflows or steps
88 
89## How to Use
90 
91Read individual rule files for detailed explanations and examples:
92 
93```
94references/lifecycle-config.md
95references/workflow-determinism.md
96references/queue-concurrency.md
97```
98 
99## References
100 
101- https://docs.dbos.dev/
102- https://github.com/dbos-inc/dbos-transact-py
103