Workflows & Steps
Function Decorators
workflow
DBOS.workflow(
*,
name: Optional[str] = None,
max_recovery_attempts: Optional[int] = 100,
serialization_type: Optional[WorkflowSerializationFormat] = None,
validate_args: Optional[ValidateArgsCallable] = None,
auto_upgrade: Optional[bool] = None,
)
Durably execute this function as a DBOS workflow.
Example:
@DBOS.workflow()
def greeting_workflow(name: str, note: str):
sign_guestbook(name)
insert_greeting(name, note)
Parameters:
name: A name for this workflow. If not provided, the function's qualified name (__qualname__, which does not include its module) is used. Workflow names must be unique: registering workflows with the same name from different modules raises aDBOSException.max_recovery_attempts: The maximum number of times execution of a workflow may be attempted. This acts as a dead letter queue so that a buggy workflow that crashes its application (for example, by running it out of memory) does not do so infinitely. If a workflow exceeds this limit, its status is set toMAX_RECOVERY_ATTEMPTS_EXCEEDEDand it may no longer be executed. A workflow in this state may be resumed, which will resume execution and reset the count of execution attempts. If this behavior is not desired, it may be disabled by settingmax_recovery_attempts=None.serialization_type: The default serialization format to use for local invocations of this workflow. Set toWorkflowSerializationFormat.PORTABLEto test cross-language interoperability.validate_args: An optional callable that validates and optionally coerces workflow arguments before execution. Pass the built-inpydantic_args_validatorto automatically validate arguments against the function's type hints using Pydantic. See Input Validation and Coercion below for details and examples.auto_upgrade: Whether to auto-upgrade this workflow, automatically moving instances of it left on older application versions to the latest version. IfTrue, the workflow is auto-upgraded even ifauto_upgradeisn't set in your configuration; ifFalse, it is never auto-upgraded. If not set, followsauto_upgradein your configuration. Requires DBOS Transact Enterprise.
step
DBOS.step(
*,
name: Optional[str] = None,
retries_allowed: bool = False,
interval_seconds: float = 1.0,
max_attempts: int = 3,
backoff_rate: float = 2.0,
should_retry: Optional[Callable[[BaseException], Union[bool, Awaitable[bool]]]] = None,
preemptible: bool = False,
timeout_seconds: Optional[float] = None,
)
Annotate a function as a step in a workflow. Workflows automatically checkpoint the outcomes of their steps. If a workflow is interrupted, it recovers from the last completed step.
Example:
@DBOS.step(retries_allowed=True, max_attempts=10)
def example_step():
return requests.get("https://example.com").text
Parameters:
name: A name for this step. If not provided, the function's qualified name (__qualname__) is used.retries_allowed: Whether to retry the step if it throws an exception.interval_seconds: How long to wait before the initial retry.max_attempts: The maximum number of times to attempt a step that is throwing exceptions, including the first attempt.backoff_rate: How much to multiplicatively increaseinterval_secondsbetween retries.should_retry: Optional predicate called with the raised exception to decide whether the step should be retried. If it returnsFalse(or an awaitable resolving toFalse), the exception is re-raised immediately without further retries. Ignored whenretries_allowedisFalse. Async predicates are only supported for async steps.preemptible: IfTrue, the step is cancelled immediately when its workflow is cancelled, rather than running to completion. Only supported for async steps.timeout_seconds: If set, cancel the step and raiseDBOSStepTimeoutErrorif it runs for longer than this many seconds. Only supported for async steps, and must be positive and finite. Each retry attempt gets a fresh timeout. See Step Timeouts.
required_roles
DBOS.required_roles(
roles: List[str]
)
The @DBOS.required_roles decorator applies role-based security to the decorated function. The authenticated user must have at least one of the roles on the roles list in order to access the function.
Parameters:
roles: List of required roles applied to the decorated function.
Example:
@DBOS.workflow()
@DBOS.required_roles(["support","admin"])
def my_support_workflow():
pass # Function accessible only with "support" or "admin" role
kafka_consumer
DBOS.kafka_consumer(
config: dict[str, Any],
topics: list[str],
*,
ordering: Optional[Literal["none", "partition", "topic"]] = None,
batch_size: int = 250,
queue_name: Optional[str] = None,
)
Runs a function for each Kafka message received on the specified topic(s). Uses the Kafka message's topic, partition, and offset and the consumer group ID to create a unique workflow id to ensure once and only once execution. Takes a configuration dictionary and a list of topics to consume. The decorated function must take a KafkaMessage as its only parameter.
Parameters:
config: a dictionary of config settings. Information on key settings follows with full configuration setting details available in the official Kafka documentation.bootstrap.servers: A list of host/port pairs to use for establishing the initial connection to the Kafka cluster. This list should be in the form host1:port1,host2:port2,...group.id: A unique string that identifies the consumer group this consumer belongs to. Setting it is recommended: if it is omitted, DBOS generates one from the function name and topics and logs a warning.
topics: a list of Kafka topics to subscribe to. A topic prefixed with^is treated as a regular expression.ordering: Controls how messages are processed. See In-Order Processing."none"(default): messages are processed in parallel."partition": messages are processed serially per topic partition (preserving Kafka's per-partition delivery order) and in parallel across partitions."topic": messages are processed serially per topic.
batch_size: The maximum number of messages consumed from Kafka and durably enqueued per batch. Defaults to 250.queue_name: The name of an optional queue on which consumer workflows run, for example to configure concurrency or rate limits. Only valid withordering="none"; ordered consumers share an internal partitioned queue. The named queue must not be a partitioned queue. If you useDBOS.listen_queues, you must include this queue.
Example
@DBOS.kafka_consumer(
config={
"bootstrap.servers": "localhost:9092",
"group.id": "dbos-kafka-group",
},
topics=["example-topic"],
)
@DBOS.workflow()
def test_kafka_workflow(msg: KafkaMessage):
DBOS.logger.info(f"Message received: {msg.value.decode()}")
Input Validation and Coercion
Python workflows can specify a validate_args parameter on @DBOS.workflow().
The built-in pydantic_args_validator sentinel builds a Pydantic validator from the function's type hints at decoration time.
This validates argument types and coerces compatible values (for example, ISO date strings to datetime objects).
Validation runs when a workflow is dequeued for execution (for example, after being enqueued, recovered, or forked), not when the workflow function is called directly or started with DBOS.start_workflow.
from datetime import datetime
from typing import Dict, Any, List
from dbos import DBOS, WorkflowSerializationFormat, pydantic_args_validator
@DBOS.workflow(
serialization_type=WorkflowSerializationFormat.PORTABLE,
validate_args=pydantic_args_validator,
)
def process_order(name: str, count: int, tags: List[str]) -> str