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