Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisLevel
✓ import { RedisLevel } from 'upstash-redis-level';
✗ const { RedisLevel } = require('upstash-redis-level');
Prefer ESM imports for modern Node.js and client-side environments. CommonJS `require` is also supported but less idiomatic for new projects.
Redis
✓ import { Redis } from '@upstash/redis';
✗ const { Redis } = require('@upstash/redis');
The underlying Upstash Redis client is a peer dependency and must be imported and instantiated separately. It powers the connection to the Upstash service.
RedisLevelOptions
✓ import type { RedisLevelOptions } from 'upstash-redis-level';
Type import for configuration options when initializing RedisLevel. Essential for TypeScript projects.
This quickstart demonstrates how to initialize `upstash-redis-level` with an `@upstash/redis` client and perform basic `put`, `get`, and iteration operations. It highlights using environment variables for Redis credentials and the `namespace` option.
import { RedisLevel } from 'upstash-redis-level';
import { Redis } from '@upstash/redis';
const UPSTASH_REDIS_REST_URL = process.env.KV_REST_API_URL ?? 'http://localhost:8079';
const UPSTASH_REDIS_REST_TOKEN = process.env.KV_REST_API_TOKEN ?? 'example_token';
async function runRedisLevelExample() {
if (!UPSTASH_REDIS_REST_URL || !UPSTASH_REDIS_REST_TOKEN) {
console.error('Missing UPSTASH_REDIS_REST_URL or UPSTASH_REDIS_REST_TOKEN environment variables.');
return;
}
// 1. Initialize the Upstash Redis client
const redisClient = new Redis({
url: UPSTASH_REDIS_REST_URL,
token: UPSTASH_REDIS_REST_TOKEN,
});
// 2. Initialize the RedisLevel database
const db = new RedisLevel({
redis: redisClient,
namespace: 'my-app-data',
debug: true,
});
try {
// 3. Perform basic operations
await db.put('user:1', JSON.stringify({ name: 'Alice', age: 30 }));
console.log('Put user:1');
const user1 = await db.get('user:1');
console.log('Got user:1:', user1); // Should output '{"name":"Alice","age":30}'
await db.put('user:2', JSON.stringify({ name: 'Bob', age: 25 }));
// 4. Iterate over entries
console.log('\nIterating through users:');
for await (const [key, value] of db.iterator({ gte: 'user:' })) {
console.log(`${key}: ${value}`);
}
// 5. Delete an entry
await db.del('user:1');
console.log('\nDeleted user:1');
const user1AfterDelete = await db.get('user:1');
console.log('Got user:1 after delete:', user1AfterDelete); // Should be undefined
} catch (error) {
console.error('Error during RedisLevel operations:', error);
} finally {
// In real serverless functions, connections are often managed by the runtime.
// Explicitly quitting might not be necessary or even desirable in some environments.
// However, for local scripts, it's good practice to close connections.
// (Note: @upstash/redis often manages its HTTP connections implicitly)
// await redisClient.quit(); // @upstash/redis doesn't have a 'quit' method in this context.
}
}
runRedisLevelExample();
Debug
Known issues
gotchaTraditional TCP-based Redis clients can face 'ERR max concurrent connections exceeded' errors in serverless environments due to connection limits and cold starts. `upstash-redis-level`, by using `@upstash/redis`, leverages an HTTP/REST API to mitigate these issues by being connectionless.fixEnsure you are correctly initializing `@upstash/redis` with `url` and `token` environment variables. The HTTP-based nature of `@upstash/redis` is designed to intrinsically handle transient connections in serverless functions without explicit connection management like `quit()`.
affects: All versions (when using traditional Redis clients, not @upstash/redis)
gotchaWhen using `@upstash/redis` (the underlying client), large numbers (exceeding `Number.MAX_SAFE_INTEGER`) may be returned as strings instead of numbers. This is a JavaScript limitation and a design choice in `@upstash/redis` to prevent silent data corruption.fixHandle large numbers as strings in your application logic. If strict numeric deserialization is required for numbers that fit within JavaScript's safe integer range, you may need to explicitly parse them or configure `responseEncoding: false` on the `Redis` client if applicable, though this is generally not recommended unless you understand the implications.
affects: All versions
gotchaIn Node.js environments prior to version 18, the `fetch` API is not natively available. Since `@upstash/redis` relies on `fetch`, this can lead to `ReferenceError: fetch is not defined`.fixFor Node.js < v18, install a polyfill like `isomorphic-fetch` (`npm install isomorphic-fetch`) and import it at the top of your entry file: `import 'isomorphic-fetch';`
affects: <=1.x.x
deprecatedUpstash Redis, the backing service, deprecated its strong consistency mode (March 2022) and GraphQL API (October 2022). While not directly affecting `upstash-redis-level`'s API, applications relying on these underlying Redis features might experience changes or require refactoring.fixReview Upstash documentation for updated recommendations. For strong consistency, Upstash improved replication for Read-Your-Writes consistency. For GraphQL, use the REST API directly.
affects: All versions
Errors
Common errors & fixes
ReferenceError: fetch is not defined
Running on Node.js versions older than 18 without a `fetch` polyfill, as `@upstash/redis` uses the Web Fetch API.
fixInstall `isomorphic-fetch` (`npm i isomorphic-fetch`) and add `import 'isomorphic-fetch';` at the top of your application's entry point.
ERR max concurrent connections exceeded
While less likely with `@upstash/redis` due to its HTTP nature, if an underlying non-Upstash Redis client or an improperly configured `@upstash/redis` instance is used in a high-concurrency serverless environment, connection limits can be hit.
fixEnsure you are using the HTTP-based `@upstash/redis` client correctly, which handles connections efficiently for serverless. Verify that `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` are correctly set.
NOAUTH Authentication required.
The `@upstash/redis` client or the `RedisLevel` instance is not correctly authenticated with the Upstash Redis service.
fixDouble-check that `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` environment variables are correctly set and correspond to your Upstash Redis database. These are crucial for authentication.
Hashed response when using redis.get() or similar.
By default, `@upstash/redis` can base64 encode responses from the server to prevent deserialization issues with certain data types.
fixIf you are certain your data is always valid JSON and you wish to disable this behavior, you can set `responseEncoding: false` in the `Redis` client options: `new Redis({ ..., responseEncoding: false })`. However, this is usually not necessary with recent versions. Audit
Dependencies
@upstash/redisrequiredCore Redis client for serverless and edge environments.
abstract-levelrequiredProvides the abstract API interface for the LevelDB-like database.