agentleFS
narenaryannarenaryan/agent-skills/skills/engineering/transactional-outbox-delivery/SKILL.md

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

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
  1. Distinctive:

    Commit domain state and its event record in one local database transaction.

    line 8
  2. Distinctive:

    Keep event fields immutable.

    line 14

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.