Idempotent @Retry vs Transactional Outbox for duplicate‑write prevention in Quarkus

The Recommended Approach

For services handling fewer than 100 messages per minute, Idempotent @Retry introduces significantly less operational overhead than the Transactional Outbox pattern. At this scale, the complexity of managing a separate outbox table and its associated polling processor outweighs the risks, provided that idempotency is enforced at the database level rather than through application-level pre-reads.

Comparison of Patterns

Operational Overhead and Storage

• Idempotent @Retry: Negligible overhead. It requires no additional infrastructure or background workers. Storage growth is limited to the business data itself.
• Transactional Outbox: High overhead. You must implement and monitor a separate relay (polling or CDC) to move messages from the outbox table to the destination. Storage grows with every message until the relay successfully processes and deletes the entry.

End-to-End Latency

Pattern	Success Path Latency	Retry/Failure Latency
@Retry	Lowest (direct write)	Increases linearly based on backoff intervals.
Outbox	Moderate (two writes)	Decoupled; primary write is fast, but delivery depends on relay polling frequency.

Failure Recovery and Trade-offs

The primary trade-off is between simplicity and guaranteed delivery. @Retry is ideal for transient network blips but can lead to "retry storms" if the failure is persistent. The Outbox pattern guarantees that a message will eventually be sent if the database transaction commits, regardless of the application's immediate state.

Implementation Steps for Idempotent @Retry

To prevent duplicate rows without the Outbox pattern, avoid "check-then-insert" logic, which is prone to race conditions. Instead, use atomic database constraints:

1. Define a Unique Constraint: Create a unique index on the business key (e.g., transaction_id) in your database schema.
2. Apply @Retry: Annotate your Quarkus service method with @Retry, configuring the maxRetries and delay.
3. Handle Constraint Violations: Ensure the retry logic only triggers on transient exceptions (e.g., ConnectException) and not on UniqueConstraintViolationException, which should be treated as a successful duplicate detection.

Verification

To verify this setup, manually trigger a transient failure (e.g., by briefly pausing the database network) during a request. Confirm that the @Retry mechanism triggers and that the database contains exactly one record for the business key despite multiple attempts.

Diagnostic Detail Needed: Are the "writes" in question strictly internal database inserts, or do they involve calling external third-party APIs? If external APIs are involved, @Retry alone cannot guarantee idempotency unless the external API also supports idempotent keys.