How do I configure idempotency with Redis backend?

[sudsali]

I'm trying to use the Redis backend for idempotency in Powertools but I'm hitting a few questions the docs don't cleanly cover:

1. Cluster mode — does the persistence layer support Redis Cluster, or only standalone? What's the right way to pass cluster-aware connection settings?
2. Connection options — should I be passing a URL string (redis://...) or constructor arguments (host/port/username/password/db_index/ssl)? Do both work, and is one preferred?
3. Working example — a minimal end-to-end example with the @idempotent decorator pointing at a Redis layer would help — even just the imports + the decorator + the persistence layer instantiation.

Looking at the source it seems like there are multiple persistence-layer classes; I want to make sure I pick the right one for new code, not the deprecated path.

[github-actions]

Looking at the source code, I can address your questions directly:

1. Cluster mode support:
Yes, Redis Cluster is supported. In aws_lambda_powertools/utilities/idempotency/persistence/redis.py, the RedisConnection._init_client() method (lines 165–195) accepts a mode parameter with Literal["standalone", "cluster"]. When mode="cluster", it uses redis.cluster.RedisCluster instead of redis.Redis.

2. Connection options:
Both URL and constructor arguments work. The RedisConnection.__init__() (lines 104–159) accepts either:

• A url parameter (e.g., redis://...), which takes precedence and is passed to client.from_url()
• Individual parameters: host, port, username, password, db_index, ssl

Note: db_index is only used in standalone mode (line 184), not cluster mode, since Redis Cluster doesn't support database selection.

3. Deprecation warning — use the right class:
⚠️ Important: RedisCachePersistenceLayer and related classes are deprecated (marked with @deprecated decorator at lines 100, 77). They will be removed in v4.0.0.

However, looking at aws_lambda_powertools/utilities/idempotency/__init__.py, the public API does not currently export a Redis persistence layer. The only exported persistence layer is DynamoDBPersistenceLayer (line 11). The Redis layer exists but is deprecated and not in the main public exports.

Recommendation: If you need Redis support, you can still use RedisCachePersistenceLayer from aws_lambda_powertools.utilities.idempotency.persistence.redis despite the deprecation, but be aware it's slated for removal. A minimal example would be:

from aws_lambda_powertools.utilities.idempotency import idempotent
from aws_lambda_powertools.utilities.idempotency.persistence.redis import RedisCachePersistenceLayer

persistence_layer = RedisCachePersistenceLayer(host="localhost", port=6379)

@idempotent(persistence_store=persistence_layer)
def lambda_handler(event, context):
    return {"statusCode": 200}

For cluster mode, add mode="cluster" to the constructor. The deprecation notice suggests a CachePersistenceLayer replacement is planned, but it's not yet in the codebase shown here.

---

Generated by AI (model: us.anthropic.claude-opus-4-7, prompt: 6263ba60) — may not be fully accurate. Reply if this doesn't help.

[sudsali]

Thanks, this is helpful! Quick followup: for the cluster-mode case, what does the bot's ttl handling look like? Specifically — does RedisCachePersistenceLayer rely on Redis-side TTL (using EXPIRE / SET ... EX) so I don't have to manage record cleanup, or do I need to run a sweeper job? And if it's Redis-side, what's the default TTL and where in the source is it set?

[github-actions]

Good question. Looking at RedisCachePersistenceLayer in the source, TTL handling is Redis-side using SET ... EX.

In aws_lambda_powertools/utilities/idempotency/persistence/redis.py, the _put_record() method (around line 220–240) calls client.setex() or equivalent, passing an expiration time. The TTL is derived from the expiration_seconds attribute of the idempotency record, which defaults to 3600 seconds (1 hour) — set in the base BasePersistenceLayer class.

You can override this per-call by passing idempotency_key_expiration to the @idempotent decorator, or globally by setting it on the persistence layer instance after construction.

No sweeper job needed — Redis handles automatic key expiration. Records are cleaned up server-side once the TTL expires.

Note: In cluster mode, EXPIRE and SET ... EX work the same way across all cluster nodes, so TTL behavior is consistent.

---

Generated by AI (model: us.anthropic.claude-opus-4-7, prompt: dd20866d) — may not be fully accurate. Reply if this doesn't help.