Skip to content
sst-community
Docs Examples
GitHub Discord

Redis

The Redis component lets you add a Redis cluster to your app using Amazon ElastiCache.

Create the cluster

sst.config.ts
const vpc = new sst.aws.Vpc("MyVpc");
const redis = new sst.aws.Redis("MyRedis", { vpc });

Create a serverless Redis

You can also create a serverless Redis instance that automatically scales based on usage. Check out the serverless example. It connects with the same username and password as a provisioned Redis.

sst.config.ts
const vpc = new sst.aws.Vpc("MyVpc");
const redis = new sst.aws.Redis("MyRedis", {
  vpc,
  serverless: true
});

Configure serverless limits.

sst.config.ts
const redis = new sst.aws.Redis("MyRedis", {
  vpc,
  serverless: {
    storage: { maximum: "100 GB" },
    ecpuPerSecond: { maximum: 50000 }
  }
});

You can link your cluster to other resources, like a function or your Next.js app.

sst.config.ts
new sst.aws.Nextjs("MyWeb", {
  link: [redis],
  vpc
});

Once linked, you can connect to it from your function code.

app/page.tsx
import { Resource } from "sst";
import { Cluster } from "ioredis";


const client = new Cluster(
  [{
    host: Resource.MyRedis.host,
    port: Resource.MyRedis.port
  }],
  {
    redisOptions: {
      tls: { checkServerIdentity: () => undefined },
      username: Resource.MyRedis.username,
      password: Resource.MyRedis.password
    }
  }
);

Running locally

By default, your Redis cluster is deployed in sst dev. But let’s say you are running Redis locally.

Terminal window
docker run \
  --rm \
  -p 6379:6379 \
  -v $(pwd)/.sst/storage/redis:/data \
  redis:latest

You can connect to it in sst dev by configuring the dev prop.

sst.config.ts
const redis = new sst.aws.Redis("MyRedis", {
  vpc,
  dev: {
    host: "localhost",
    port: 6379
  }
});

This will skip deploying a Redis ElastiCache cluster and link to the locally running Redis server instead. Check out the full example.

Cost

By default this component uses On-demand nodes with a single cache.t4g.micro instance.

The default redis engine costs $0.016 per hour. That works out to $0.016 x 24 x 30 or $12 per month.

If the valkey engine is used, the cost is $0.0128 per hour. That works out to $0.0128 x 24 x 30 or $9 per month.

Adjust this for the instance type and number of nodes you are using.

With serverless, you pay for the data stored and the ECPUs used instead. A serverless cache is billed for at least 1 GB of storage, even when idle, and setting a minimum raises that floor. The maximum limits cap what it can cost. Check out the ElastiCache Serverless pricing.

The above are rough estimates for us-east-1, check out the ElastiCache pricing for more details.

Constructor

new Redis(name, args, opts?)

Parameters

RedisArgs

cluster?

Type Input<boolean | Object>

Default { nodes: 1 }

Configure cluster mode for Redis.

Disable cluster mode.

{
  cluster: false
}

cluster.nodes

Type Input<number>

Default 1

The number of nodes to use for the Redis cluster.

{
  nodes: 4
}

dev?

Type Object

Configure how this component works in sst dev.

By default, your Redis instance is deployed in sst dev. But if you want to instead connect to a locally running Redis server, you can configure the dev prop.

This will skip deploying a Redis ElastiCache instance and link to the locally running Redis server instead.

Setting the dev prop also means that any linked resources will connect to the right Redis instance both in sst dev and sst deploy.

{
  dev: {
    host: "localhost",
    port: 6379
  }
}

dev.host?

Type Input<string>

Default “localhost”

The host of the local Redis server to connect to when running in dev.

dev.password?

Type Input<string>

Default No password

The password of the local Redis server to connect to when running in dev.

dev.port?

Type Input<number>

Default 6379

The port of the local Redis server when running in dev.

dev.username?

Type Input<string>

Default “default”

The username of the local Redis server to connect to when running in dev.

engine?

Type Input<“redis” | “valkey”>

Default “redis”

The Redis engine to use. The following engines are supported:

  • "redis": The open-source version of Redis.
  • "valkey": Valkey is a Redis-compatible in-memory key-value store.

instance?

Type Input<string>

Default “t4g.micro”

The type of instance to use for the nodes of the Redis instance. Check out the supported instance types.

{
  instance: "m7g.xlarge"
}

parameters?

Type Input<Record<string, Input<string>>>

Key-value pairs that define custom parameters for the Redis’s parameter group. These values override the defaults set by AWS.

{
  parameters: {
    "maxmemory-policy": "noeviction"
  }
}

serverless?

Type boolean | Object

Default false

Use Amazon ElastiCache Serverless instead of a provisioned cluster. It scales with your usage and you pay for the data stored and the compute you use.

A serverless cache needs version 7 or later, which the defaults are. A lower version fails with an error. Only the major part of version is used, so "7.2" is sent as "7" and ElastiCache picks the minor version.

When this is set, instance, cluster, nodes and parameters are ignored, and transform.subnetGroup, transform.parameterGroup and transform.cluster don’t run. Use transform.serverlessCache instead. The password is set through an ElastiCache user and user group that SST creates for the cache.

A serverless cache always uses TLS. By default SST also gives it a generated password for the default user, like a provisioned cluster, so the linked resource has the same host, port, username and password, and the code that connects to it doesn’t change. Turn it off with password: false.

Use the default limits.

{
  serverless: true
}

