ElastiCache Basics

This page is the working quickstart for ElastiCache: provision a small Redis (or Valkey) cache with the AWS SDK, find the endpoint the SDK reports, and connect to it from application code. The one idea to keep straight throughout is the split introduced in the previous page - the AWS SDK provisions the cache; a Redis client uses it.

Each example is small. Read them in order: create the replication group, wait for it, discover its endpoints, then connect and run SET/GET with a cache client. The AWS SDK snippets use CodeGroup; the connection snippets are plain fences because a Redis client is not the AWS SDK.

Prerequisites

• Python: pip install boto3 redis (boto3 1.43.x, redis-py 5.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-elasticache ioredis (Node.js 18+).
• Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.
• A VPC with a cache subnet group and a security group that allows TCP 6379 from your application. ElastiCache is only reachable from inside its VPC, never the public internet.
• A region set with AWS_REGION or passed per client. These examples assume us-east-1.

Quick Install

# --- Python (boto3) --- AWS SDK client for the ElastiCache control plane.
import boto3
 
ec = boto3.client("elasticache", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) --- AWS SDK client for the ElastiCache control plane.
import { ElastiCacheClient } from "@aws-sdk/client-elasticache";
 
const ec = new ElastiCacheClient({ region: "us-east-1" });

Basic Examples

1. Provision a Small Redis Replication Group

Create a two-node Redis replication group: one primary plus one replica, with encryption on. NumCacheClusters: 2 means one writer and one reader - this is non-cluster (single-shard) mode, which is the right default until you need sharding.

# --- Python (boto3) ---
ec.create_replication_group(
    ReplicationGroupId="app-cache",
    ReplicationGroupDescription="App read cache",
    Engine="redis",                 # or "valkey"
    EngineVersion="7.1",
    CacheNodeType="cache.t4g.micro",
    NumCacheClusters=2,             # 1 primary + 1 replica (single shard)
    AutomaticFailoverEnabled=True,
    MultiAZEnabled=True,
    AtRestEncryptionEnabled=True,
    TransitEncryptionEnabled=True,
    CacheSubnetGroupName="app-cache-subnets",
    SecurityGroupIds=["sg-0123456789abcdef0"],
)

// --- TypeScript (AWS SDK v3) ---
import { CreateReplicationGroupCommand } from "@aws-sdk/client-elasticache";
 
await ec.send(new CreateReplicationGroupCommand({
  ReplicationGroupId: "app-cache",
  ReplicationGroupDescription: "App read cache",
  Engine: "redis",                 // or "valkey"
  EngineVersion: "7.1",
  CacheNodeType: "cache.t4g.micro",
  NumCacheClusters: 2,             // 1 primary + 1 replica (single shard)
  AutomaticFailoverEnabled: true,
  MultiAZEnabled: true,
  AtRestEncryptionEnabled: true,
  TransitEncryptionEnabled: true,
  CacheSubnetGroupName: "app-cache-subnets",
  SecurityGroupIds: ["sg-0123456789abcdef0"],
}));

• CreateReplicationGroup is the Redis/Valkey call - it provisions the nodes but returns before they are ready.
• AutomaticFailoverEnabled with MultiAZEnabled promotes a replica automatically if the primary fails.
• TransitEncryptionEnabled turns on TLS - the client must then connect with rediss://, not redis://.
• Switch Engine to "valkey" for the drop-in, lower-cost Valkey engine; everything else is identical.

Related: Redis vs Memcached: Choosing an Engine.

2. Wait Until It Is Available

Provisioning takes minutes. Block until the group reports available before you try to read its endpoint or connect.

# --- Python (boto3) ---
ec.get_waiter("replication_group_available").wait(ReplicationGroupId="app-cache")
print("cache is available")

// --- TypeScript (AWS SDK v3) ---
import { waitUntilReplicationGroupAvailable } from "@aws-sdk/client-elasticache";
 
await waitUntilReplicationGroupAvailable(
  { client: ec, maxWaitTime: 900 },
  { ReplicationGroupId: "app-cache" },
);
console.log("cache is available");

• The waiter polls DescribeReplicationGroups until Status is available, so you do not hand-roll a loop.
• A fresh Redis replication group typically takes several minutes to reach available.
• Give the waiter a generous maxWaitTime (here 900 seconds) - creation can exceed the default.
• Do not connect a Redis client before this returns; the endpoint DNS may not resolve yet.

Related: Cluster Mode & Endpoint Discovery.

3. Discover the Endpoints

Ask the SDK where to connect. A single-shard Redis group exposes a primary endpoint for writes and a reader endpoint for reads.

# --- Python (boto3) ---
group = ec.describe_replication_groups(ReplicationGroupId="app-cache")["ReplicationGroups"][0]
node_group = group["NodeGroups"][0]
primary = node_group["PrimaryEndpoint"]["Address"]
reader = node_group["ReaderEndpoint"]["Address"]
print(f"primary={primary} reader={reader}")

// --- TypeScript (AWS SDK v3) ---
import { DescribeReplicationGroupsCommand } from "@aws-sdk/client-elasticache";
 
const out = await ec.send(new DescribeReplicationGroupsCommand({ ReplicationGroupId: "app-cache" }));
const nodeGroup = out.ReplicationGroups![0].NodeGroups![0];
const primary = nodeGroup.PrimaryEndpoint!.Address;
const reader = nodeGroup.ReaderEndpoint!.Address;
console.log(`primary=${primary} reader=${reader}`);

• The primary endpoint accepts writes; the reader endpoint load-balances reads across replicas.
• Both are stable DNS names - they keep working across a failover, so hard-code neither node's IP.
• Port defaults to 6379; read it from PrimaryEndpoint.Port rather than assuming.
• These addresses feed your Redis client's connection config, not any further AWS SDK call.

Related: ElastiCache's Role Between App and Database.

Intermediate Examples

4. Connect and Run GET/SET (Redis Client, not the AWS SDK)

Now leave the AWS SDK behind. The snippets below use a Redis client library - redis-py in Python, ioredis in JavaScript - pointed at the endpoint the SDK reported. Because the group was created with in-transit encryption, the connection uses TLS.

# --- Python: redis-py (cache client, NOT the AWS SDK) ---
import redis
 
# Point at the PRIMARY endpoint for writes; rediss:// because TLS is on.
r = redis.Redis(host=primary, port=6379, ssl=True, decode_responses=True)
 
r.set("user:1", "Ada", ex=300)      # SET with a 300s TTL
print(r.get("user:1"))              # -> "Ada" (a cache hit)

// --- Node.js: ioredis (cache client, NOT the AWS SDK) ---
import Redis from "ioredis";
 
// tls:{} enables encryption in transit; host is the PRIMARY endpoint.
const r = new Redis({ host: primary, port: 6379, tls: {} });
 
await r.set("user:1", "Ada", "EX", 300); // SET with a 300s TTL
console.log(await r.get("user:1"));       // -> "Ada" (a cache hit)

• These are third-party clients speaking the Redis wire protocol - AWS does not ship them and the AWS SDK does not wrap them.
• ex=300 / "EX", 300 attach a TTL so the entry self-expires after five minutes.
• Use the reader endpoint for read-only clients to spread reads across replicas.
• decode_responses=True (redis-py) returns strings instead of bytes; omit it if you store binary.

Related: Cache-Aside & Write-Through Patterns with Redis.

5. A Minimal Cache-Aside Read

Put the pieces together into the read loop that motivates the whole service: check the cache, fall back to the database on a miss, and populate the cache for next time.

# --- Python: redis-py + your DB (cache client, NOT the AWS SDK) ---
def get_user(user_id: str) -> str:
    key = f"user:{user_id}"
    cached = r.get(key)
    if cached is not None:
        return cached                       # cache hit
    row = db_fetch_user(user_id)            # cache miss -> backing store
    r.set(key, row, ex=300)                 # populate for next time
    return row

// --- Node.js: ioredis + your DB (cache client, NOT the AWS SDK) ---
async function getUser(userId) {
  const key = `user:${userId}`;
  const cached = await r.get(key);
  if (cached !== null) return cached;       // cache hit
  const row = await dbFetchUser(userId);    // cache miss -> backing store
  await r.set(key, row, "EX", 300);         // populate for next time
  return row;
}

• The first call for a key misses and reads the database; subsequent calls hit for the TTL window.
• The database is untouched on a hit - this is exactly how a cache sheds read load.
• The code must be correct with a cold, empty cache - every miss simply costs one database read.
• The full pattern, including write-through and invalidation, has its own page.

Related: ElastiCache via SDK Best Practices.

Deep Dive

The Two-Tool Split

Everything on this page falls into one of two buckets. The AWS SDK (create_replication_group, waiters, describe_replication_groups) is the control plane: it stands the cache up and tells you where it lives. The Redis client (redis.Redis, new Redis) is the data plane: it moves keys and values. You provision once, at deploy time, with the AWS SDK; you read and write thousands of times per second with the Redis client. Keeping these separate in your head prevents the most common beginner confusion - looking for a get_item on the ElastiCache SDK client that does not exist.

Endpoints and Failover

The primary and reader endpoints are DNS names managed by AWS, not fixed IPs. When AutomaticFailoverEnabled promotes a replica after a primary failure, AWS repoints the primary endpoint DNS at the new primary. Your client keeps using the same hostname and reconnects. This is why you configure clients with endpoints, never with node addresses - the indirection is the failover mechanism.

Encryption Changes the Connection String

Creating the group with TransitEncryptionEnabled=True means every client must use TLS: ssl=True in redis-py, tls: {} in ioredis, or a rediss:// URL. Forgetting this yields a connection that hangs or is refused. If you also set AuthToken (a password) or use IAM authentication, the client must supply that credential too.

Gotchas

• Calling the SDK to read a key. There is no get/set on the ElastiCache SDK client. Fix: provision with the AWS SDK, then read and write with a Redis client library.
• Connecting before available. The endpoint DNS may not resolve during creation. Fix: block on the replication_group_available waiter first.
• Plaintext client against a TLS cache. With TransitEncryptionEnabled=True, a redis:// client hangs or is refused. Fix: use ssl=True / tls: {} / rediss://.
• Trying to reach the cache from your laptop. ElastiCache lives in a VPC with no public endpoint. Fix: run the client inside the VPC (EC2, Lambda in-VPC, ECS) or tunnel through a bastion.
• Hard-coding a node IP. IPs change on failover and replacement. Fix: always connect to the primary/reader endpoint DNS names from DescribeReplicationGroups.
• No TTL on cached entries. Without ex/EX, entries live until evicted and can serve stale data indefinitely. Fix: set a deliberate TTL on writes.

FAQs

Related

• ElastiCache's Role Between App and Database - the control-plane vs data-plane split in full.
• Redis vs Memcached: Choosing an Engine - which engine this quickstart should provision.
• Cluster Mode & Endpoint Discovery - sharding and the configuration endpoint.
• Cache-Aside & Write-Through Patterns with Redis - the read/write loops built on this connection.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).