rrezartprebreza/spring-boot-skills / skills/spring-boot-3/idempotency-patterns
idempotency-patterns
VerifiedUse when making retried HTTP commands or message processing safe against duplicate effects, including database-backed request keys, payload conflicts and concurrent retries. Do not apply caching as a substitute for business idempotency.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| agents/openai.yaml | config | 261 B |
| examples/bad-idempotency.java | other | 303 B |
| examples/good-idempotency.sql | other | 964 B |
SKILL.md
View on GitHub---
name: idempotency-patterns
description: >
Use when making retried HTTP commands or message processing safe against duplicate effects, including database-backed request keys, payload conflicts and concurrent retries. Do not apply caching as a substitute for business idempotency.
---
# Idempotency Patterns
## Spring Boot 3 baseline
The examples use Java 17 and Jakarta APIs supported by this Boot version. Keep dependencies managed by the project's Boot BOM.
## Define the contract
Identify the authenticated tenant/principal, operation, idempotency key, canonical request hash,
retention window and replayable result. Scope uniqueness by principal/tenant and operation;
a raw client key must never allow reading another user's result. Authenticate and authorize
before both initial execution and replay. Bound key length and stored response size.
Document what same-key/different-payload and still-in-progress requests return.
## Database-local effects
For PostgreSQL, [the schema and claim example](examples/good-idempotency.sql) uses a composite
primary key and INSERT ON CONFLICT DO NOTHING RETURNING. In a single database transaction:
claim the key, apply the business write, store the resulting status/body/selected headers,
then commit. Roll back the claim with the business mutation on failure.
If the insert returns no row, load the existing result in a subsequent statement under READ
COMMITTED, compare the canonical hash and replay only when it matches. A concurrent insert
waits on the uniqueness constraint; bound lock waits and return a documented retryable outcome
on timeout. With snapshot isolation, serialization failures require retrying the whole transaction.
Do not catch a unique-constraint violation and continue in an already-aborted transaction.
A result row and business write must use the same transaction manager and database. Return
the stored result rather than reconstructing it from mutable current entity state.
Keep replay headers allowlisted; do not persist cookies, bearer tokens or hop-by-hop headers.
## External effects and messages
A database transaction cannot atomically include an HTTP payment or email. Write an outbox record
with the business mutation and let a retryable worker perform the external effect using the
provider's idempotency support. Reconcile uncertain outcomes before retrying irreversible effects.
For messages, record a unique consumer/event pair and apply the projection in one transaction;
acknowledge only after commit. Retry failed transactions and route poison messages deliberately.
Define retention from the real client retry window. Deleting a key permits a later repeat to
execute again; do not present TTL as an exactly-once guarantee. Protect stored responses as
application data and delete them according to the project's retention policy.
## Verification
Test simultaneous identical requests, conflicting payloads, tenant separation, rollback after
claim, response replay after a lost connection and retries following a worker crash.
Use the production database engine for lock and isolation tests, not H2 compatibility mode.
[The bad example](examples/bad-idempotency.java) illustrates the check-then-act race.
## Gotchas
- Agent checks existence then inserts - enforce uniqueness in the database.
- Agent uses a JVM map or Redis TTL as the only business guard - coordinate with the actual write transaction.
- Agent replays another tenant's result - scope the key and re-authorize.
- Agent retries an external effect after a timeout blindly - reconcile or use provider idempotency.
- Agent deletes keys too early - document the retry window and expiry semantics.
## Official sources
- [PostgreSQL INSERT and ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html)
- [PostgreSQL transaction isolation](https://www.postgresql.org/docs/current/transaction-iso.html)
- [Spring transaction management](https://docs.spring.io/spring-framework/reference/data-access/transaction.html)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |