Patching

[kraftp]

Patching is a mechanism for safely upgrading workflow code. It is an alternative to workflow versioning (though they can be used together).

The problem patching solves is "How do I make a breaking change to a workflow's code but continue execution of long-running workflows that started on the old code version?" A breaking change is any change in what steps run or the order in which they run.

To use patching, first enable it in configuration:

config: DBOSConfig = {
    "name": "dbos-starter",
    "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    "enable_patching": True,
}
DBOS(config=config)

Next, when making a breaking change, use an if DBOS.patch(): conditional. DBOS.patch() returns True for new workflows (those started after the breaking change) and False for old workflows (those started before the breaking change). Therefore, if DBOS.patch() is true, call the new code, else call the old code.

So let's say our workflow is:

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

We want to replace the call to foo() with a call to baz(), which is a breaking change. We can do this safely using a patch:

@DBOS.workflow()
def workflow():
  if DBOS.patch("use-baz"):
    baz()
  else:
    foo()
  bar()

Now, new workflows will run baz(), while old workflows will safely recover through foo().

Once all workflows of the pre-patch code version are complete, we can remove patches from our code. First, we deprecate the patch. This will safely run workflows containing the patch marker, but will not insert the patch marker into new workflows:

@DBOS.workflow()
def workflow():
  DBOS.deprecate_patch("use-baz")
  baz()
  bar()

Then, when all workflows containing the patch marker are complete, we can remove the patch entirely and complete the workflow upgrade!

@DBOS.workflow()
def workflow():
  baz()
  bar()

If any mistakes happen during the process (a breaking change is not patched, or a patch is deprecated or removed prematurely), the workflow will throw a clean DBOSUnexpectedStepError pointing to the step where the problem occurred.

Also, one advanced feature is that if you need to make consecutive breaking changes to the same code, you can stack patches:

@DBOS.workflow()
def workflow():
  if DBOS.patch("use-qux"):
    qux()
  elif DBOS.patch("use-baz"):
    baz()
  else:
    foo()
  bar()

[dosubot]

Related Documentation

Checked 8 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[maxdml]

How would I use this patching system to fix a workflow? Manually fork from the step before the patch?

[qianl15]

I think we don't need this config. Because users should be able to use patching + versioning together. This code forces the version to be a weird PATCHING_ENABLED string which is not intuitive.

[kraftp]

This makes behavior much more intuitive. Patching requires a static version string. This check provides clean errors if you don't have one. You can still override it if you really want to. Otherwise you'll be thinking you're using patching, but your workflows don't recover and you don't know why.

[qianl15]

The problem with this approach is it's confusing where to run deprecate_patch: does it replace the original if-else statements? What if I have consecutive if-else branches?

[qianl15]

I think a better design is to explicitly register patches and explicitly enable/disable them. It's easier for testing too -- you can test the patched code controlling which patch is effective.