OmniDB

Thin database orchestration library for Node.js — manage multiple connections with health monitoring and failover.

Features

• 🔌 Multi-Database Support — Bring your own clients (Prisma, Drizzle, Redis, MongoDB, etc.)
• 🏥 Health Monitoring — Configurable periodic health checks with timeouts
• 🔄 Automatic Failover — Route to backups when primary is unhealthy
• 📡 Event System — Subscribe to connection, health, and failover events
• 📦 Minimal Footprint — Zero runtime dependencies, <10KB bundle
• 🔷 TypeScript Ready — Full type definitions with generics

Before & After

// DIY: Managing multiple databases with health checks and failover

const primaryPool = new Pool({ connectionString: PRIMARY_URL });
const replicaPool = new Pool({ connectionString: REPLICA_URL });
const redis = createClient({ url: REDIS_URL });

let primaryHealthy = true;
let replicaHealthy = true;
let redisHealthy = true;

// Manual health check loop
setInterval(async () => {
  try {
    await primaryPool.query('SELECT 1');
    primaryHealthy = true;
  } catch {
    primaryHealthy = false;
    console.log('[HEALTH] Primary unhealthy');
  }
  
  try {
    await replicaPool.query('SELECT 1');
    replicaHealthy = true;
  } catch {
    replicaHealthy = false;
  }
  
  try {
    await redis.ping();
    redisHealthy = true;
  } catch {
    redisHealthy = false;
  }
}, 30000);

// Manual failover logic
function getDatabase() {
  if (primaryHealthy) return primaryPool;
  if (replicaHealthy) {
    console.log('[FAILOVER] Using replica');
    return replicaPool;
  }
  throw new Error('All databases unavailable');
}

// Manual graceful shutdown
process.on('SIGTERM', async () => {
  clearInterval(healthCheckInterval);
  await Promise.all([
    primaryPool.end(),
    replicaPool.end(),
    redis.quit(),
  ]);
  process.exit(0);
});

// Usage
app.get('/users', async (req, res) => {
  const db = getDatabase();
  const { rows } = await db.query('SELECT * FROM users');
  res.json(rows);
});

import { Orchestrator } from 'omni-db';

const db = new Orchestrator({
  connections: { primary: primaryPool, replica: replicaPool, cache: redis },
  failover: { primary: 'replica' },
  healthCheck: {
    interval: '30s',
    checks: {
      primary: async (c) => { await c.query('SELECT 1'); return true; },
      replica: async (c) => { await c.query('SELECT 1'); return true; },
      cache: async (c) => (await c.ping()) === 'PONG',
    },
  },
});

await db.connect();
db.shutdownOnSignal();

// Usage — identical, but with automatic failover
app.get('/users', async (req, res) => {
  const pg = db.get('primary');  // Auto-routes to replica if primary is down
  const { rows } = await pg.query('SELECT * FROM users');
  res.json(rows);
});

What you get: Health monitoring, automatic failover, event system, graceful shutdown, TypeScript types — all in <10KB with zero dependencies.

Installation

npm install omni-db

Quick Start

import { Orchestrator } from 'omni-db';

const db = new Orchestrator({
  connections: {
    primary: prismaClient,
    replica: replicaClient,
    cache: redisClient,
  },
  failover: { primary: 'replica' },
  healthCheck: {
    interval: '30s',
    timeout: '5s',
    checks: {
      primary: async (client) => {
        await client.$queryRaw`SELECT 1`;
        return true;
      },
      cache: async (client) => {
        const pong = await client.ping();
        return pong === 'PONG';
      },
    },
  },
});

// Connect and start health monitoring
await db.connect();

// Get clients (auto-routes to replica if primary is unhealthy)
const client = db.get('primary');

// Check health status
console.log(db.health());
// { primary: { status: 'healthy' }, replica: { status: 'healthy' }, cache: { status: 'healthy' } }

// Disconnect when done
await db.disconnect();

API Reference

new Orchestrator(config)

Creates a new orchestrator instance.

| Option | Type | Description | |--------|------|-------------| | connections | Record<string, any> | Named database client instances | | failover | Record<string, string> | Map primary → backup names | | healthCheck.interval | string | Check interval (e.g., '30s', '1m') | | healthCheck.timeout | string | Timeout per check | | healthCheck.retry.retries | number | Failed attempts before marking unhealthy | | healthCheck.retry.delay | string | Waiting time between retries | | healthCheck.checks | Record<string, Function> | Custom health check functions | | circuitBreaker.threshold | number | Failures before opening circuit (default: 5) | | circuitBreaker.resetTimeout | string | Time before half-open (default: '30s') | | circuitBreaker.use | object | External circuit breaker (opossum, cockatiel) |

Methods

| Method | Returns | Description | |--------|---------|-------------| | connect() | Promise<void> | Connect and start health monitoring | | disconnect() | Promise<void> | Disconnect and stop monitoring | | get(name) | T | Get client (with failover routing) | | execute(name, fn) | Promise<T> | Execute with automatic circuit breaker | | getStats() | Record<string, object> | Get health + circuit breaker stats | | list() | string[] | Get all connection names | | has(name) | boolean | Check if connection exists | | health() | Record<string, ConnectionHealth> | Get health status | | recordSuccess(name) | void | Record success for circuit breaker | | recordFailure(name) | void | Record failure for circuit breaker | | shutdownOnSignal(opts?) | () => void | Register graceful shutdown handlers | | isConnected | boolean | Connection state | | size | number | Number of connections |

Events

db.on('connected', ({ name }) => console.log(`${name} connected`));
db.on('disconnected', ({ name }) => console.log(`${name} disconnected`));
db.on('health:changed', ({ name, previous, current }) => {
  console.log(`${name}: ${previous} → ${current}`);
});
db.on('failover', ({ primary, backup }) => {
  console.log(`Switched from ${primary} to ${backup}`);
});
db.on('recovery', ({ primary, backup }) => {
  console.log(`Recovered ${primary}, was using ${backup}`);
});

TypeScript

Full type inference with generic connections:

import { Orchestrator } from 'omni-db';
import { PrismaClient } from '@prisma/client';
import { Redis } from 'ioredis';

const db = new Orchestrator({
  connections: {
    postgres: new PrismaClient(),
    redis: new Redis(),
  },
});

const prisma = db.get('postgres'); // Type: PrismaClient
const redis = db.get('redis');     // Type: Redis

Documentation

For detailed guides, see the docs/ folder:

| Guide | Description | |-------|-------------| | Getting Started | Installation and basic usage | | Configuration | All configuration options | | Architecture | How components work together | | Health Monitoring | Health checks and status | | Failover | Automatic failover routing | | Circuit Breaker | Prevent cascading failures | | Events | Event system reference | | Observability | Prometheus, logging, metrics | | Middleware | Express, Fastify, Koa, Hono, NestJS | | TypeScript | Type definitions and generics | | Examples | Real-world usage patterns | | Best Practices | Patterns, anti-patterns, and tips | | Error Reference | All errors with causes and solutions |

Philosophy

OmniDB is a thin orchestration layer. It doesn't abstract your databases — it orchestrates them.

You bring:

• Your database clients (Prisma, Drizzle, pg, Redis, MongoDB...)
• Your health check logic
• Your routing decisions

OmniDB provides:

• Connection registry with O(1) lookup
• Periodic health monitoring
• Automatic failover routing
• Event-driven notifications

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Sathvik C