🪓 Hatchet v1: Questions and Feedback

[abelanger5]

🪓 Hatchet v1 is nearly here!

Note

The first Hatchet Launch Week is coming up! From March 24th to March 28th, we will be highlighting a new feature or performance improvement in the v1 engine each day. You can get updates in our Discord here and we will be updating the top of our README here with new announcements.

For the past several months, we’ve been working on a complete rewrite of the Hatchet queue with a focus on performance and a set of feature requests which weren’t possible in the v0 architecture.

This discussion outlines the timeline, new features and breaking changes you can expect from the new release. This is a living document and will continue to be updated until March 24th.

If you have feedback or questions, please add them to this Github discussion.

Timeline

• March 24th, 2025: Hatchet v1 will be released on Hatchet Cloud and under the latest v0.55.x release bundled with the v0 Hatchet engine. It will be opt-in, meaning engine v0 will still be the default engine for each tenant.
• March 24th-28th, 2025: Hatchet v1 launch week! We will be highlighting a new feature or performance improvement in the v1 engine. You can get updates in our Discord here and we will be updating the top of our README here with new announcements.
• May 1st, 2025: Hatchet v1 will become the new default engine for all Hatchet releases after this point. We will be releasing v1.0.x on this date.
• September 30th, 2025: Hatchet v0 enters EOL, and will no longer be bundled into the Hatchet runtime.

New features

At a high level, Hatchet v1 will support the following new features:

• Complex/conditional workflow logic, like skipping or branching workflows
• Durable execution features: workflow signaling and durable sleep
• A documented, stable REST API for interacting with workflows
• Each SDK will receive a new v1.0.x release with the following improvements:
  • Python will receive improved support for Pydantic validation, dynamic workflow composition, simpler workflow and task declaration, and significantly improved type support.
  • Typescript will receive a new factory method for building workflows, and improved typing and validation support
  • Go will receive improvements for registering workflows and defining tasks.
• Improved bulk cancellations and replays

We are currently working on documentation and specs for the new features. If you would like to beta test a new feature, please let us know in our Discord.

Breaking changes

First, a quick note — we are not removing any features from our existing feature set. Our goal is for all features to work with minimal changes in Hatchet v1.

Up to now, we’ve attempted to be as backwards-compatible as possible while keeping up with feature velocity, and we’d like to support users on v0 for as long as possible while providing an easy path for upgrading. Generally, we’d recommend upgrading the Hatchet engine first, followed by the SDK version. Here’s our compatibility matrix between v0 and v1:

	Engine v0	Engine v1
SDK v0	Supported	Supported*
SDK v1	Limited support**	Supported

* Some features will behave slightly differently on the v1 engine, but all workflows defined in v0 can be registered in v1

** It will not be possible to register a v1 workflow against the v0 engine, but each SDK will continue to bundle the v0 version until September 30th, 2025.

List of breaking changes

While we’d prefer to avoid any breaking changes, v1 is architecturally very different from v0, which means that the following APIs will be modified/replaced:

• While we haven’t published an official REST API doc, we have often recommended usage of the REST API in our SDKs to implement replays, retrieving task status, and dead-letter queueing. The current API for listing, cancelling and replaying workflow runs will not work against a v1 engine. We will be providing an upgrade path using new endpoints which are more conducive to bulk replays and cancellations.
• We will only be supporting CEL-based concurrency keys, and we will not be supporting custom concurrency methods defined on the client. If you require custom logic to compute the concurrency key that can’t be captured in a CEL expression, we recommend computing the key ahead of time and passing it as part of the input to the workflow. Workflows registered against a v1 engine with a custom concurrency method (instead of an expression) will not use a concurrency queue.
• Concurrency queues previously did not respect the ScheduleTimeout value set on the workflow level, so concurrency queues had no timeouts. In v1, concurrency queues will respect the schedule timeout value as well.
• User-defined events sent via event.push will no longer be displayed in the Hatchet UI and will not be available over the REST API. Events will still trigger workflows, but in nearly all instances of Hatchet that we surveyed, events were not used, accessed after writes, or replayed. We are considering adding an option to mark a user-defined event as Durable, but that will not be available in the initial v1 release. Please let us know if you are dependent on the events view or APIs.

These are the most important breaking changes, but we will add any small modifications to queueing/workflow behavior ahead of March 24th.

Terminology

We have gotten feedback that the terminology of Workflows and Steps is confusing, and we’ve seen users use the terms steps/tasks/jobs/workflows interchangeably. In the next major release, we are calling each individual unit of work a Task, and we are calling the declaration of the work to do a Workflow. We believe that this naming translates more directly to what Hatchet is actually doing (we are a task queue built on Postgres, after all). When referring to an instance of a task or workflow, we will internally (and over our REST API) refer to these as Task Run or Workflow Run, respectively, though it should be clear from context whether a Workflow or a Task refers to the declaration of work or an instance of the work.

Performance improvements

In our benchmarks so far, we’ve seen:

• 30% lower latency, from 30ms → 20ms average enqueue times
• 10x higher throughput, from about 1k events/s to 10k events/s
• Under significant load, we see about 6x less IOPs load and 5x less CPU load on the database

As part of the v1 rewrite, we will be releasing a new load testing container which is designed to benchmark Hatchet setups. We will be publishing a number of new benchmarks during our Launch Week.

Migration guides

We will be publishing the following migration guides in the next few weeks:

• v1 Self-Hosted Migration Guide
• v1 Python SDK migration guide
• v1 Go SDK migration guide
• v1 Typescript SDK migration guide

These links will become active when each migration guide is available.

Prerelease Testing

Hatchet pre-release v0.55.11 bundles a beta version of the v1 engine for testing. If you upgrade to v0.55.11 and navigate to your Tenant Settings, you will see an option to upgrade the tenant to v1:

Feedback + bug reports are much appreciated!