# How to Configure the Storage System in LunaTV: Kvrocks, Redis, and Upstash Setup

> Configure LunaTV's storage with Kvrocks, Redis, or Upstash. Easily switch backends using the STORAGE environment variable without code changes for flexible data management.

- Repository: [MoonTechLab/LunaTV](https://github.com/MoonTechLab/LunaTV)
- Tags: how-to-guide
- Published: 2026-09-08

---

**LunaTV selects its storage backend at runtime via the `STORAGE` environment variable, instantiating Kvrocks, Upstash Redis, or local Redis drivers without requiring code changes.**

LunaTV implements a pluggable storage architecture that abstracts persistence behind a unified interface. The system dynamically loads the appropriate driver based on environment configuration, allowing seamless switching between self-hosted Kvrocks, managed Upstash Redis, or local Redis instances. This design centers around the factory pattern in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts) and strict configuration validation in [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts).

## Supported Storage Backends

LunaTV provides three distinct storage implementations, each optimized for specific infrastructure requirements.

### Kvrocks (Persistent KV Store)

**Kvrocks** provides a Redis-compatible persistent storage layer ideal for self-hosted deployments requiring data durability. The implementation in [`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts) extends `BaseRedisStorage` to communicate with Kvrocks endpoints using standard Redis protocol semantics while persisting data to disk.

### Upstash (Serverless Redis)

**Upstash** offers a fully managed, serverless Redis API accessible via HTTP REST. The driver in [`src/lib/upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/upstash.db.ts) wraps Upstash's REST interface, making it optimal for serverless deployments where maintaining persistent TCP connections is problematic or impossible.

### Redis (Local Development)

**Redis** via the standard client in [`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts) serves local development and traditional containerized deployments. This implementation uses the standard Node.js Redis client with full command compatibility for testing environments that require native Redis protocol support.

## Configuration Environment Variables

The [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts) module parses environment variables to determine storage selection and connection parameters. Configure these variables in your `.env` file or deployment environment:

- **`STORAGE`**: Defines the backend type. Accepts `"kvrocks"`, `"upstash"`, or `"redis"`.
- **`KVROCKS_URL`**: Connection URI for Kvrocks instances (e.g., `redis://user:pass@host:6379`).
- **`UPSTASH_REDIS_REST_URL`**: HTTPS endpoint for Upstash Redis REST API.
- **`UPSTASH_REDIS_REST_TOKEN`**: Authentication token for Upstash REST requests.
- **`REDIS_URL`**: Standard Redis connection URI for local or custom deployments.
- **`REDIS_PASSWORD`**: Optional authentication credential when using the Redis backend.

## How the Storage Factory Works

The `createStorage()` function in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts) acts as the central factory that instantiates the appropriate driver. This function reads configuration via `getConfig()` and returns a storage implementation matching the `STORAGE` environment variable.

```typescript
// src/lib/db.ts
import { KvrocksStorage } from './kvrocks.db';
import { UpstashStorage } from './upstash.db';
import { RedisStorage } from './redis.db';
import { getConfig } from './config';

export function createStorage() {
  const cfg = getConfig();
  switch (cfg.storage) {
    case 'kvrocks':  return new KvrocksStorage();
    case 'upstash': return new UpstashStorage();
    case 'redis':   return new RedisStorage();
    default:        throw new Error('Unsupported storage type');
  }
}

```

The factory throws an explicit error if `STORAGE` is undefined or contains an unsupported value, preventing the application from starting with an invalid configuration.

## Step-by-Step Configuration Examples

### Configuring Kvrocks

To use Kvrocks as your persistence layer, set the following environment variables:

```bash

# .env

STORAGE=kvrocks
KVROCKS_URL=redis://user:password@kvrocks.example.com:6379

```

The `KvrocksStorage` class handles connection pooling and protocol compatibility automatically. Once configured, use the storage interface:

```typescript
import { createStorage } from '@/lib/db';

const storage = createStorage();
await storage.set('user:1234:token', 'abcdef');
const token = await storage.get('user:1234:token');

```

### Configuring Upstash

For serverless deployments using Upstash Redis, configure these variables:

```bash

# .env

STORAGE=upstash
UPSTASH_REDIS_REST_URL=https://example.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxxxxxxxxxxxx

```

The `UpstashStorage` implementation translates standard Redis commands into HTTP requests to Upstash's REST API, handling authentication and retry logic internally.

### Configuring Local Redis

For development environments, point LunaTV to a local Redis instance:

```bash

# .env

STORAGE=redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=optional_dev_password

```

This configuration instantiates the `RedisStorage` class from [`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts), which uses the standard Node.js Redis client for maximum compatibility with local development tools.

## Validation and Error Handling

The [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts) module validates required environment variables during application startup. If you select `STORAGE=kvrocks` but omit `KVROCKS_URL`, the configuration loader throws an initialization error before the storage factory attempts connection. This early validation prevents runtime failures in production environments.

Similarly, selecting `upstash` without both `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` results in a descriptive error indicating exactly which variables are missing.

## Summary

- **LunaTV** abstracts storage behind a unified interface implemented in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts).
- Three backends are supported: **Kvrocks** ([`kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/kvrocks.db.ts)), **Upstash** ([`upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/upstash.db.ts)), and **Redis** ([`redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/redis.db.ts)).
- The `STORAGE` environment variable controls backend selection without code changes.
- Configuration validation occurs in [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts) before application startup.
- Each backend requires specific environment variables: `KVROCKS_URL`, `UPSTASH_REDIS_REST_URL`/`TOKEN`, or `REDIS_URL`.

## Frequently Asked Questions

### What storage backends does LunaTV support?

LunaTV supports **Kvrocks** for persistent self-hosted storage, **Upstash** for serverless Redis via REST API, and standard **Redis** for local development. Each implementation resides in [`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts), [`src/lib/upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/upstash.db.ts), and [`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts) respectively.

### How do I switch between storage backends in LunaTV?

Change the `STORAGE` environment variable to `"kvrocks"`, `"upstash"`, or `"redis"` and provide the corresponding connection URLs. The `createStorage()` factory in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts) automatically instantiates the correct driver on the next application restart. No code modifications are required.

### Is Kvrocks compatible with standard Redis clients?

Yes. The **Kvrocks** implementation in [`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts) extends `BaseRedisStorage` and uses Redis protocol compatibility. You can use standard Redis connection URLs and commands, though Kvrocks persists data to disk rather than memory.

### Can I use authentication with the Redis backend?

Yes. Set `REDIS_PASSWORD` in your environment variables when using the Redis backend. The `RedisStorage` class passes this credential to the underlying Redis client. For Kvrocks, embed credentials directly in the `KVROCKS_URL` using standard Redis URI syntax (`redis://user:pass@host:port`).