Skip to content

docs(outbox): document single-commit vs 2PC consumer pattern - #40

Merged
asawicki merged 1 commit into
mainfrom
asawicki/docs/outbox-single-commit-pattern
Jun 28, 2026
Merged

docs(outbox): document single-commit vs 2PC consumer pattern#40
asawicki merged 1 commit into
mainfrom
asawicki/docs/outbox-single-commit-pattern

Conversation

@asawicki

Copy link
Copy Markdown
Collaborator

What

Adds a Consumer Business Writes: Single-Commit vs 2PC section to the published Outbox article (docs/articles/outbox.md).

The recent outbox changes (sharing the middleware's pinned connection via IOutboxConnectionAccessor so a consumer's business write commits single-phase with the outbox/inbox writes) were documented in the EF package README, but the published DocFX article was never updated. This closes that gap.

Why

  • The DocFX Outbox article never documented a 2PC requirement to begin with, so nothing there was incorrect — but it also never described the new, recommended single-commit pattern.
  • A consumer that persists business state through its own DbContext needs to know how to avoid escalating to a two-phase (prepared) commit, which on PostgreSQL fails by default (max_prepared_transactions = 0).

Details

The new section explains:

  • Two physical connections → two-phase (prepared) commit, with the 55000: prepared transactions are disabled failure mode and its cost.
  • One shared connection → single-phase commit (recommended) via IOutboxConnectionAccessor, removing the max_prepared_transactions requirement.
  • A wiring example using the (IServiceProvider, DbContextOptionsBuilder) overload, aligned with the article's existing TransferDbContext example.
  • A pointer to the samples that use this pattern.

Docs-only change — no code or behavior affected.

Add a "Consumer Business Writes: Single-Commit vs 2PC" section to the
published Outbox article covering the IOutboxConnectionAccessor pattern:
sharing the middleware's pinned connection lets a consumer's business
write commit single-phase with the outbox and inbox writes, removing the
PostgreSQL max_prepared_transactions requirement. The package README
already documented this; the DocFX article did not.
@asawicki
asawicki merged commit 200f290 into main Jun 28, 2026
1 check passed
@asawicki
asawicki deleted the asawicki/docs/outbox-single-commit-pattern branch June 28, 2026 21:10
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.

1 participant