Redis

Main Redis client class for interacting with Upstash Redis

The Redis class is the main entry point for interacting with Upstash Redis. It provides methods for all Redis commands and supports both direct instantiation and environment-based configuration.

Constructor

With Configuration Object

Create a new Redis client by providing connection credentials.

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

const redis = new Redis({
  url: '<UPSTASH_REDIS_REST_URL>',
  token: '<UPSTASH_REDIS_REST_TOKEN>'
});

config · RedisConfigNodejs · required

Configuration object for the Redis client

Show properties

url · string · required

UPSTASH_REDIS_REST_URL - Get it from your Upstash Console

token · string · required

UPSTASH_REDIS_REST_TOKEN - Get it from your Upstash Console

automaticDeserialization · boolean · default: "true"

Automatically deserialize returned data using JSON.parse

enableTelemetry · boolean · default: "true"

Enable telemetry data collection. Can be disabled by setting UPSTASH_DISABLE_TELEMETRY environment variable

enableAutoPipelining · boolean · default: "true"

Enable automatic pipelining of commands for better performance

latencyLogging · boolean · default: "false"

Enable latency logging for commands

readYourWrites · boolean · default: "true"

When enabled, subsequent commands are guaranteed to observe effects of all earlier writes submitted by the same client

retry · RetryConfig · default: "5 retries with exponential backoff"

Configure retry behavior for network errors

Show properties

retries · number · default: "5"

Number of retries to attempt before giving up

backoff · (retryCount: number) => number

Backoff function that returns milliseconds to wait before retrying. Default: Math.exp(retryCount) * 50

responseEncoding · false | 'base64' · default: "'base64'"

Encode responses as base64 before sending. Disable if you’re sure your data is valid UTF-8

cache · 'default' | 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached' | 'reload' · default: "'no-store'"

Configure cache behavior for requests

signal · AbortSignal

AbortSignal to cancel requests. See MDN AbortSignal

agent · http.Agent | https.Agent

HTTP(S) agent for connection pooling (Node.js only). Not supported in edge runtimes

import https from 'https';

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
  agent: new https.Agent({ keepAlive: true })
});

keepAlive · boolean · default: "true"

Enable HTTP keep-alive for connection reuse

With Custom Requester

Create a Redis client with a custom HTTP requester implementation.

import { Redis, Requester, UpstashRequest, UpstashResponse } from '@upstash/redis';

const customRequester: Requester = {
  request: async <TResult>(req: UpstashRequest): Promise<UpstashResponse<TResult>> => {
    // Custom request implementation
    // ...
  }
};

const redis = new Redis(customRequester);

requester · Requester · required

Custom requester implementation

Show properties

request · <TResult>(req: UpstashRequest) => Promise<UpstashResponse<TResult>> · required

Function that handles HTTP requests to Upstash Redis REST API

readYourWrites · boolean

Enable read-your-writes consistency

upstashSyncToken · string

Sync token for maintaining consistency

Static Methods

fromEnv()

Create a Redis instance from environment variables.

const redis = Redis.fromEnv();

This method automatically loads connection credentials from:

• UPSTASH_REDIS_REST_URL or KV_REST_API_URL (fallback for Vercel KV)
• UPSTASH_REDIS_REST_TOKEN or KV_REST_API_TOKEN (fallback for Vercel KV)

config · Omit<RedisConfigNodejs, 'url' | 'token'>

Optional configuration (all options except url and token)

redis · Redis

A configured Redis instance

const redis = Redis.fromEnv({
  enableAutoPipelining: false,
  latencyLogging: true
});

Properties

readYourWritesSyncToken

Get or set the sync token for read-your-writes consistency.

// Get current sync token
const token = redis.readYourWritesSyncToken;

// Set sync token
redis.readYourWritesSyncToken = 'your-sync-token';

readYourWritesSyncToken · string | undefined

The current sync token

Instance Methods

pipeline()

Create a new pipeline to batch multiple commands.

const pipeline = redis.pipeline();
pipeline.set('key1', 'value1');
pipeline.set('key2', 'value2');
pipeline.get('key1');

const results = await pipeline.exec();
// results: ['OK', 'OK', 'value1']

pipeline · Pipeline

A new Pipeline instance for batching commands

See Pipeline for full documentation.

multi()

Create a transaction (MULTI/EXEC) to execute commands atomically.

const transaction = redis.multi();
transaction.set('key1', 'value1');
transaction.set('key2', 'value2');
transaction.get('key1');

