[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82058":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":14,"starSnapshotCount":14,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},82058,"durable-execution-the-hard-way","hatchet-dev\u002Fdurable-execution-the-hard-way","hatchet-dev","Set up a durable execution engine from scratch using Postgres with no dependencies.",null,"Go",145,5,27,0,4,9,113,12,2.33,"MIT License",false,"main",true,[],"2026-06-12 02:04:22","# Durable execution, the hard way\n\nInspired by Kelsey Hightower's [Kubernetes the hard way](https:\u002F\u002Fgithub.com\u002Fkelseyhightower\u002Fkubernetes-the-hard-way), we're going to build a durable execution engine from scratch using Go and Postgres.\n\nDurable execution is a mechanism to incrementally checkpoint the state of a function as it makes progress, so that in the case of unexpected failure, the function can recover from where it left off. It's particularly relevant in newer stacks and projects implementing AI agents, which are long-running and stateful. A system which implements durable execution is often called a \"workflow engine.\"\n\nThis guide uses Go and templated SQL using [sqlc](https:\u002F\u002Fsqlc.dev\u002F). The only dependencies are:\n\n- Go 1.25+\n- Postgres (by default, created via Docker)\n- pgx\n\nIf you are interested in contributing support for other languages, please create a Github issue. I'll be sharing updates (new lessons, other languages) for this guide on [Twitter](https:\u002F\u002Fx.com\u002Fabelanger5) if you'd like to follow along.\n\n## Target audience\n\nYou will benefit from this guide if you:\n\n- Want to understand how durable execution engines like Hatchet and Temporal work at a deeper level\n- Are implementing your own workflow engine and would like a simple starting point for your architecture\n\nThis guide expects that you understand the foundations of SQL databases, can read code, and are familiar with some minimal backend engineering concepts, such as queues. More advanced terminology will be introduced in each lesson.\n\nFor a motivating guide on durable execution, see the blog post [How to think about durable execution](https:\u002F\u002Fhatchet.run\u002Fblog\u002Fdurable-execution).\n\n## Navigating lessons\n\nEach directory in [\u002Flessons](.\u002Flessons\u002F) is set up with an identical structure:\n\n- A `README.md` file for navigating the lesson\n- A `main.go` file for running the example code produced by the lesson, which can be run via `go run .`\n- A `sql` directory which contains a `schema.sql` file, a `queries.sql` file, and some files for generating templated queries via `sqlc`\n\nBy the final lesson, we'll have a minimal but _fully-working workflow engine_. Note that these lessons are not focused on developer ergonomics: we'll be building the bare minimum to understand the fundamentals, but won't implement the typical niceties you'd see in a client SDK.\n\n## Lessons\n\n1. [Prerequisites](.\u002Flessons\u002F01-prerequisites\u002F)\n2. [Simple task queue](.\u002Flessons\u002F02-simple-task-queue\u002F)\n3. [Limiting concurrent tasks](.\u002Flessons\u002F03-limiting-concurrent-tasks\u002F)\n4. [Task queue improvements](.\u002Flessons\u002F04-task-queue-improvements\u002F)\n5. [Durable event log](.\u002Flessons\u002F05-durable-event-log\u002F)\n6. [Tracking non-determinism](.\u002Flessons\u002F06-non-determinism\u002F)\n7. [Durable tasks](.\u002Flessons\u002F07-durable-tasks\u002F)\n\n## Opinions\n\nThis guide is a somewhat _opinionated_ view on durable execution. Specifically, it implements:\n\n- Durable execution entirely in Postgres.\n- Two types of functions: durable tasks and regular tasks. These map directly to durable tasks and tasks in Hatchet, and are akin to Temporal workflows and activities.\n- Regular tasks invokable as standalone tasks, meaning this guide implements a simple Postgres-backed task queue as well in the first few lessons.\n- Multiple types of retries and replays, which are treated as distinct:\n  - Retries will retry a durable task without resetting the event history (preserving the execution state of the function)\n  - Replays will reset a durable task's execution history to start from scratch\n  - Forking will reset a durable task's execution history at a given point in the execution history, effectively creating a \"fork\" of that task. This will be the subject of a future lesson\n\n## Modifying lessons\n\nYou can modify the schema, queries, and code in each lesson to experiment. To regenerate the SQL files in each directory, run the following:\n\n```\ngo run github.com\u002Fsqlc-dev\u002Fsqlc\u002Fcmd\u002Fsqlc generate --file sql\u002Fsqlc.yaml\n```\n\n## Reporting issues\n\nIf you discovered an error in the core logic of any lesson, please file a Github issue. We'd be happy to reward you with a baked good from a bakery near you (yes, we're serious). If a bakery isn't available, we'd be happy to send you a Hatchet tee or hat. If you understandably don't want more vendor swag, you'll have my eternal gratitude.\n\n## Use of AI\n\nAI has not been used to write any prose in this guide. All mistakes and turns of phrase are my own. AI has been used to:\n\n- Verify that each lesson of this guide is independently runnable and instructions are easy to follow\n- Generate mermaid diagrams\n\n## Ideas for future lessons\n\nIf there's sufficient interest, I'd be happy to put together additional lessons, such as:\n\n- Using Postgres `LISTEN`\u002F`NOTIFY` to speed up processing significantly\n- Durable sleep\n- Branching and forking the durable event log\n","该项目从零开始使用Go语言和Postgres构建了一个持久化执行引擎。其核心功能包括通过Postgres实现状态的增量检查点，以确保在意外故障后可以从断点恢复执行，特别适用于需要长时间运行且保持状态的应用场景，如AI代理等。技术特点上，除了Go 1.25+、Postgres（默认通过Docker创建）以及pgx外无其他依赖，并采用sqlc生成模板化的SQL代码。本项目适合希望深入了解持久化执行引擎工作原理的技术人员，或正在寻找简单起点来构建自己的工作流引擎的开发者。",2,"2026-06-11 04:07:37","CREATED_QUERY"]