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

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#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). 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), 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). 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#L18-L30) instantiates the appropriate storage class at runtime:

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):

export NEXT_PUBLIC_STORAGE_TYPE=upstash
npm start

Using Self-Hosted Redis:

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

Using KVROCKS:

export NEXT_PUBLIC_STORAGE_TYPE=kvrocks

Unified Database API

Regardless of the selected backend, the DbManager exposes identical methods for data operations. Import the singleton db instance to interact with storage:

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.
• 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}