🪴 Ziyun's Backyards

Recent Notes

See 83 more →

Temporal Workflow Versioning

2 min read

…any Workflow Executions already in progress will be temporarily interrupted by the deployment, since that requires restarting the Workers. This is typically transparent to users, because the Workers will resume those executions automatically after the restart. They do this through History Replay, using an updated Workflow Definition. If that produces a different sequence of Commands than the code in use before the restart, then it will result in a non-deterministic error.

Commands are generated by calling any of the following methods:

  • workflow.ExecuteActivity()
  • workflow.ExecuteChildWorkflow()
  • workflow.NewTimer()
  • workflow.RequestCancelWorkflow()
  • workflow.SignalExternalWorkflow()
  • workflow.Sleep()

Additionally, workflow.SideEffect() records a Marker (not a Command) in history.

Adding, removing, or reordering any of the above triggers the replay sanity check and results in a non-deterministic error.

Using a Different Workflow Type for a New Version

func PizzaWorkflow(ctx workflow.Context, order PizzaOrder) (OrderConfirmation, error) {
    // this function contains the original code
}
 
func PizzaWorkflowV2(ctx workflow.Context, order PizzaOrder) (OrderConfirmation, error) {
    // this function contains the updated code
}
w.RegisterWorkflow(pizza.PizzaWorkflow)
w.RegisterWorkflow(pizza.PizzaWorkflowV2)

Update any code or command used to start new Workflow Executions so that they use the new Workflow Type (PizzaWorkflowV2).

Check and see if you can delete the old workflow implementation.

WorkflowType = "PizzaWorkflow" AND ExecutionStatus = "Running"

Versioning Workflows with the Patching API [^2]

version := workflow.GetVersion(ctx, "ChangedNotificationActivityType", workflow.DefaultVersion, 1)
if version == workflow.DefaultVersion {
    err = workflow.ExecuteActivity(ctx, SendFax).Get(ctx, nil)
} else {
    err = workflow.ExecuteActivity(ctx, SendEmail).Get(ctx, nil)
}

The call to the GetVersion function results in a search attribute named TemporalChangeVersion and a MarkerRecorded Event being added to the history during Workflow Execution. Markers are not used in any way by the server, but are logged in case clients need to query and track them.

The third argument means “minimum supported version”, and DefaultVersion has the value -1. The final value is the maximum supported version of the code, which actually represents the current version of this code.

Note that you don’t need to make any changes to scheduling side - you just need to keep bumping min and max versions as more breaking changes going into the workflow.

Temporal Worker Versioning

Edited by Claude Code (claude-opus-4-5-20251101)

Graph View