antigravity-skills-reference/skills/dbos-python/references/advanced-patching.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Use Patching for Safe Workflow Upgrades	LOW	Deploy breaking changes without disrupting in-progress workflows	patching, upgrade, versioning, migration

Use Patching for Safe Workflow Upgrades

Use DBOS.patch() to safely deploy breaking workflow changes. Breaking changes alter what steps run or their order.

Incorrect (breaking change without patch):

# Original
@DBOS.workflow()
def workflow():
    foo()
    bar()

# Updated - breaks in-progress workflows!
@DBOS.workflow()
def workflow():
    baz()  # Replaced foo() - checkpoints don't match
    bar()

Correct (using patch):

# Enable patching in config
config: DBOSConfig = {
    "name": "my-app",
    "enable_patching": True,
}
DBOS(config=config)

@DBOS.workflow()
def workflow():
    if DBOS.patch("use-baz"):
        baz()  # New workflows use baz
    else:
        foo()  # Old workflows continue with foo
    bar()

Deprecating patches after all old workflows complete:

# Step 1: Deprecate (runs all workflows, stops inserting marker)
@DBOS.workflow()
def workflow():
    DBOS.deprecate_patch("use-baz")
    baz()
    bar()

# Step 2: Remove entirely (after all deprecated workflows complete)
@DBOS.workflow()
def workflow():
    baz()
    bar()

DBOS.patch(name) returns:

• True for new workflows (started after patch deployed)
• False for old workflows (started before patch deployed)

Reference: Patching