Set your own limits. These cap how far the cache scales, and so what it can cost.

{
  serverless: {
    storage: { maximum: "100 GB" },
    ecpuPerSecond: { maximum: 50000 }
  }
}

serverless.ecpuPerSecond?

Type Input<Object>

Default { maximum: 5000 }

The ElastiCache Processing Units (ECPU) the cache can use per second. A minimum and a maximum have to be at least 1, and the minimum can’t be above the maximum.

{
  ecpuPerSecond: { minimum: 1000, maximum: 50000 }
}
serverless.ecpuPerSecond.maximum?

Type Input<number>

The most ECPUs per second the cache can use.

serverless.ecpuPerSecond.minimum?

Type Input<number>

The smallest number of ECPUs per second the cache keeps available.

serverless.password?

Type boolean

Default true

Protect the cache with a password. SST generates one for the default user and links it as password, like a provisioned cluster. Without a password, anything that can reach the cache inside the VPC can read and write it.

Set this to false for a cache with no password. Then the link has host, port and username, and no password.

Linked resources get the password, and sst shell has it in Resource.MyRedis.password.

With a password, the deploy role needs these ElastiCache actions, on top of the ones for the cache: elasticache:CreateUser, elasticache:DescribeUsers, elasticache:DeleteUser, elasticache:CreateUserGroup, elasticache:DescribeUserGroups and elasticache:DeleteUserGroup. Changing a setting later may also call the matching Modify actions.

serverless.storage?

Type Input<Object>

Default { maximum: “10 GB” }

The amount of data the cache can store, in whole GB. A fraction is rounded up. A minimum and a maximum have to be at least 1 GB, and the minimum can’t be above the maximum.

{
  storage: { minimum: "1 GB", maximum: "100 GB" }
}
serverless.storage.maximum?

Type Input<“${number} GB”>

The most data the cache can store.

serverless.storage.minimum?

Type Input<“${number} GB”>

The smallest amount of storage the cache keeps available.

transform?

Type Object

Transform how this component creates its underlying resources.

transform.cluster?

Type ReplicationGroupArgs | (args: ReplicationGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Redis cluster.

transform.parameterGroup?

Type ParameterGroupArgs | (args: ParameterGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Redis parameter group.

transform.serverlessCache?

Type ServerlessCacheArgs | (args: ServerlessCacheArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Redis serverless cache.

transform.subnetGroup?

Type SubnetGroupArgs | (args: SubnetGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Redis subnet group.

version?

Type Input<string>

Default "7.1" for Redis, "7.2" for Valkey

The version of Redis.

The default is "7.1" for the "redis" engine and "7.2" for the "valkey" engine.

Check out the supported versions.

{
  version: "6.2"
}

vpc

Type Vpc | Input<Object>

The VPC to use for the Redis instance.

Create a VPC component.

const myVpc = new sst.aws.Vpc("MyVpc");

And pass it in.

{
  vpc: myVpc
}

Or pass in a custom VPC configuration.

{
  vpc: {
    subnets: ["subnet-0db7376a7ad4db5fd ", "subnet-06fc7ee8319b2c0ce"],
    securityGroups: ["sg-0399348378a4c256c"]
  }
}

vpc.securityGroups

Type Input<Input<string>[]>

A list of VPC security group IDs.

vpc.subnets

Type Input<Input<string>[]>

A list of subnet IDs in the VPC to deploy the Redis instance in.

Properties

clusterId

Type Output<string>

The ID of the Redis cluster, or of the serverless cache when serverless is set. Redis.get only works with the ID of a cluster.

host

Type Output<string>

The host to connect to the Redis cluster.

nodes

Type Object

The underlying resources this component creates.

nodes.cluster

Type Output<ReplicationGroup>

The ElastiCache Redis cluster. This throws when serverless is set, use serverlessCache instead.

nodes.serverlessCache

Type ServerlessCache

The ElastiCache Redis serverless cache. This throws when serverless is not set, use cluster instead.

password

Type undefined | Output<string>

The password to connect to the Redis cluster. This is undefined for a serverless cache with password: false.

port

Type Output<number>

The port to connect to the Redis cluster.

username

Type Output<string>

The username to connect to the Redis cluster.

SDK

Use the SDK in your runtime to interact with your infrastructure.

This is accessible through the Resource object in the SDK.

  • host string

    The host to connect to the Redis cluster.

  • password? string

    The password to connect to the Redis cluster. This is undefined for a serverless cache with password: false.

  • port number

    The port to connect to the Redis cluster.

  • username string

    The username to connect to the Redis cluster.

Methods

static get

Redis.get(name, clusterId, opts?)

Parameters

  • name string

    The name of the component.

  • clusterId Input<string>

    The id of the existing Redis cluster.

  • opts? ComponentResourceOptions

    Resource options.

Returns Redis

Reference an existing Redis cluster with the given cluster name. This is useful when you create a Redis cluster in one stage and want to share it in another. It avoids having to create a new Redis cluster in the other stage.

Imagine you create a cluster in the dev stage. And in your personal stage frank, instead of creating a new cluster, you want to share the same cluster from dev.

sst.config.ts
const redis = $app.stage === "frank"
  ? sst.aws.Redis.get("MyRedis", "app-dev-myredis")
  : new sst.aws.Redis("MyRedis");

Here app-dev-myredis is the ID of the cluster created in the dev stage. You can find this by outputting the cluster ID in the dev stage.

sst.config.ts
return {
  cluster: redis.clusterId
};