@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

@upstash/redis is an HTTP/REST based Redis client for typescript, 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.

Quick Start

Install

Node.js

npm install @upstash/redis

Deno

import { Redis } from "https://deno.land/x/upstash_redis/mod.ts";

Create database

Create a new redis database on upstash

Basic Usage:

import { Redis } from "@upstash/redis"

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

// string
await redis.set('key', 'value');
let data = await redis.get('key');
console.log(data)

await redis.set('key2', 'value2', {ex: 1});

// sorted set
await redis.zadd('scores', { score: 1, member: 'team1' })
data = await redis.zrange('scores', 0, 100 )
console.log(data)

// list
await redis.lpush('elements', 'magnesium')
data = await redis.lrange('elements', 0, 100 )
console.log(data)

// hash
await redis.hset('people', {name: 'joe'})
data = await redis.hget('people', 'name' )
console.log(data)

// sets
await redis.sadd('animals', 'cat')
data  = await redis.spop('animals', 1)
console.log(data)

Troubleshooting

We have a dedicated page for common problems. If you can't find a solution, please open an issue.

Docs

See the documentation for details.

Contributing

Install Deno

Database

Create a new redis database on upstash and copy the url and token

Running tests

UPSTASH_REDIS_REST_URL=".." UPSTASH_REDIS_REST_TOKEN=".." deno test -A

Telemetry

This library sends anonymous telemetry data to help us improve your experience. We collect the following:

• SDK version
• Platform (Deno, Cloudflare, Vercel)
• Runtime version (node@18.x)

You can opt out by setting the UPSTASH_DISABLE_TELEMETRY environment variable to any truthy value.

UPSTASH_DISABLE_TELEMETRY=1