Client configuration

Configure the Upstash Redis client with connection credentials, retry behavior, and advanced options

Overview

The Upstash Redis client provides several configuration options to customize behavior for your environment and use case. Configuration varies slightly between platforms, but all platforms share common options.

Basic configuration

Create a Redis client with your Upstash credentials:

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

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

Get your credentials from the Upstash Console under your database details.

Configuration from environment variables

Load credentials automatically from environment variables:

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

const redis = Redis.fromEnv();

This method reads from:

• UPSTASH_REDIS_REST_URL or KV_REST_API_URL for the URL
• UPSTASH_REDIS_REST_TOKEN or KV_REST_API_TOKEN for the token

The KV_* variables provide compatibility with Vercel KV and other platforms that use different naming conventions.

Configuration options

Connection credentials

url · string · required

The REST URL for your Upstash Redis database. Find this in the Upstash Console under UPSTASH_REDIS_REST_URL.

token · string · required

The authentication token for your database. Find this in the Upstash Console under UPSTASH_REDIS_REST_TOKEN.

HTTP and retry options

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

Configure retry behavior for network errors.

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  retry: {
    retries: 3,
    backoff: (retryCount) => Math.exp(retryCount) * 100,
  },
});

Set to false to disable retries:

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

RetryConfig properties:

• retries (number, default: 5): Maximum number of retry attempts
• backoff (function): Function that returns wait time in milliseconds given the retry count

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

Controls how response data is encoded for transfer.

By default, the server base64-encodes responses to safely handle non-UTF8 data like emojis. For very large responses with guaranteed UTF8 data, you can disable this:

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

Only disable base64 encoding if you’re certain your data is valid UTF8. Invalid data will cause parsing errors.

cache · CacheSetting · default: "'no-store'"

Configure HTTP cache behavior. Options: "default", "force-cache", "no-cache", "no-store", "only-if-cached", "reload".

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
  cache: "no-store",
});

signal · AbortSignal | (() => AbortSignal)

Provide an AbortSignal to cancel in-flight requests.

const controller = new AbortController();

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

// Cancel all future requests
controller.abort();

Redis client options

automaticDeserialization · boolean · default: "true"

Automatically deserialize JSON responses from Redis using JSON.parse.

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

await redis.set("user", { name: "Alice", age: 30 });
const user = await redis.get("user"); // Returns { name: "Alice", age: 30 }

enableAutoPipelining · boolean · default: "true"

Enable automatic command pipelining for improved performance. See auto-pipeline for details.

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

readYourWrites · boolean · default: "true"

Ensure read-your-writes consistency. See read-your-writes for details.

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

latencyLogging · boolean · default: "false"

Log the latency of each command to the console for debugging.

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

await redis.get("key");
// Console output: Latency for GET: 45.23 ms

enableTelemetry · boolean · default: "true"

Send anonymous telemetry data to help improve the SDK. Collected data includes SDK version, platform, and runtime version.

Disable telemetry:

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

Or set the UPSTASH_DISABLE_TELEMETRY environment variable:

UPSTASH_DISABLE_TELEMETRY=1

Node.js specific options

agent · unknown

Provide a custom HTTP agent for connection reuse (Node.js only).

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

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

This option is not supported in edge runtimes like Vercel Edge Functions or Cloudflare Workers.

keepAlive · boolean · default: "true"

Enable HTTP keep-alive for connection reuse.

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

Platform-specific imports

Cloudflare Workers

Import from the Cloudflare-specific entrypoint:

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

export default {
  async fetch(request: Request, env: Env) {
    const redis = new Redis({
      url: env.UPSTASH_REDIS_REST_URL,
      token: env.UPSTASH_REDIS_REST_TOKEN,
    });
    
    // Or use fromEnv with module workers
    const redis2 = Redis.fromEnv(env);
    
    // Use redis...
  },
};

Node.js

Use the standard import:

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

Advanced: custom requester

For advanced use cases, provide a custom 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);