transactional-outbox-delivery
Skill0 starsChanged 40 days agoMITView on GitHub
Use when a database-backed service needs polling-versus-CDC choices, duplicate-safe consumers, or per-aggregate delivery order
In this repository66 other files it gives its agents.
- AGENTS.mdAGENTS.md
- postgres-locking-joinsSkill
- ai-bug-patternsSkill
- compressed-ndjson-boundariesSkill
- http-resume-integritySkill
- linux-io-latency-triageSkill
- macos-disk-space-recoverySkill
- minimal-sufficient-evidenceSkill
- modularize-large-filesSkill
- patch-reproducer-validitySkill
- prompt-cache-boundariesSkill
- proton-drive-selective-backupSkill
- conventional-commitsSkill
- git-advanced-mergingSkill
- git-bisect-forensicsSkill
- git-data-recoverySkill
- git-hooksSkill
- git-rerereSkill
- git-reset-mechanicsSkill
- git-revisions-syntaxSkill
- git-rewriting-historySkill
- git-submodulesSkill
- git-worktreesSkill
- github-ssh-keysSkill
- npm-publish-ci-pitfallsSkill
- sapling-stacked-pr-workflowSkill
- go-concurrency-patternsSkill
- go-data-idiomsSkill
- go-error-handlingSkill
- go-interfaces-embeddingSkill
- go-pprof-profilingSkill
- marketing-funnel-diagnosisSkill
- marketing-geo-experimentsSkill
- marketing-incrementalitySkill
- marketing-positioning-testsSkill
- python-descriptors-mroSkill
- python-logging-cookbookSkill
- python-scaling-regression-testsSkill
- python-unicode-gotchasSkill
- rust-compile-time-invariantsSkill
- rust-deterministic-concurrency-testsSkill
- rust-error-identity-boundariesSkill
- rust-regex-search-contractsSkill
- rust-runtime-bug-classesSkill
- rust-tokio-actor-deliverySkill
- rust-tokio-cancellation-safetySkill
- sales-discovery-qualificationSkill
- sales-mutual-action-plansSkill
- sales-pipeline-forecast-calibrationSkill
- sales-value-negotiationSkill
- ai-triage-evaluationSkill
- container-image-patchingSkill
- dependency-artifact-integritySkill
- dnssec-sentinel-diagnosticsSkill
- iam-policy-change-replaySkill
- rbvm-applicabilitySkill
- rbvm-asset-evidenceSkill
- rbvm-guarded-remediationSkill
- rbvm-priority-decisionsSkill
- rbvm-risk-exceptionsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Commit domain state and its event record in one local database transaction.
- Distinctive: line 14
Keep event fields immutable.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Transactional Outbox Delivery
Commit domain state and its event record in one local database transaction. The broker is outside; expect replay. Transport “exactly once” does not ensure one business effect.
Producer and relay
- In one transaction, update the domain row and insert an immutable event row; rollback must leave neither visible. Include stable event ID, aggregate type/ID, event type, and payload. If order matters, allocate the per-aggregate sequence with the aggregate update, not a timestamp.
- Polling needs indexed scans, backoff, and safe claims. After its initial snapshot, CDC avoids repeated scans but adds log retention, offsets, snapshots, and connector operations. Debezium PostgreSQL slots retain WAL during outages and can consume disk. Test restart and backlog recovery.
- Keep event fields immutable; polling state is separate. A poller advances or deletes only after broker acknowledgement; a crash after broker acknowledgement but before checkpoint duplicates. CDC replays from offsets; retain rows and WAL through connector capture and recovery.
- If order matters, use aggregate ID as Kafka key with a stable key-based partitioner and unchanged partition count. Matching keys share a partition; Kafka preserves its append order, not end-to-end order across parallel relays or consumer effects. Enforce next sequence and serialize per aggregate on publish and apply, or reject/retry gaps. IDs and timestamps do not prove commit order.
Example: order 781 emits OrderPlaced as E/sequence 14; every retry keeps both values.
Make consumer dedup atomic
Use a durable unique (consumer_name, event_id) key. In one consumer DB transaction, insert the key and apply the effect only if the claim wins; a duplicate is a no-op. Commit DB before Kafka offset commit or other broker ack. If the effect fails, roll back the marker; redelivery after commit is safe. For external effects, an outbox makes dispatch durable; the receiver still needs idempotency or reconciliation.
Retain source outbox/WAL through connector recovery. Keep consumer dedup markers at least as long as the maximum supported redelivery/replay horizon; purging sooner can repeat effects. Set broker-topic retention separately for replay/audit; archive IDs and sequences if older replay is promised. Deleting delivered rows removes that replay source; name the authoritative archive and expiry.
Sources: AWS transactional-outbox guidance; AWS saga guidance; Debezium Outbox Event Router; Debezium PostgreSQL connector; Kafka 4.2 design docs.
Pitfalls
- A polling relay that marks or deletes before broker acknowledgement can lose an event on crash.
- A dedup marker committed apart from the business effect still permits a duplicate effect after a crash.
- Kafka partition order is not end-to-end order if relay or consumer work is parallelized.
- Purging rows before the supported recovery horizon makes older events unreplayable.
- The outbox covers one service’s state and event record, not a multi-service transaction; if coordinated recovery is required, model a saga with explicit retries and compensation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

