@upstash/redis

What is @upstash/redis?

@upstash/redis is an npm package that provides a serverless Redis solution. It allows developers to interact with a Redis database using a simple and efficient API. The package is designed to work seamlessly with serverless environments, making it ideal for modern cloud-based applications.

What are @upstash/redis's main functionalities?

Basic Redis Commands

This feature allows you to perform basic Redis commands such as SET and GET. The code sample demonstrates how to set a key-value pair and retrieve it.

const { Redis } = require('@upstash/redis');
const redis = new Redis({ url: 'your-upstash-redis-url', token: 'your-upstash-token' });

async function run() {
  await redis.set('key', 'value');
  const value = await redis.get('key');
  console.log(value); // Output: 'value'
}

run();

Pub/Sub

This feature allows you to use the Pub/Sub (publish/subscribe) pattern. The code sample demonstrates how to subscribe to a channel and publish a message to it.

const { Redis } = require('@upstash/redis');
const redis = new Redis({ url: 'your-upstash-redis-url', token: 'your-upstash-token' });

async function run() {
  const subscriber = redis.duplicate();
  await subscriber.subscribe('channel', (message) => {
    console.log('Received message:', message);
  });

  await redis.publish('channel', 'Hello, World!');
}

run();

Transactions

This feature allows you to perform transactions in Redis. The code sample demonstrates how to use the MULTI and EXEC commands to execute multiple commands atomically.

const { Redis } = require('@upstash/redis');
const redis = new Redis({ url: 'your-upstash-redis-url', token: 'your-upstash-token' });

async function run() {
  const transaction = redis.multi();
  transaction.set('key1', 'value1');
  transaction.set('key2', 'value2');
  const results = await transaction.exec();
  console.log(results); // Output: [ 'OK', 'OK' ]
}

run();

Other packages similar to @upstash/redis

ioredis

ioredis is a robust, full-featured Redis client for Node.js. It supports all Redis commands, including Pub/Sub and transactions, and provides high availability and cluster support. Compared to @upstash/redis, ioredis is more suitable for traditional server-based environments rather than serverless architectures.

redis

redis is the official Redis client for Node.js. It provides a straightforward API for interacting with a Redis database and supports all standard Redis commands. While it is highly reliable and widely used, it does not offer the serverless-specific optimizations that @upstash/redis provides.

node-redis

node-redis is another popular Redis client for Node.js. It offers a simple and efficient API for performing Redis operations and supports features like Pub/Sub and transactions. Similar to the official redis package, it is designed for traditional server environments rather than serverless setups.

README

Upstash Redis

An HTTP/REST based Redis client built on top of Upstash REST API.

It is the only connectionless (HTTP based) Redis client and designed for:

• Serverless functions (AWS Lambda ...)
• Cloudflare Workers (see the example)
• Fastly Compute@Edge (see the example)
• Next.js, Jamstack ...
• Client side web/mobile applications
• WebAssembly
• and other environments where HTTP is preferred over TCP.

See the list of APIs supported.

Upgrading from v0.2.0?

Please read the migration guide. For further explanation we wrote a blog post.

Quick Start

Install

npm install @upstash/redis

Create database

Create a new redis database on upstash

Environments

We support various platforms, such as nodejs, cloudflare and fastly. Platforms differ slightly when it comes to environment variables and their fetch api. Please use the correct import when deploying to special platforms.

Node.js

Examples: Vercel, Netlify, AWS Lambda

If you are running on nodejs you can set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN as environment variable and create a redis instance like this:

import { Redis } from "@upstash/redis"

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

// or load directly from env
const redis = Redis.fromEnv()

• Code example

Cloudflare Workers

Cloudflare handles environment variables differently than nodejs. Please add UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN using wrangler secret put ... or in the cloudflare dashboard.

Afterwards you can create a redis instance:

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

const redis = new Redis({
  url: <UPSTASH_REDIS_REST_URL>,
  token: <UPSTASH_REDIS_REST_TOKEN>,
})
// or load directly from env
const redis = Redis.fromEnv()

• Code example
• Documentation

Fastly

Fastly introduces a concept called backend. You need to configure a backend in your fastly.toml. An example can be found here. Until the fastly api stabilizes we recommend creating an instance manually:

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

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

• Code example
• Documentation

Working with types

Most commands allow you to provide a type to make working with typescript easier.

const data = await redis.get<MyCustomType>("key")
// data is typed as `MyCustomType`

Migrating to v1

Explicit authentication

The library is no longer automatically trying to load connection secrets from environment variables. You must either supply them yourself:

import { Redis } from "@upstash/redis"

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

Or use one of the static constructors to load from environment variables:

// Nodejs
import { Redis } from "@upstash/redis"
const redis = Redis.fromEnv()

// or when deploying to cloudflare workers
import { Redis } from "@upstash/redis/cloudflare"
const redis = Redis.fromEnv()

Error handling

Errors are now thrown automatically instead of being returned to you.

// old
const { data, error } = await set("key", "value")
if (error) {
  throw new Error(error)
}

// new
const data = await redis.set("key", "value") // error is thrown automatically

Pipeline

v1.0.0 introduces redis pipelines. Pipelining commands allows you to send a single http request with multiple commands.

import { Redis } from "@upstash/redis"

const redis = new Redis({
  /* auth */
})

const p = redis.pipeline()

// Now you can chain multiple commands to create your pipeline:

p.set("key", 2)
p.incr("key")

// or inline:
p.hset("key2", "field", { hello: "world" }).hvals("key2")

// Execute the pipeline once you are done building it:
// `exec` returns an array where each element represents the response of a command in the pipeline.
// You can optionally provide a type like this to get a typed response.
const res = await p.exec<[Type1, Type2, Type3]>()

For more information about pipelines using REST see here.

Advanced

A low level Command class can be imported from @upstash/redis in case you need more control about types and or (de)serialization.

By default all objects you are storing in redis are serialized using JSON.stringify and recursively deserialized as well. Here's an example how you could customize that behaviour. Keep in mind that you need to provide a fetch polyfill if you are running on nodejs. We recommend isomorphic-fetch.

import { Command } from "@upstash/redis/commands"
import { HttpClient } from "@upstash/redis/http"

/**
 * TData represents what the user will enter or receive,
 * TResult is the raw data returned from upstash, which may need to be
 * transformed or parsed.
 */
const deserialize: (raw: TResult) => TData = ...

class CustomGetCommand<TData, TResult> extends Command<TData | null, TResult | null> {
  constructor(key: string, ) {
    super(["get", key], { deserialize })
  }
}

const client = new HttpClient({
  baseUrl: <UPSTASH_REDIS_REST_URL>,
  headers: {
    authorization: `Bearer ${<UPSTASH_REDIS_REST_TOKEN>}`,
  },
})

const res = new CustomGetCommand("key").exec(client)

Javascript MAX_SAFE_INTEGER

Javascript can not handle numbers larger than 2^53 -1 safely and would return wrong results when trying to deserialize them. In these cases the default deserializer will return them as string instead. This might cause a mismatch with your custom types.

await redis.set("key", "101600000000150081467")
const res = await redis<number>("get")

In this example res will still be a string despite the type annotation. Please keep that in mind and adjust accordingly.

Docs

See the documentation for details.

Contributing

Installing dependencies

pnpm install

Database

Create a new redis database on upstash and copy the url and token to .env (See .env.example for reference)

Running tests

pnpm test