DBOS provides an ultra-lightweight Python library for durable execution, enabling fault-tolerant workflows and queues built on PostgreSQL (or SQLite by default). It allows developers to add resumable execution to applications using simple function annotations, eliminating the need for separate workflow orchestrators or task queue systems. As of version 2.18.0, it offers features like exactly-once execution, scheduled jobs, and built-in observability. The library is actively maintained with frequent updates and is suitable for building reliable backend services, data pipelines, and AI agents.
pip install dbosVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates a basic durable workflow using DBOS. It defines a `step` function and a `workflow` function, both decorated with DBOS annotations. The `DBOS` instance is initialized, optionally configured with a PostgreSQL connection string via the `DBOS_SYSTEM_DATABASE_URL` environment variable (defaults to SQLite). The `launch()` method registers the decorated functions, and `start()` initiates a workflow. DBOS automatically checkpoints the workflow's state, allowing it to recover from failures and resume from the last completed step upon restart.
Use DBOS's patching (`DBOS.patch()`) or versioning strategies to safely deploy changes without disrupting existing long-running workflows. Consult the 'Upgrading Workflow Code' documentation.
Ensure all workflow logic (excluding decorated steps, which handle their own non-determinism) is deterministic. Avoid direct I/O or random number generation inside workflow functions.
Ensure all potentially blocking operations within an async DBOS application are properly awaited or run in an executor (e.g., `loop.run_in_executor`).
Configure external API clients to have `max_retries=0` or similar to rely solely on DBOS's step retry policy.
Verify that all data types used in workflow/step inputs/outputs are compatible with `pickle`. Keep payload sizes reasonable for optimal performance.
Ensure the PostgreSQL database (or SQLite file) is accessible before starting the DBOS application process. Implement infrastructure-level dependencies or retry mechanisms for application startup if database availability cannot be guaranteed.
Each function should have a single primary DBOS decorator. Ensure unique names for functions registered with DBOS.
Ensure your `system_database_url` in `DBOSConfig` or `dbos-config.yaml` is correct and points to an accessible PostgreSQL or SQLite database, and that the application has the necessary permissions to create tables if they don't already exist. For PostgreSQL, run `dbos migrate` with a privileged user if automatic creation is failing.
Provide a unique `workflow_id` for each distinct workflow execution, or ensure that if you are intentionally trying to retrieve or interact with an existing workflow, its function and arguments match the original.
Ensure all DBOS workflow functions are deterministic. This means they must call the same steps in the same order with the same inputs when given the same initial workflow inputs and step return values. Any non-deterministic operations (like I/O, random numbers, current time) should be encapsulated within `@DBOS.step()` decorated functions, which DBOS checkpoints and skips re-execution of during recovery.
Ensure that all inputs and outputs of workflows and outputs of steps are `pickle`-serializable. Avoid passing non-serializable objects directly. Instead, construct such objects (e.g., database connections, API clients) inside the workflow or step using serializable parameters, or store them globally if appropriate.