const results = await transaction.exec();
// All commands executed atomically

multi · Pipeline

A new Pipeline instance configured for atomic execution

createScript()

Create a Lua script that can be executed efficiently using EVALSHA.

const script = redis.createScript<string>(
  'return ARGV[1];'
);

const result = await script.eval([], ['Hello World']);
// result: 'Hello World'

script · string · required

The Lua script to execute

opts · { readonly?: boolean }

Script options

Show properties

readonly · boolean · default: "false"

If true, returns a ScriptRO instance that uses EVALSHA_RO/EVAL_RO

script · Script<TResult> | ScriptRO<TResult>

A Script or ScriptRO instance depending on the readonly option

See Script for full documentation.

use()

Wrap middleware around the HTTP client for custom request/response handling.

redis.use(async (request, next) => {
  console.log('Making request:', request);
  const response = await next(request);
  console.log('Received response:', response);
  return response;
});

middleware · (request: UpstashRequest, next: (req: UpstashRequest) => Promise<UpstashResponse<TResult>>) => Promise<UpstashResponse<TResult>> · required

Middleware function to wrap around requests

Command Methods

The Redis class provides methods for all Redis commands. Here are some commonly used examples:

String Commands

// SET
await redis.set('key', 'value');
await redis.set('key', 'value', { ex: 60 }); // with expiration

// GET
const value = await redis.get('key');

// MGET
const values = await redis.mget('key1', 'key2', 'key3');

// MSET
await redis.mset({ key1: 'value1', key2: 'value2' });

// INCR
await redis.incr('counter');

// INCRBY
await redis.incrby('counter', 5);

Hash Commands

// HSET
await redis.hset('user:1', { name: 'John', age: 30 });

// HGET
const name = await redis.hget('user:1', 'name');

// HGETALL
const user = await redis.hgetall('user:1');

// HMGET
const [name, age] = await redis.hmget('user:1', 'name', 'age');

List Commands

// LPUSH
await redis.lpush('list', 'item1', 'item2');

// RPUSH
await redis.rpush('list', 'item3');

// LRANGE
const items = await redis.lrange('list', 0, -1);

// LPOP
const item = await redis.lpop('list');

Set Commands

// SADD
await redis.sadd('set', 'member1', 'member2');

// SMEMBERS
const members = await redis.smembers('set');

// SISMEMBER
const isMember = await redis.sismember('set', 'member1');

Sorted Set Commands

// ZADD
await redis.zadd('leaderboard', { score: 100, member: 'player1' });

// ZRANGE
const topPlayers = await redis.zrange('leaderboard', 0, 9);

// ZRANK
const rank = await redis.zrank('leaderboard', 'player1');

JSON Commands

// JSON.SET
await redis.json.set('user:1', '$', { name: 'John', age: 30 });

// JSON.GET
const user = await redis.json.get('user:1', '$');

// JSON.NUMINCRBY
await redis.json.numincrby('user:1', '$.age', 1);

Key Management

// DEL
await redis.del('key');

// EXISTS
const exists = await redis.exists('key');

// EXPIRE
await redis.expire('key', 60);

// TTL
const ttl = await redis.ttl('key');

// KEYS (use with caution in production)
const keys = await redis.keys('user:*');

Complete Example

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

// Initialize client
const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

// Or use fromEnv
const redis = Redis.fromEnv();

// Simple operations
await redis.set('greeting', 'Hello, World!');
const greeting = await redis.get('greeting');

// Pipelining
const pipeline = redis.pipeline();
pipeline.set('user:1', { name: 'Alice' });
pipeline.set('user:2', { name: 'Bob' });
pipeline.get('user:1');
const results = await pipeline.exec();

// Transactions
const transaction = redis.multi();
transaction.set('balance', 100);
transaction.incrby('balance', 50);
transaction.get('balance');
const [setResult, incrResult, balance] = await transaction.exec();

// Scripts
const myScript = redis.createScript<number>(
  'return redis.call("INCR", KEYS[1])'
);
const counter = await myScript.exec(['mycounter'], []);

TypeScript Support

The Redis client is fully typed with TypeScript generics:

interface User {
  name: string;
  age: number;
}

// Type-safe operations
await redis.set<User>('user:1', { name: 'John', age: 30 });
const user = await redis.get<User>('user:1');
// user is typed as User | null

// JSON operations
await redis.json.set('user:2', '$', { name: 'Jane', age: 25 });
const userData = await redis.json.get<User>('user:2');