upstash-redis

Upstash Redis

Overview

@upstash/redis is a Redis client that talks to an Upstash Redis database over

HTTPS instead of a TCP connection. Because every command is a stateless HTTP

request, it works in environments where a pooled TCP client is awkward or

impossible: Vercel and Netlify functions, Cloudflare Workers, Deno, Bun, and

Next.js middleware. The client serializes and deserializes JavaScript values

automatically, so numbers and objects round-trip without manual JSON.parse.

When to Use This Skill

• Use when the user needs a cache, session store, counter, leaderboard, or

simple queue from a serverless or edge function.

• Use when the user mentions Upstash Redis, UPSTASH_REDIS_REST_URL, or

@upstash/redis.

• Use when migrating an ioredis or node-redis call site to a runtime that

cannot hold a persistent TCP socket.

• Do not use for a self-hosted or non-Upstash Redis server; the client only

speaks the Upstash REST protocol. Use ioredis or node-redis there.

• Do not use for Redis administration or CLI work; see redis-cli.

How It Works

Step 1: Configure credentials

Create a database in the Upstash console and copy the REST URL and token into

environment variables. Never hardcode them.

UPSTASH_REDIS_REST_URL=https://<your-db>.upstash.io
UPSTASH_REDIS_REST_TOKEN=<your-rest-token>

Step 2: Create one client per module

import { Redis } from "@upstash/redis";

export const redis = Redis.fromEnv();

On Cloudflare Workers, import from @upstash/redis/cloudflare and pass the

worker env object: Redis.fromEnv(env).

Step 3: Call Redis commands as methods

Command names are lowercase methods (get, set, hset, zadd, incr).

Values are auto-serialized; pass and receive native JavaScript types.

Examples

Example 1: Cache-aside with a TTL

import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();

export async function getUser(id: string) {
  const cached = await redis.get<{ id: string; name: string }>(`user:${id}`);
  if (cached) return cached;

  const user = await db.users.findById(id);
  await redis.set(`user:${id}`, user, { ex: 3600 }); // expires in 1 hour
  return user;
}

export async function invalidateUser(id: string) {
  await redis.del(`user:${id}`);
}

Example 2: Batch commands in a pipeline

const pipeline = redis.pipeline();
pipeline.hset("user:1", { name: "Alice", plan: "pro" });
pipeline.incr("signups:total");
pipeline.zadd("leaderboard", { score: 120, member: "user:1" });
const [hsetResult, signups, zaddResult] = await pipeline.exec();

pipeline() batches independent commands into one round trip. It is not

atomic; use redis.multi() for MULTI/EXEC or a reviewed server-side Lua script

when commands must run as one unit.

Best Practices

• ✅ Read credentials with Redis.fromEnv() or from a secrets manager.
• ✅ Set a TTL ({ ex: seconds }) on cache entries so stale data expires.
• ✅ Namespace keys (user:123, session:abc) to keep the keyspace readable.
• ✅ Use pipeline() or mget/mset instead of many sequential awaits.
• ❌ Don't JSON.stringify values before set; the client already does it.
• ❌ Don't call keys("*") in request handlers; use scan for large keyspaces.
• ❌ Don't store secrets or PII in Redis without a retention plan and TTL.

Limitations

• Requires an Upstash Redis database; it cannot connect to other Redis servers.
• Each command is an HTTP request, so latency is higher than a warm TCP

connection; batch with pipelines where it matters.

• Transactions (multi()) do not roll back on runtime errors, and WATCH is

not available over REST; use a Lua script for atomic check-and-set.

• Pub/Sub subscribe and blocking commands (BLPOP, XREAD BLOCK) are not

supported over the REST client.

• This skill covers the TypeScript client only. Python, Go, and other SDKs

differ in method names.

• This skill does not replace environment-specific validation, testing, or

expert review.

Security & Safety Notes

• The REST token grants full read/write access to the database. Keep it in

server-side environment variables; never ship it to a browser bundle.

• Use a read-only token from the console for read-only workloads.
• Commands such as flushdb and del are destructive; confirm with the user

before running them against a production database.

Common Pitfalls

• Problem: get returns null in production but works locally.

Solution: The deployment is missing UPSTASH_REDIS_REST_URL or

UPSTASH_REDIS_REST_TOKEN; check the platform's environment settings.

• Problem: A number comes back as a string after incr on a value set

with JSON.stringify.

Solution: Store the raw number (redis.set("n", 1)) and let the client

serialize it.

Related Skills

• @upstash-ratelimit - Rate limiting built on this client.
• @upstash-qstash - HTTP message queue and schedules when you need delivery

guarantees rather than a data store.

• @redis-cli - Inspecting and administering Redis from the command line.
• @bullmq-specialist - Job queues on a TCP Redis you operate yourself.

Additional Resources

• Upstash Redis documentation
• @upstash/redis on GitHub
• TypeScript SDK reference