dbos-python

DBOS Python Best Practices

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

When to Use

Reference these guidelines when:

• Adding DBOS to existing Python code
• Creating workflows and steps
• Using queues for concurrency control
• Implementing workflow communication (events, messages, streams)
• Configuring and launching DBOS applications
• Using DBOSClient 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

DBOS Configuration and Launch

A DBOS application MUST configure and launch DBOS inside its main function:

import os
from dbos import DBOS, DBOSConfig

@DBOS.workflow()
def my_workflow():
    pass

if __name__ == "__main__":
    config: DBOSConfig = {
        "name": "my-app",
        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    }
    DBOS(config=config)
    DBOS.launch()

Workflow and Step Structure

Wor