Skip to content

docs(README): add 'Is this for me?' section (who/why/when)#204

Merged
pinodeca merged 3 commits into
mainfrom
readme-who-why-when
Jun 4, 2026
Merged

docs(README): add 'Is this for me?' section (who/why/when)#204
pinodeca merged 3 commits into
mainfrom
readme-who-why-when

Conversation

@pinodeca

@pinodeca pinodeca commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Improves the README to help devs landing on GitHub answer "does this apply to me?" within ~30 seconds.

Adds an Is this for me? section after the Quick Example covering:

  • The core idea — durable graph of SQL steps with per-step checkpointing
  • Pain points it addresses — long-running SQL falling over, workflow logic leaking into app code, no native fan-out/branch/loop, scripts with no memory
  • Who it's for — backend engineers, data/platform engineers, DBAs/SREs, AI pipeline teams
  • Workloads it fits — ETL, scheduled jobs, parallel aggregation, approvals, DB maintenance, HTTP-from-SQL
  • What you're probably doing today instead — pg_cron + jobs table + worker, external orchestrators, queues + workers, plpgsql with EXCEPTION blocks
  • How it's different — lives inside Postgres, SQL is the workflow language, per-step checkpointing with replay, Postgres as source of truth
  • What changes in your architecture — delete bespoke queues/state tables, move background work into Postgres, observability via SELECT
  • When NOT to use it — sub-ms hot paths, massive stream processing, no PG17/extensions, pure single-statement SQL, heterogeneous distributed sagas

Kept scannable (bullets, no long prose) so it stays within the ~30-second skim budget. All existing sections (Features, Quick Example, How It Works, Installation, Multi-User Setup, CI, Testing, Architecture, etc.) are unchanged.

@pinodeca pinodeca merged commit 36950ca into main Jun 4, 2026
5 checks passed
@pinodeca pinodeca deleted the readme-who-why-when branch June 4, 2026 03:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants