Migrating to v2

QStash v2 is almost a complete rewrite of the existing system allowing us to scale horizontally much easier to meet the demand.

As a result of that, a few endpoints have changed and we also added new ones.

• v1 reference
• v2 reference

During the deprecation phase, you can use both versions but we encourage you to move to v2 as soon as possible.

To migrate to v2, all you need to do is call the new /v2 endpoints.

In the console you can toggle between versions to access your logs and messages.

Major changes

Creating schedules is its own endpoint

Instead of creating schedules through the /v2/publish endpoint, there is a dedicated /v2/schedules api now.

Where are the messages in V2 ?

A big difference on v2 is that we no longer keep the messages to be accessed via Get Message to scale better.

• A message is removed from the messages list if the call was successful.
• If the publish is failed, it will be moved to DLQs.
• This endpoint will return a message only if a message is retrying.

A common workflow was to check the message via message id Get Message to see if it was successful or not. This was not a good workflow because, it is not clear when to check this endpoint to take an action.

Instead in v2, to check a message is failed and act on it, you can:

1. Use Upstash-Failure-Callback. Give the Upstash-Failure-Callback when publishing the message to be called when the message is failed to be delivered. In the given endpoint:

   • Handle the message.
   • Remove it from DLQ using Delete a Message From DLQ via the dlqId delivered to Upstash-Failure-Callback.

2. Use DLQs. This means that you need a continuously running task to read the messages from DLQ. The workflow in this case looks like this:

   • Get all the messages with the last known cursor(Cursor will be empty in the beginning)
   • Update the last known cursor with the cursor in the response.
   • If the messages are empty, query the endpoint again after a delay.
   • If there are messages, handle and delete them from DLQ via Delete a Message From DLQ
   • Query the endpoint again after a delay with the updated cursor.

With this follow, in a good run, DLQ should be empty. It will have messages only when there is something wrong with your service.