# Database Options Supported by LunaTV: Redis, Upstash, KVROCKS, and LocalStorage

> Discover LunaTV's supported database options including Redis, Upstash, KVROCKS, and LocalStorage. Easily configure your backend with NEXT_PUBLIC_STORAGE_TYPE.

- Repository: [MoonTechLab/LunaTV](https://github.com/MoonTechLab/LunaTV)
- Tags: getting-started
- Published: 2026-09-09

---

**LunaTV supports four pluggable storage backends—localStorage, Redis, Upstash, and KVROCKS—selected via the `NEXT_PUBLIC_STORAGE_TYPE` environment variable.**

LunaTV, developed by MoonTechLab, implements a storage abstraction layer that decouples the application logic from specific database implementations. The database options supported by LunaTV range from browser-based persistence for static deployments to enterprise-grade Redis-compatible servers for production environments. All backends are managed through a unified factory pattern defined in the core storage module.

## Supported Database Backends in LunaTV

The storage layer resolves the active backend by reading the `NEXT_PUBLIC_STORAGE_TYPE` environment variable in [[`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts)](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts#L9-L16). The codebase provides four distinct implementations, each optimized for different deployment scenarios.

### LocalStorage (Browser Default)

When `NEXT_PUBLIC_STORAGE_TYPE` is set to `localstorage` or left undefined, LunaTV defaults to the browser's native `localStorage` API. This implementation requires no external dependencies, configuration files, or server infrastructure, making it suitable for development environments and static site deployments.

### Redis (Self-Hosted)

For production workloads requiring in-memory performance, LunaTV includes a Redis adapter implemented in [[`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts)](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts). This backend connects to self-hosted Redis instances using the `REDIS_URL` environment variable, providing full control over persistence, replication, and clustering.

### Upstash (Serverless/Managed)

The Upstash backend, defined in [[`src/lib/upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/upstash.db.ts)](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/upstash.db.ts), targets serverless architectures and edge deployments. It integrates with Upstash's managed Redis service, offering Redis-compatible semantics without the operational overhead of maintaining Redis servers.

### KVROCKS (Redis-Compatible)

For deployments requiring disk-based persistence with Redis protocol compatibility, LunaTV provides a KVROCKS adapter in [[`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts)](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts). KVROCKS uses RocksDB as the storage engine while maintaining wire-protocol compatibility with Redis, enabling large datasets that exceed available memory.

## How the Storage Factory Works

The central factory function in [[`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts)](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts#L18-L30) instantiates the appropriate storage class at runtime:

```typescript
function createStorage(): IStorage {
  switch (STORAGE_TYPE) {
    case 'redis':    return new RedisStorage();
    case 'upstash':  return new UpstashRedisStorage();
    case 'kvrocks':  return new KvrocksStorage();
    case 'localstorage':
    default:         return null as unknown as IStorage; // falls back to localStorage
  }
}

```

This factory pattern ensures the **DbManager** API remains consistent across all storage implementations, allowing you to swap backends without modifying application logic.

## Configuring Database Backends

Select your storage backend by setting the `NEXT_PUBLIC_STORAGE_TYPE` environment variable before starting the application.

**Using Upstash (Managed Redis):**

```bash
export NEXT_PUBLIC_STORAGE_TYPE=upstash
npm start

```

**Using Self-Hosted Redis:**

```bash
export NEXT_PUBLIC_STORAGE_TYPE=redis
export REDIS_URL=redis://localhost:6379
npm run dev

```

**Using KVROCKS:**

```bash
export NEXT_PUBLIC_STORAGE_TYPE=kvrocks

```

## Unified Database API

Regardless of the selected backend, the [`DbManager`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts) exposes identical methods for data operations. Import the singleton `db` instance to interact with storage:

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

// Store a play record with position data
await db.savePlayRecord('alice', 'movie', '12345', {
  position: 120,
  duration: 3600,
});

// Retrieve a user's favorite item
const favorite = await db.getFavorite('alice', 'tv', '9876');
console.log(favorite);

```

The same code executes against localStorage, Redis, Upstash, or KVROCKS without modification.

## Summary

- LunaTV provides **four database options**: localStorage, Redis, Upstash, and KVROCKS.
- Backend selection is controlled by the `NEXT_PUBLIC_STORAGE_TYPE` environment variable resolved in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts).
- The **factory function** `createStorage()` instantiates `RedisStorage`, `UpstashRedisStorage`, or `KvrocksStorage` based on the configuration.
- All backends implement the **IStorage** interface, exposing uniform methods like `savePlayRecord()` and `getFavorite()`.
- Self-hosted Redis requires the additional `REDIS_URL` environment variable for connection details.

## Frequently Asked Questions

### What is the default database option if I don't configure any environment variables?

If `NEXT_PUBLIC_STORAGE_TYPE` is undefined or explicitly set to `localstorage`, LunaTV falls back to the browser's native `localStorage` API. This default requires no server-side infrastructure and stores all data locally in the user's browser according to the implementation in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts).

### Can I switch from localStorage to Redis without changing my application code?

Yes. The `DbManager` API abstracts the underlying storage implementation, ensuring methods like `savePlayRecord()` and `getFavorite()` behave identically across all backends. You only need to change the `NEXT_PUBLIC_STORAGE_TYPE` environment variable and provide the appropriate connection URL for Redis-based backends.

### Does LunaTV support Redis Sentinel or Cluster configurations?

The current implementations in [`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts) handle standard single-node connections via the `REDIS_URL` environment variable. To support Redis Sentinel or Cluster topologies, you would need to extend the `RedisStorage` class to initialize the client with cluster-specific configuration options.

### Is KVROCKS different from standard Redis?

KVROCKS is a Redis-compatible key-value store that uses RocksDB for disk-based persistence instead of memory. While it speaks the Redis protocol and works with LunaTV's `KvrocksStorage` class as a drop-in replacement, it stores data on disk rather than in memory, making it suitable for larger datasets that exceed RAM constraints.