Skip to main content

​
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);

Build docs developers (and LLMs) love

Get started for freeTalk to us