Upstash Redis adapter for Keyv
npm install keyv-upstashUpstash Redis storage adapter for Keyv.




Upstash Redis storage adapter for Keyv.
- Built on top of Upstash Redis.
- Is fully compatible with serverless-redis-http so you can setup your own serverless Redis and use this adapter with it.
- TTL is handled directly by Upstash Redis.
- Supports namespaces for key management.
- Compatible with Keyv's official Redis adapter where possible.
- Provides access to the Upstash Redis client for advanced use cases.
- Written in TypeScript with type definitions included.
- Supports both CommonJS and ES Modules.
For the Upstash client the automaticDeserialization option is set to false by default and it is not recommended to change it because it can cause issues with storing and retrieving special types of values like Buffers, BigInt, etc.
In case you are passing a custom Upstash client instance, make sure to pass an instance that has been constructed with the automaticDeserialization option to false. (see the Usage section for an example)
- Usage
- Namespaces
- Typescript
- Performance Considerations
- Using Cacheable with Upstash Redis
- API
- Differences from @keyv/redis
- Contributing
- License
First, install keyv-upstash and keyv:
``bash`
npm install keyv-upstash keyv
Here is a standard use case where we implement Keyv with keyv-upstash:
`typescript
import Keyv from "keyv"
import { KeyvUpstash } from "keyv-upstash"
const keyv = new Keyv({
store: new KeyvUpstash({
url: "your-upstash-redis-url",
token: "your-upstash-redis-token",
}),
})
await keyv.set("foo", "bar")
const value = await keyv.get("foo")
console.log(value) // 'bar'
`
Alternatively, if you already have an Upstash Redis client instance:
`typescript
import Keyv from "keyv"
import { KeyvUpstash } from "keyv-upstash"
import { Redis } from "@upstash/redis"
const upstashRedis = new Redis({
url: "your-upstash-redis-url",
token: "your-upstash-redis-token",
/**
* IMPORTANT: Set automaticDeserialization to false to prevent issues
* with special value types
*/
automaticDeserialization: false,
})
const keyv = new Keyv({
store: new KeyvUpstash({ upstashRedis }),
})
await keyv.set("foo", "bar")
`
You can set a namespace for your keys to manage them more effectively:
`typescript
const keyv = new Keyv({
store: new KeyvUpstash({
url: "your-upstash-redis-url",
token: "your-upstash-redis-token",
namespace: "my-namespace",
}),
})
await keyv.set("foo", "bar")
`
This will prefix all keys with my-namespace::.
When initializing KeyvUpstash, you can specify the type of the values you are storing and you can also specify types when calling methods:
`typescript
import Keyv from "keyv"
import { KeyvUpstash } from "keyv-upstash"
interface User {
id: number
name: string
}
const keyv = new Keyv
store: new KeyvUpstash
url: "your-upstash-redis-url",
token: "your-upstash-redis-token",
}),
})
await keyv.set("user:1", { id: 1, name: "Alice" })
const user = await keyv.get("user:1")
console.log(user.name) // 'Alice'
// specify types when calling methods
const user = await keyv.get
console.log(user.name) // 'Alice'
`
- Clear Operations: The clear() method uses the SCAN command to iterate over keys and delete them in batches. This can be slow if you have a large dataset. It's recommended to use namespaces to limit the keys being cleared. If you don't set namespaces, you can enable noNamespaceAffectsAll to clear all keys using the FLUSHDB command which is faster.useUnlink
- Delete Operations: By default, is set to true, which uses the non-blocking UNLINK command instead of DEL. This helps improve performance during deletion.setMany
- Batch Operations: Methods like , getMany, and deleteMany are more efficient than their singular counterparts and are recommended when dealing with multiple keys.
To enhance performance further, you can use Cacheable for multi-layered caching:
`typescript
import { Cacheable } from "cacheable"
import { KeyvUpstash } from "keyv-upstash"
const secondary = new KeyvUpstash({
url: "your-upstash-redis-url",
token: "your-upstash-redis-token",
})
const cache = new Cacheable({ secondary })
`
Creates a new KeyvUpstash instance.
#### Options:
- upstashRedis: An existing Upstash Redis client instance.
- url: The Upstash Redis REST API URL.
- token: The Upstash Redis REST API token.
- namespace: An optional namespace to prefix all keys with.
- keyPrefixSeparator: A custom separator between the namespace and the key (default is ::).UNLINK
- defaultTtl: The default TTL for keys in milliseconds.
- useUnlink: Whether to use the command instead of DEL for deleting keys (default is true).1000
- clearBatchSize: The number of keys to delete in a single batch when clearing the cache (default is ).false
- noNamespaceAffectsAll: Whether to allow clearing all keys when no namespace is set (default is ).
- client: The Upstash Redis client instance.
- namespace: The namespace used for keys.
- keyPrefixSeparator: Separator used between namespace and key.
- defaultTtl: The default TTL for keys.
- useUnlink: Indicates if UNLINK is used for deletion.
- clearBatchSize: Batch size for clear operations.
- noNamespaceAffectsAll: Determines behavior when no namespace is set.
- set(key, value, ttl?): Set a value in the cache.
- get(key): Get a value from the cache.
- delete(key): Delete a key from the cache.
- clear(): Clear all keys in the namespace. If the namespace is not set it will clear all keys that are not prefixed with a namespace unless noNamespaceAffectsAll is set to true.noNamespaceAffectsAll
- setMany(entries): Set multiple values in the cache.
- getMany(keys): Get multiple values from the cache.
- deleteMany(keys): Delete multiple keys from the cache.
- has(key): Check if a key exists in the cache.
- hasMany(keys): Check if multiple keys exist in the cache.
- iterator(namespace?): Create a new iterator for the keys. If the namespace is not set it will iterate over all keys that are not prefixed with a namespace unless is set to true.
- Backend: Uses Upstash Redis, an HTTP-based, serverless Redis service.
- Connection: Requires Upstash REST API URL and token instead of a traditional Redis connection URL.
- TLS and Sockets: Connection options related to sockets and TLS are not applicable.
- Compatibility: Aims to be compatible with @keyv/redis` where possible, but some differences exist due to the nature of Upstash Redis.