Skip to main content

SDK for Javascript

upstash-redis is a Javascript SDK and HTTP/REST based Redis client built on top of Upstash REST API. It is connectionless (HTTP based) and designed to work seamlessly in serverless environments such as AWS Lambda, Cloudflare Workers and all other environments where HTTP is preferred over TCP.

When should upstash-redis be preferred over Redis clients?

You can use all Redis clients with Upstash databases. But at some cases, we recommend to use upstash-redis instead of native clients.

Use upstash-redis in serverless functions if you expect high number of concurrent connections

Serverless functions scale up fast. This can cause some issues if you need persistent connections. REST based upstash-redis fits better in such cases as it does not require a TCP connection with its stateless design.

Use upstash-redis in edge functions

Cloudflare Workers and Fastly Compute run your function in a runtime which does not allow TCP connections. So you can not use Redis client in those. upstash-redis works in those environments without any problem.

Use Redis clients in traditional server side applications

If your application is already stateful then Redis clients would be a better choice. Reusing TCP based connection should perform better and upstash-redis supports fewer commands than native Redis clients.

How to Install

npm install @upstash/redis

Authentication

You need UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN which can be copied from the database page in the Upstash Console.

There are two alternatives to authenticate:

1- Set environment variables as below:

UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

2- Call auth() before running any command in your code.

 auth('UPSTASH_REDIS_REST_URL', 'UPSTASH_REDIS_REST_TOKEN');

Usage

upstash-redis commands returns Promise. The promise resolves to a JSON object with following structure:

{
"data" : ">>> result of the Redis command",
"error" : ">>> error expression if the command fails",
"metadata" : ">>> the information if the result is fetched from edge cache "
}

Here an example with async/wait:

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

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

Here an example with a callback:

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

auth('UPSTASH_REDIS_REST_URL', 'UPSTASH_REDIS_REST_TOKEN');

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

Enable Edge Caching

Edge caching caches your REST API responses on globally distributed edge locations (CDN). You can enable edge caching by setting UPSTASH_REDIS_EDGE_URL as environment variable or a parameter to your auth() method as below:

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

auth({
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 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 get('key', { edge: false });
if (get1.error) throw get1.error;
} catch (error) {
console.error(error);
}
})();

When you enable edge, all read commands will be fetched from edge cache. You can configure a command to read from origin as below:

   const get1 = await get('key', { edge: false });

You can also change the default behaviour by setting:

 
auth({
url: 'UPSTASH_REDIS_REST_URL',
token: 'UPSTASH_REDIS_REST_TOKEN',
edgeUrl: 'UPSTASH_REDIS_EDGE_URL',
readFromEdge: false
});

With the above configuration, all read commands will be read from origin. You can still read from edge by explicitly configuring the command:

    const get1 = await get('key', { edge: true });

API Examples

upstash-redis supports all commands supported by Upstash Redis API. See the list of APIs supported.

Also see the tests in our repo to see example usages for the commands.