Skip to content
Back to search

absurd

An experiment in durability

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/earendil-works--absurd/badge.svg)](/listings/earendil-works--absurd)

HTML

<a href="/listings/earendil-works--absurd"><img src="/api/listings/earendil-works--absurd/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Absurd just needs a single `.sql` file ([`absurd.sql`](sql/absurd.sql)) which needs to be applied to a database of your choice. You can plug it into your favorite migration system of choice. Additionally if that file changes, we also release [migrations](sql/migrations) which should make upgrading easy. See the [quickstart guide](https://earendil-works.github.io/absurd/quickstart/) for a short tutorial and the [documentation index](https://earendil-works.github.io/absurd/) for everything else.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div style="text-align: center" align="center">
  2. <img src="logo.jpg" width="350" alt="Une photo d'un éléphant avec le titre : « Ceci n'est pas un éléphant »">
  3. <br><br>
  4. </div>
  5. # Absurd
  6. Absurd is the simplest durable execution workflow system you can think of.
  7. It's entirely based on Postgres and nothing else. It's almost as easy to use as
  8. a queue, but it handles scheduling and retries, and it does all of that without
  9. needing any other services to run in addition to Postgres.
  10. *… because it's absurd how much you can over-design such a simple thing.*
  11. More about it can be found [in the announcement post](https://lucumr.pocoo.org/2025/11/3/absurd-workflows/).
  12. You can read in the docs [how Absurd compares to PGMQ, Cadence, Temporal,
  13. Inngest, and DBOS](https://earendil-works.github.io/absurd/comparison/).
  14. ## What is Durable Execution?
  15. Durable execution (or durable workflows) is a way to run long-lived, reliable
  16. functions that can survive crashes, restarts, and network failures without losing
  17. state or duplicating work. Durable execution can be thought of as the combination
  18. of a queue system and a state store that remembers the most recently seen state.
  19. Instead of running your logic in memory, a durable execution system decomposes
  20. a task into smaller pieces (step functions) and records every step and decision.
  21. When the process stops (fails, intentionally suspends, or a machine dies), the
  22. engine can replay those events to restore the exact state and continue where it
  23. left off, as if nothing happened.
  24. In practice, that makes it possible to build dependable systems for things like
  25. LLM-based agents, payments, email scheduling, order processing--really anything
  26. that spans minutes, days, or even years. Rather than bolting on ad-hoc retry
  27. logic and database checkpoints, durable workflows give you one consistent model
  28. for ensuring progress without double execution. It's the promise of
  29. "exactly-once" semantics in distributed systems, but expressed as code you can
  30. read and reason about.
  31. ## Installation
  32. Absurd just needs a single `.sql` file ([`absurd.sql`](sql/absurd.sql)) which
  33. needs to be applied to a database of your choice. You can plug it into your
  34. favorite migration system of choice. Additionally if that file changes, we
  35. also release [migrations](sql/migrations) which should make upgrading easy.
  36. See the [quickstart guide](https://earendil-works.github.io/absurd/quickstart/) for a short tutorial and the
  37. [documentation index](https://earendil-works.github.io/absurd/) for everything else.
  38. ## Client SDKs
  39. Currently SDKs exist for the following languages:
  40. * [TypeScript](sdks/typescript) (and JavaScript)
  41. * [Python](sdks/python)
  42. * [Go](sdks/go/absurd) *(experimental bootstrap)*
  43. ## Push vs Pull
  44. Absurd is a pull-based system, which means that your code pulls tasks from
  45. Postgres as it has capacity. It does not support push at all, which would
  46. require a coordinator to run and call HTTP endpoints or similar. Push systems
  47. have the inherent disadvantage that you need to take greater care of system load
  48. constraints. If you need this, you can write yourself a simple service that
  49. consumes messages and makes HTTP requests.
  50. ## High-Level Operations
  51. Absurd's goal is to move the complexity of SDKs into the underlying stored
  52. functions. The SDKs then try to make the system convenient by abstracting the
  53. low-level operations in a way that leverages the ergonomics of the language you
  54. are working with.
  55. A *task* dispatches onto a given *queue* from where a *worker* picks it up
  56. to work on. Tasks are subdivided into *steps*, which are executed in sequence
  57. by the worker. Tasks can be suspended or fail, and when that happens, they
  58. execute again (a *run*). The result of a step is stored in the database (a
  59. *checkpoint*). To not repeat work, checkpoints are automatically loaded from
  60. the state storage in Postgres again.
  61. Additionally, tasks can *sleep* or *suspend for events*. Events are cached
  62. (first emit wins), which means they are race-free.
  63. ## Components
  64. Absurd comes with two basic tools that help you work with it. One is
  65. called [`absurdctl`](https://earendil-works.github.io/absurd/tools/absurdctl/) which allows you to initialize and
  66. migrate the schema, inspect schema versions, create/drop/list queues, and spawn
  67. or retry tasks. The other is [habitat](habitat) which is a Go application that
  68. serves up a web UI to show you the current state of running and executed tasks.
  69. ```bash
  70. uvx absurdctl init -d database-name
  71. uvx absurdctl schema-version -d database-name
  72. uvx absurdctl migrate -d database-name
  73. uvx absurdctl create-queue -d database-name default
  74. ```
  75. Use [`uvx`](https://docs.astral.sh/uv/guides/tools/) `absurdctl ...` for
  76. one-off commands, or install it persistently with `uv tool install absurdctl`.
  77. If you prefer a standalone file, you can also download `absurdctl` from GitHub
  78. Releases and put it on your `PATH`:
  79. ```bash
  80. curl -fsSL \
  81. https://github.com/earendil-works/absurd/releases/latest/download/absurdctl \
  82. -o absurdctl
  83. chmod +x absurdctl
  84. install -m 755 absurdctl ~/.local/bin/absurdctl
  85. ```
  86. Install the SDK for your language of choice:
  87. ```bash
  88. # TypeScript / JavaScript
  89. npm install absurd-sdk
  90. # Python
  91. uv add absurd-sdk
  92. # Go
  93. go get github.com/earendil-works/absurd/sdks/go/absurd@latest
  94. ```
  95. <div style="text-align: center" align="center">
  96. <img src="habitat/screenshot.png" width="550" alt="Screenshot of habitat">
  97. </div>
  98. ## Example
  99. Here's what that looks like in TypeScript.
  100. ```typescript
  101. import { Absurd } from 'absurd-sdk';
  102. const app = new Absurd();
  103. // A task represents a series of operations. It can be decomposed into
  104. // steps, which act as checkpoints. Once a step has been passed
  105. // successfully, the return value is retained and it won't execute again.
  106. // If it fails, the entire task is retried. Code that runs outside of
  107. // steps will potentially be executed multiple times.
  108. app.registerTask({ name: 'order-fulfillment' }, async (params, ctx) => {
  109. // Each step is checkpointed, so if the process crashes, we resume
  110. // from the last completed step
  111. const payment = await ctx.step('process-payment', async () => {
  112. // If you need an idempotency key, you can derive one from ctx.taskID.
  113. return {
  114. paymentId: `pay-${params.orderId}`,
  115. amount: params.amount,
  116. };
  117. });
  118. const inventory = await ctx.step('reserve-inventory', async () => {
  119. return { reservedItems: params.items };
  120. });
  121. // Wait indefinitely for a warehouse event - the task suspends
  122. // until the event arrives. Events are cached like step checkpoints
  123. // (first emit wins), which means this is race-free.
  124. const shipment = await ctx.awaitEvent(`shipment.packed:${params.orderId}`);
  125. // Ready to send a notification!
  126. await ctx.step('send-notification', async () => {
  127. return {
  128. sentTo: params.email,
  129. trackingNumber: shipment.trackingNumber,
  130. };
  131. });
  132. return {
  133. orderId: params.orderId,
  134. payment,
  135. inventory,
  136. trackingNumber: shipment.trackingNumber,
  137. };
  138. });
  139. // Start a worker that pulls tasks from Postgres
  140. const worker = await app.startWorker();
  141. // Spawn a task - it will be executed durably with automatic retries. If
  142. // triggered from within a task, you can also await it.
  143. const { taskID } = await app.spawn('order-fulfillment', {
  144. orderId: '42',
  145. amount: 9999,
  146. items: ['widget-1', 'gadget-2'],
  147. email: 'customer@example.com'
  148. });
  149. await app.emitEvent('shipment.packed:42', {
  150. trackingNumber: 'TRACK123',
  151. });
  152. console.log(await app.awaitTaskResult(taskID, { timeout: 10 }));
  153. await worker.close();
  154. await app.close();
  155. ```
  156. ## Documentation
  157. More detail lives in the docs:
  158. - [Quickstart](https://earendil-works.github.io/absurd/quickstart/)
  159. - [TypeScript SDK](https://earendil-works.github.io/absurd/sdks/typescript/)
  160. - [Python SDK](https://earendil-works.github.io/absurd/sdks/python/)
  161. - [Go SDK](https://earendil-works.github.io/absurd/sdks/go/) *(experimental)*
  162. - [Database Setup and Migrations](https://earendil-works.github.io/absurd/database/)
  163. - [Concepts](https://earendil-works.github.io/absurd/concepts/) — includes retry semantics, worker claims, and idempotency keys
  164. - [Living with Code Changes](https://earendil-works.github.io/absurd/patterns/living-with-code-changes/)
  165. - [Cleanup and Retention](https://earendil-works.github.io/absurd/cleanup/)
  166. ## Working With Agents
  167. Absurd is built so that agents such as Claude Code or pi can efficiently work
  168. with the state in the database. The easiest setup is to install the bundled
  169. Absurd skill into a project or user skills directory:
  170. ```
  171. absurdctl install-skill # installs to .agents/skills
  172. absurdctl install-skill .pi/skills # if you want a different path
  173. ```
  174. See [Working With Agents](https://earendil-works.github.io/absurd/agents/) for the recommended setup.
  175. ## AI Use Disclaimer
  176. This codebase has been built with a lot of support of AI. A combination of hand
  177. written code, Codex and Claude Code was used to create this repository. To the
  178. extent to which it can be copyrighted, the Apache 2.0 license should be assumed.
  179. ## License and Links
  180. - [Examples](https://github.com/earendil-works/absurd/tree/main/sdks/typescript/examples)
  181. - [Issue Tracker](https://github.com/earendil-works/absurd/issues)
  182. - License: [Apache-2.0](https://github.com/earendil-works/absurd/blob/main/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.