/api-database-upstash

name: api-database-upstash
description: Upstash serverless Redis -- REST-based client, auto-serialization, pipelines, rate limiting, QStash, edge compatibility, global replication

Upstash Patterns

> **Quick Guide:** Upstash provides a **REST/HTTP-based Redis client** (`@upstash/redis`) designed for serverless and edge runtimes where TCP connections are unavailable. Unlike ioredis/node-redis, every command is an HTTP request -- no persistent connections, no connection pools, no teardown. The client **automatically serializes/deserializes JSON** (objects stored via `set` come back as objects from `get`), which is convenient but has gotchas with large numbers and cross-client compatibility. Use `redis.pipeline()` to batch commands into a single HTTP request, `redis.multi()` for atomic transactions, and `@upstash/ratelimit` for pre-built rate limiting algorithms. For background jobs, use `@upstash/qstash` which pushes messages to your API via HTTP webhooks.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use `Redis.fromEnv()` for initialization in production code -- never hardcode `UPSTASH_REDIS_REST_URL` or `UPSTASH_REDIS_REST_TOKEN` values)**

**(You MUST handle the `pending` promise from `@upstash/ratelimit` responses in edge runtimes -- use `context.waitUntil(pending)` on Vercel Edge/Cloudflare Workers or analytics data is lost)**

**(You MUST use `redis.pipeline()` when issuing 3+ independent commands in a single handler -- each command is a separate HTTP round-trip without pipelining)**

**(You MUST NOT use Upstash for Pub/Sub, blocking commands (BRPOP, BLPOP, XREAD BLOCK), or Lua scripting -- REST API does not support these; use ioredis with a TCP connection instead)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) -- Client setup, commands, auto-serialization, pipeline, transactions
• [Rate Limiting](examples/rate-limiting.md) -- @upstash/ratelimit algorithms, middleware, analytics
• [QStash](examples/qstash.md) -- Background jobs, scheduling, message publishing

**Additional resources:**

• [reference.md](reference.md) -- Command cheat sheet, constructor options, environment variables, eviction policies

---

**Auto-detection:** Upstash, @upstash/redis, @upstash/ratelimit, @upstash/qstash, Redis.fromEnv, UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN, Ratelimit.slidingWindow, Ratelimit.fixedWindow, Ratelimit.tokenBucket, serverless Redis, edge Redis, REST Redis

**When to use:**

• Serverless functions (AWS Lambda, Vercel, Netlify) that cannot maintain TCP connections
• Edge runtimes (Cloudflare Workers, Vercel Edge, Fastly Compute) that only support HTTP
• Rate limiting API routes with pre-built algorithms (sliding window, fixed window, token bucket)
• Caching in serverless/edge where ioredis connection pooling is impractical
• Background job scheduling with QStash (push-based, no long-running consumers needed)
• Global read latency optimization via Upstash Global Database with read replicas

**Key patterns covered:**

• `@upstash/redis` client setup with `Redis.fromEnv()` and constructor options
• Automatic JSON serialization/deserialization behavior and gotchas
• Pipeline batching (`redis.pipeline()`) and atomic transactions (`redis.multi()`)
• `@upstash/ratelimit` algorithms: sliding window, fixed window, token bucket
• `@upstash/qstash` for serverless background jobs and scheduling
• Global Database architecture (primary + read regions, eventual consistency)
• Edge runtime compatibility and `context.waitUntil()` patterns

**When NOT to use:**

• Long-running servers with persistent connections (use ioredis -- lower latency per command via TCP)
• Pub/Sub, blocking commands, or Lua scripting (REST API does not support these)
• Write-heavy workloads on Global Database (writes always go to primary region)
• Latency-critical paths where per-command HTTP overhead (~5-15ms) is unacceptable (use ioredis with TCP for <1ms per command)
• Large payloads (>1 MB) -- REST API has payload size limits

---

<philosophy>

Philosophy

Upstash exists because **serverless and edge runtimes cannot maintain TCP connections**. Traditional Redis clients (ioredis, node-redis) rely on persistent TCP sockets -- they fail in Cloudflare Workers, break in short-lived Lambda functions, and cannot run in browser/WebAssembly environments. Upstash replaces TCP with REST/HTTP, trading per-command latency (~5-15ms vs <1ms) for universal compatibility.

**Core principles:**

1. **Connectionless by design** -- Every command is a stateless HTTP request. No connection pools, no teardown, no connection limits. This is a feature, not a limitation. 2. **Auto-serialization is default** -- Objects go in, objects come out. No manual `JSON.stringify`/`JSON.parse`. This simplifies 90% of use cases but surprises developers who expect raw string behavior. 3. **Pipeline for performance** -- Without pipelining, N commands = N HTTP requests. Always batch independent commands with `redis.pipeline()` to reduce round-trips. 4. **Rate limiting as a first-class citizen** -- `@upstash/ratelimit` provides production-ready algorithms without writing Lua scripts. The library handles all the Redis plumbing internally. 5. **Push-based messaging** -- QStash delivers messages TO your API via HTTP webhooks. No long-running consumer processes needed -- perfect for serverless.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Setup with Redis.fromEnv()

Initialize using environment variables for zero-config deployment. See [examples/core.md](examples/core.md) for full examples including constructor options and timeout configuration.

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

const redis = Redis.fromEnv();
// Reads UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN automatically

export { redis };

**Why good:** Zero-config, environment variables injected by platform (Vercel, Fly.io), no secrets in code