Best practices for breaking changes in Job Arguments?

[almottier]

Hi! I need to deploy a breaking change to job arguments in production. We have 2 workers and may have jobs queued with the old structure. We would need to handle both old and new formats during deployment.

// current
type SendEmailArgs struct {
    User types.User  `json:"user"`
}

// new (breaking change)
type SendEmailArgs struct {
    UserID uuid.UUID `json:"user_id"`
}

Questions:

1. What's the recommended approach for handling this transition?
2. Should I use versioned arguments, or multiple queues/workers?
3. Any River-specific gotchas when migrating job arguments?

Thanks for any advice! 🙏

[bgentry]

@almottier I would typically handle this by keeping both sets of args around for a transitional period, following this rough strategy:

1. Add the UserID field and start using it on the enqueueing side where you can.
2. Update the worker to prefer UserID but fall back to User if that's all there is (can be deployed together with the above).
3. Once all relevant jobs have been worked or cleared out of the queue, remove the old field so it's just UserID remaining.

You could definitely adopt a versioned strategy if you're trying to solve this with a general pattern beyond just this one simple case.

Not sure if this is enough to help you, let me know if I can elaborate on anything!

[almottier]

Thank you for your response, that's the solution I'm going to use.

[brandur]

Great!

Also, forgot to mention, but we ended up publishing a docs page on this too:

https://riverqueue.com/docs/changing-job-args