@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
• 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

npm install @upstash/redis

Usage with Promise

import { auth, set } from '@upstash/redis';

auth('UPSTASH_REDIS_REST_URL', 'UPSTASH_REDIS_REST_TOKEN');

set('key', 'value').then(({ data }) => {
  console.log(data);
  // -> "OK"
});

Usage with async/await

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

(async () => {
  try {
    const { data, error } = await set('key', 'value');
    if (error) throw error;
    console.log(data);
    // -> "OK"
  } catch (error) {
    console.error(error);
  }
})();

If you define UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables, you can run the Redis commands directly.

Edge Support

Once you set edgeUrl, all read commands are fetched using edge url. The REST URL is used for write/update commands.

import upstash from '@upstash/redis';

const redis = upstash({
  url: 'UPSTASH_REDIS_REST_URL',
  token: 'UPSTASH_REDIS_REST_TOKEN',
  edgeUrl: 'UPSTASH_REDIS_EDGE_URL',
});

(async () => {
  try {
    // the below reads using edge url
    const { data, error, metadata } = await redis.get('key');
    if (error) throw error;
    console.log(data);
    // -> null | string
    console.log(metadata);
    // -> { edge: boolean, cache: null | 'miss' | 'hit' }

    // the below reads using REST url (non-edge)
    const get1 = await redis.get('key', { edge: false });
    if (get1.error) throw get1.error;
  } catch (error) {
    console.error(error);
  }
})();