Upstash Redis is a serverless, pay-per-request Redis database managed by Upstash. Accessible over HTTPS (REST API) or the standard Redis protocol, it fits naturally with Lambda functions and other serverless workloads where persistent connections aren't practical. Stacktape provisions and manages the database as part of your stack.
Upstash Redis uses pay-per-request pricing with no idle costs. See the Upstash pricing page for current rates.
When to use
Upstash Redis is the right choice when your workload is serverless and bursty. Use it for caching, session storage, or rate limiting in Lambda-based applications. Because pricing is per-request with no idle costs, it avoids the minimum monthly spend of a traditional Redis cache.
Choose Upstash Redis when:
- Your compute is primarily Lambda functions — the HTTPS REST API avoids connection-pooling problems.
- Traffic is unpredictable or low-volume — you pay only for commands you run, not for idle hours.
- You want a serverless resource with minimal configuration —
UpstashRedisPropsexposes onlyenableEviction; instance sizing, patching, and replication are not configured through Stacktape. - You need a Redis-compatible store that does not require VPC configuration.
When NOT to use
Upstash Redis is not a drop-in replacement for every Redis workload. Prefer a managed Redis cache (ElastiCache) when:
- You need the lowest possible latency at high throughput — ElastiCache runs inside your VPC with direct network access, avoiding the overhead of HTTPS or public internet routing.
- Your workload is container-based (web services, worker services) with sustained high request rates — per-request pricing becomes expensive compared to per-hour pricing at scale.
- Your application depends on Redis features beyond what Upstash supports — check the Upstash documentation for supported commands before choosing this resource.
| Criteria | Upstash Redis | Redis (ElastiCache) |
|---|---|---|
| Pricing model | Per-request, no idle cost | Per-hour per-node |
| Connection model | HTTPS REST API or standard Redis protocol | Standard Redis protocol (TCP) |
| VPC required | No | Yes |
| Stacktape configuration surface | Only enableEviction | Instance sizing, patching, failover config |
| Best for | Serverless / bursty workloads | High-throughput container workloads |
For most Lambda-based projects, Upstash Redis is the better starting point. Switch to ElastiCache when sustained high-throughput workloads make per-request pricing more expensive than ElastiCache's per-hour pricing.
Provider configuration
Upstash Redis requires providerConfig.upstash in your Stacktape config. This block supplies your Upstash account credentials so Stacktape can provision and manage the database on your behalf. See the basic example below for the shape of the block.
Use the $Secret() directive to reference sensitive credential values instead of hard-coding them in the config file. Create secrets with stacktape secret set before deploying.
Every stack that uses an upstash-redis resource must include providerConfig.upstash. If you have multiple Upstash Redis resources in the same stack, they all share the same provider credentials — you only configure providerConfig.upstash once.
Basic example
The UpstashRedis constructor can be called with an empty object — the only configurable property is enableEviction. However, the stack must still include providerConfig.upstash whenever it contains an Upstash Redis resource. The example below creates an Upstash Redis database and connects it to a Lambda function using connectTo.
The api Lambda function uses connectTo to reference the cache resource. Stacktape automatically injects environment variables with connection details into the function — see Connecting from workloads below.
The providerConfig.upstash block at the top of the returned config is required whenever the stack contains an upstash-redis resource — see Provider configuration above for details on the credential values.
Eviction
By default, Upstash Redis does not evict keys — writes fail when the database reaches its memory limit. For caching workloads where losing old data is acceptable, set enableEviction to true. When enabled, Upstash prioritizes keys with TTL set.
When to enable: the database is used as a cache or for transient data like sessions and rate-limit counters. Keys with a TTL are evicted first, so set a TTL on cache entries to control what gets removed.
When to leave disabled (default): every key matters and you want writes to fail explicitly rather than silently discard data. This is the safer default for session stores or queues where data loss is unacceptable.
Connecting from workloads
Use connectTo to give a compute resource access to your Upstash Redis database. Stacktape injects environment variables with connection details into the consuming workload. Any resource that supports connectTo — including Lambda functions, web services, worker services, and multi-container workloads — can connect this way.
For a resource named cache, the following environment variables are injected:
| Environment variable | Description |
|---|---|
STP_CACHE_HOST | Redis host endpoint |
STP_CACHE_PORT | Redis port |
STP_CACHE_PASSWORD | Database password |
STP_CACHE_REST_TOKEN | Token for the Upstash REST API |
STP_CACHE_REST_URL | URL for the Upstash REST API |
STP_CACHE_REDIS_URL | Redis connection URL |
Variable names follow the pattern STP_[RESOURCE_NAME]_[PARAM], where the resource name is converted to SCREAMING_SNAKE_CASE. A resource named sessionStore produces STP_SESSION_STORE_HOST, STP_SESSION_STORE_REST_URL, and so on.
Using the REST API
The Upstash REST API lets you run Redis commands over HTTPS without a persistent connection or Redis client library. This is the recommended approach for Lambda functions, because it avoids the connection-pooling problems that traditional Redis clients have in Lambda's ephemeral execution model.
You can call the REST API directly with fetch():
The @upstash/redis npm package wraps the REST API with a Redis-like TypeScript interface:
Using the Redis protocol
Upstash Redis also supports the standard Redis protocol. Use the STP_CACHE_REDIS_URL environment variable with any Redis client library like ioredis:
For Lambda functions, prefer the REST API or @upstash/redis over a traditional Redis client. Traditional clients open persistent TCP connections that don't map well to Lambda's ephemeral execution model and can exhaust connection limits under high concurrency.
Referenceable parameters
Use $ResourceParam() to reference Upstash Redis parameters in other parts of your config — for example, to pass the host or REST URL as an environment variable to a resource that doesn't support connectTo.
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
Hostname (address) of the Upstash Redis database.
- Usage:
$ResourceParam('<<resource-name>>', 'host')
Port of the Upstash Redis database.
- Usage:
$ResourceParam('<<resource-name>>', 'port')
Autogenerated password that can be used to authenticate towards the database.
- Usage:
$ResourceParam('<<resource-name>>', 'password')
Rest token which can be used when reading/writing from/to the database using the REST API
- Usage:
$ResourceParam('<<resource-name>>', 'restToken')
Rest token which can be used only for reading from the database using the REST API
- Usage:
$ResourceParam('<<resource-name>>', 'readOnlyRestToken')
Rest URL which can be used when communicating with the database using the REST API
- Usage:
$ResourceParam('<<resource-name>>', 'restUrl')
Standard redis url (including password) which can be used for connecting using cli.
- Usage:
$ResourceParam('<<resource-name>>', 'redisUrl')
API Reference
UpstashRedisPropsUpstash Redis FAQ
When should I use Upstash Redis vs a Redis (ElastiCache)?
Use Upstash Redis for serverless and bursty workloads — primarily Lambda functions — where you want pay-per-request pricing and minimal configuration (the resource exposes only enableEviction). Use a Redis cache (ElastiCache) when your workload is container-based with sustained high throughput or when you need direct in-VPC network access. At low-to-moderate request volume, Upstash is significantly cheaper; at sustained high throughput, ElastiCache's per-hour pricing becomes more cost-effective.
What does Upstash Redis cost?
Upstash uses a pay-per-request pricing model with no idle costs — you pay only for the commands you execute. This makes it especially cost-effective for development stages, staging environments, and low-traffic production workloads. Check the Upstash pricing page for current rates and plan details.
How do I connect to Upstash Redis from a Lambda function?
Add the Upstash Redis resource name to your Lambda function's connectTo list. Stacktape injects environment variables (STP_[RESOURCE_NAME]_REST_URL, STP_[RESOURCE_NAME]_REST_TOKEN, etc.) into your function. Use the @upstash/redis npm package or raw fetch() calls against the REST URL — both avoid the connection-pooling issues that traditional Redis clients have in Lambda.
Does Upstash Redis run inside my VPC?
No. Upstash Redis is a third-party managed service that runs outside your AWS VPC. This means Lambda functions do not need VPC access to reach Upstash Redis. Any compute resource that supports connectTo can connect to it without VPC configuration.
Should I use the REST API or the Redis protocol?
For Lambda functions, use the REST API (via @upstash/redis or raw fetch()). It avoids persistent TCP connections that don't fit Lambda's ephemeral execution model and can exhaust connection limits under concurrency. For container workloads with long-lived processes, either approach works — the standard Redis protocol with a client like ioredis may be simpler if your codebase already uses Redis client libraries.
Why does my deploy fail without providerConfig.upstash?
Every stack that contains an upstash-redis resource must include a providerConfig.upstash block with your Upstash account credentials — this is how Stacktape provisions the database on your behalf. You configure it once per stack even if you have multiple Upstash Redis resources, since they all share the same provider credentials. Use the $Secret() directive for the apiKey instead of hard-coding it.