drizzle-multitenant 1.0.9 → 1.1.0

package/README.md

@@ -1,20 +1,36 @@
-# drizzle-multitenant
+<p align="center">
+  <img src="./assets/banner.svg" alt="drizzle-multitenant" width="500" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/drizzle-multitenant.svg)](https://www.npmjs.com/package/drizzle-multitenant)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://mateusflorez.github.io/drizzle-multitenant/)
+<p align="center">
+  <strong>Multi-tenancy toolkit for Drizzle ORM</strong>
+</p>
 
-Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and parallel migrations.
+<p align="center">
+  Schema isolation, tenant context propagation, and parallel migrations for PostgreSQL
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/drizzle-multitenant"><img src="https://img.shields.io/npm/v/drizzle-multitenant.svg?style=flat-square&color=4A9A98" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/drizzle-multitenant"><img src="https://img.shields.io/npm/dm/drizzle-multitenant.svg?style=flat-square&color=3D5A80" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-6AADAB.svg?style=flat-square" alt="License"></a>
+  <a href="https://mateusflorez.github.io/drizzle-multitenant/"><img src="https://img.shields.io/badge/docs-online-2B3E5C.svg?style=flat-square" alt="Documentation"></a>
+</p>
+
+<br />
 
 ## Features
 
-- **Schema Isolation** - PostgreSQL schema-per-tenant with LRU pool management
-- **Context Propagation** - AsyncLocalStorage-based tenant context
-- **Parallel Migrations** - Concurrent migrations with progress tracking
-- **Cross-Schema Queries** - Type-safe joins between tenant and shared tables
-- **Connection Retry** - Automatic retry with exponential backoff
-- **Framework Support** - Express, Fastify, NestJS middleware/plugins
-- **CLI Tools** - Generate, migrate, status, tenant management
+| Feature | Description |
+|---------|-------------|
+| **Schema Isolation** | PostgreSQL schema-per-tenant with automatic LRU pool management |
+| **Context Propagation** | AsyncLocalStorage-based tenant context across your entire stack |
+| **Parallel Migrations** | Apply migrations to all tenants concurrently with progress tracking |
+| **Cross-Schema Queries** | Type-safe joins between tenant and shared tables |
+| **Connection Retry** | Automatic retry with exponential backoff for transient failures |
+| **Framework Support** | First-class Express, Fastify, and NestJS integrations |
+
+<br />
 
 ## Installation
 
@@ -22,8 +38,12 @@ Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and
 npm install drizzle-multitenant drizzle-orm pg
 ```
 
+<br />
+
 ## Quick Start
 
+### 1. Define your configuration
+
 ```typescript
 // tenant.config.ts
 import { defineConfig } from 'drizzle-multitenant';
@@ -39,6 +59,8 @@ export default defineConfig({
 });
 ```
 
+### 2. Create the tenant manager
+
 ```typescript
 // app.ts
 import { createTenantManager } from 'drizzle-multitenant';
@@ -46,51 +68,118 @@ import config from './tenant.config';
 
 const tenants = createTenantManager(config);
 
-// Get typed DB for a tenant
-const db = tenants.getDb('tenant-123');
+// Type-safe database for each tenant
+const db = tenants.getDb('acme');
 const users = await db.select().from(schema.users);
-
-// With retry and validation
-const db = await tenants.getDbAsync('tenant-123');
 ```
 
-## CLI
+<br />
+
+## CLI Commands
 
 ```bash
-npx drizzle-multitenant init                    # Setup wizard
-npx drizzle-multitenant generate --name=users   # Create migration
-npx drizzle-multitenant migrate --all           # Apply to all tenants
-npx drizzle-multitenant status                  # Check status
+npx drizzle-multitenant init                     # Interactive setup wizard
+npx drizzle-multitenant generate --name=users    # Generate migration
+npx drizzle-multitenant migrate --all            # Apply to all tenants
+npx drizzle-multitenant status                   # Check migration status
+npx drizzle-multitenant tenant:create --id=acme  # Create new tenant
 ```
 
+<br />
+
 ## Framework Integrations
 
+<details>
+<summary><strong>Express</strong></summary>
+
 ```typescript
-// Express
 import { createExpressMiddleware } from 'drizzle-multitenant/express';
-app.use(createExpressMiddleware({ manager: tenants, extractTenantId: (req) => req.headers['x-tenant-id'] }));
 
-// Fastify
+app.use(createExpressMiddleware({
+  manager: tenants,
+  extractTenantId: (req) => req.headers['x-tenant-id'] as string,
+}));
+
+app.get('/users', async (req, res) => {
+  const db = req.tenantContext.db;
+  const users = await db.select().from(schema.users);
+  res.json(users);
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Fastify</strong></summary>
+
+```typescript
 import { fastifyTenantPlugin } from 'drizzle-multitenant/fastify';
-fastify.register(fastifyTenantPlugin, { manager: tenants, extractTenantId: (req) => req.headers['x-tenant-id'] });
 
-// NestJS
+fastify.register(fastifyTenantPlugin, {
+  manager: tenants,
+  extractTenantId: (req) => req.headers['x-tenant-id'] as string,
+});
+
+fastify.get('/users', async (req, reply) => {
+  const db = req.tenantContext.db;
+  const users = await db.select().from(schema.users);
+  return users;
+});
+```
+
+</details>
+
+<details>
+<summary><strong>NestJS</strong></summary>
+
+```typescript
 import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
-@Module({ imports: [TenantModule.forRoot({ config, extractTenantId: (req) => req.headers['x-tenant-id'] })] })
+
+@Module({
+  imports: [
+    TenantModule.forRoot({
+      config,
+      extractTenantId: (req) => req.headers['x-tenant-id'],
+    }),
+  ],
+})
+export class AppModule {}
+
+@Injectable({ scope: Scope.REQUEST })
+export class UserService {
+  constructor(@InjectTenantDb() private db: TenantDb) {}
+
+  findAll() {
+    return this.db.select().from(users);
+  }
+}
 ```
 
-## Documentation
+</details>
 
-**[Read the full documentation →](https://mateusflorez.github.io/drizzle-multitenant/)**
+<br />
 
-- [Getting Started](https://mateusflorez.github.io/drizzle-multitenant/guide/getting-started)
-- [Configuration](https://mateusflorez.github.io/drizzle-multitenant/guide/configuration)
-- [Framework Integrations](https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/express)
-- [CLI Commands](https://mateusflorez.github.io/drizzle-multitenant/guide/cli)
-- [Cross-Schema Queries](https://mateusflorez.github.io/drizzle-multitenant/guide/cross-schema)
-- [Advanced Features](https://mateusflorez.github.io/drizzle-multitenant/guide/advanced)
-- [API Reference](https://mateusflorez.github.io/drizzle-multitenant/api/reference)
-- [Examples](https://mateusflorez.github.io/drizzle-multitenant/examples/)
+## Documentation
+
+<table>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/getting-started">Getting Started</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/configuration">Configuration</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/cli">CLI Commands</a></td>
+  </tr>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/express">Express</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/fastify">Fastify</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/nestjs">NestJS</a></td>
+  </tr>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/cross-schema">Cross-Schema Queries</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/advanced">Advanced Features</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/api/reference">API Reference</a></td>
+  </tr>
+</table>
+
+<br />
 
 ## Requirements
 
@@ -98,6 +187,8 @@ import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
 - PostgreSQL 12+
 - Drizzle ORM 0.29+
 
+<br />
+
 ## License
 
 MIT

package/dist/{context-DoHx79MS.d.ts → context-Vki959ri.d.ts}

@@ -1,4 +1,4 @@
-import { T as TenantManager, a as TenantDb, S as SharedDb } from './types-B5eSRLFW.js';
+import { T as TenantManager, a as TenantDb, S as SharedDb } from './types-BhK96FPC.js';
 
 /**
  * Base tenant context data

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as Config, T as TenantManager, R as RetryConfig } from './types-B5eSRLFW.js';
-export { b as ConnectionConfig, h as DEFAULT_CONFIG, D as DebugConfig, e as DebugContext, H as Hooks, I as IsolationConfig, c as IsolationStrategy, M as MetricsConfig, P as PoolEntry, d as SchemasConfig, S as SharedDb, a as TenantDb, g as TenantWarmupResult, W as WarmupOptions, f as WarmupResult } from './types-B5eSRLFW.js';
-export { B as BaseTenantContext, a as TenantContext, T as TenantContextData, c as createTenantContext } from './context-DoHx79MS.js';
+import { C as Config, T as TenantManager, R as RetryConfig } from './types-BhK96FPC.js';
+export { b as ConnectionConfig, n as ConnectionMetrics, o as DEFAULT_CONFIG, D as DebugConfig, e as DebugContext, h as HealthCheckOptions, i as HealthCheckResult, H as Hooks, I as IsolationConfig, c as IsolationStrategy, M as MetricsConfig, l as MetricsResult, P as PoolEntry, j as PoolHealth, k as PoolHealthStatus, d as SchemasConfig, S as SharedDb, a as TenantDb, m as TenantPoolMetrics, g as TenantWarmupResult, W as WarmupOptions, f as WarmupResult } from './types-BhK96FPC.js';
+export { B as BaseTenantContext, a as TenantContext, T as TenantContextData, c as createTenantContext } from './context-Vki959ri.js';
 export { AppliedMigration, CreateTenantOptions, DropTenantOptions, MigrateOptions, MigrationErrorHandler, MigrationFile, MigrationHooks, MigrationProgressCallback, MigrationResults, Migrator, MigratorConfig, TenantMigrationResult, TenantMigrationStatus, createMigrator } from './migrator/index.js';
 export { ColumnSelection, CrossSchemaContext, CrossSchemaQueryBuilder, CrossSchemaRawOptions, InferSelectResult, InferSelectedColumns, JoinCondition, JoinDefinition, JoinType, LookupResult, SchemaSource, SharedLookupConfig, TableReference, WithSharedConfig, WithSharedOptions, WithSharedQueryBuilder, buildCrossSchemaSelect, createCrossSchemaQuery, crossSchemaRaw, withShared, withSharedLookup } from './cross-schema/index.js';
 import 'pg';

package/dist/index.js

@@ -624,6 +624,227 @@ var PoolManager = class {
       details: results
     };
   }
+  /**
+   * Get current metrics for all pools
+   *
+   * Collects metrics on demand with zero overhead when not called.
+   * Returns raw data that can be formatted for any monitoring system.
+   *
+   * @example
+   * ```typescript
+   * const metrics = manager.getMetrics();
+   * console.log(metrics.pools.total); // 15
+   *
+   * // Format for Prometheus
+   * for (const pool of metrics.pools.tenants) {
+   *   gauge.labels(pool.tenantId).set(pool.connections.idle);
+   * }
+   * ```
+   */
+  getMetrics() {
+    this.ensureNotDisposed();
+    const maxPools = this.config.isolation.maxPools ?? DEFAULT_CONFIG.maxPools;
+    const tenantMetrics = [];
+    for (const [schemaName, entry] of this.pools.entries()) {
+      const tenantId = this.tenantIdBySchema.get(schemaName) ?? schemaName;
+      const pool = entry.pool;
+      tenantMetrics.push({
+        tenantId,
+        schemaName,
+        connections: {
+          total: pool.totalCount,
+          idle: pool.idleCount,
+          waiting: pool.waitingCount
+        },
+        lastAccessedAt: new Date(entry.lastAccess).toISOString()
+      });
+    }
+    return {
+      pools: {
+        total: tenantMetrics.length,
+        maxPools,
+        tenants: tenantMetrics
+      },
+      shared: {
+        initialized: this.sharedPool !== null,
+        connections: this.sharedPool ? {
+          total: this.sharedPool.totalCount,
+          idle: this.sharedPool.idleCount,
+          waiting: this.sharedPool.waitingCount
+        } : null
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Check health of all pools and connections
+   *
+   * Verifies the health of tenant pools and optionally the shared database.
+   * Returns detailed status information for monitoring and load balancer integration.
+   *
+   * @example
+   * ```typescript
+   * // Basic health check
+   * const health = await manager.healthCheck();
+   * console.log(health.healthy); // true/false
+   *
+   * // Use with Express endpoint
+   * app.get('/health', async (req, res) => {
+   *   const health = await manager.healthCheck();
+   *   res.status(health.healthy ? 200 : 503).json(health);
+   * });
+   *
+   * // Check specific tenants only
+   * const health = await manager.healthCheck({
+   *   tenantIds: ['tenant-1', 'tenant-2'],
+   *   ping: true,
+   *   pingTimeoutMs: 3000,
+   * });
+   * ```
+   */
+  async healthCheck(options = {}) {
+    this.ensureNotDisposed();
+    const startTime = Date.now();
+    const {
+      ping = true,
+      pingTimeoutMs = 5e3,
+      includeShared = true,
+      tenantIds
+    } = options;
+    const poolHealthResults = [];
+    let sharedDbStatus = "ok";
+    let sharedDbResponseTimeMs;
+    let sharedDbError;
+    const poolsToCheck = [];
+    if (tenantIds && tenantIds.length > 0) {
+      for (const tenantId of tenantIds) {
+        const schemaName = this.config.isolation.schemaNameTemplate(tenantId);
+        const entry = this.pools.get(schemaName);
+        if (entry) {
+          poolsToCheck.push({ schemaName, tenantId, entry });
+        }
+      }
+    } else {
+      for (const [schemaName, entry] of this.pools.entries()) {
+        const tenantId = this.tenantIdBySchema.get(schemaName) ?? schemaName;
+        poolsToCheck.push({ schemaName, tenantId, entry });
+      }
+    }
+    const poolChecks = poolsToCheck.map(async ({ schemaName, tenantId, entry }) => {
+      const poolHealth = await this.checkPoolHealth(tenantId, schemaName, entry, ping, pingTimeoutMs);
+      return poolHealth;
+    });
+    poolHealthResults.push(...await Promise.all(poolChecks));
+    if (includeShared && this.sharedPool) {
+      const sharedResult = await this.checkSharedDbHealth(ping, pingTimeoutMs);
+      sharedDbStatus = sharedResult.status;
+      sharedDbResponseTimeMs = sharedResult.responseTimeMs;
+      sharedDbError = sharedResult.error;
+    }
+    const degradedPools = poolHealthResults.filter((p) => p.status === "degraded").length;
+    const unhealthyPools = poolHealthResults.filter((p) => p.status === "unhealthy").length;
+    const healthy = unhealthyPools === 0 && sharedDbStatus !== "unhealthy";
+    return {
+      healthy,
+      pools: poolHealthResults,
+      sharedDb: sharedDbStatus,
+      sharedDbResponseTimeMs,
+      sharedDbError,
+      totalPools: poolHealthResults.length,
+      degradedPools,
+      unhealthyPools,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      durationMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Check health of a single tenant pool
+   */
+  async checkPoolHealth(tenantId, schemaName, entry, ping, pingTimeoutMs) {
+    const pool = entry.pool;
+    const totalConnections = pool.totalCount;
+    const idleConnections = pool.idleCount;
+    const waitingRequests = pool.waitingCount;
+    let status = "ok";
+    let responseTimeMs;
+    let error;
+    if (waitingRequests > 0) {
+      status = "degraded";
+    }
+    if (ping) {
+      const pingResult = await this.executePingQuery(pool, pingTimeoutMs);
+      responseTimeMs = pingResult.responseTimeMs;
+      if (!pingResult.success) {
+        status = "unhealthy";
+        error = pingResult.error;
+      } else if (pingResult.responseTimeMs && pingResult.responseTimeMs > pingTimeoutMs / 2) {
+        if (status === "ok") {
+          status = "degraded";
+        }
+      }
+    }
+    return {
+      tenantId,
+      schemaName,
+      status,
+      totalConnections,
+      idleConnections,
+      waitingRequests,
+      responseTimeMs,
+      error
+    };
+  }
+  /**
+   * Check health of shared database
+   */
+  async checkSharedDbHealth(ping, pingTimeoutMs) {
+    if (!this.sharedPool) {
+      return { status: "ok" };
+    }
+    let status = "ok";
+    let responseTimeMs;
+    let error;
+    const waitingRequests = this.sharedPool.waitingCount;
+    if (waitingRequests > 0) {
+      status = "degraded";
+    }
+    if (ping) {
+      const pingResult = await this.executePingQuery(this.sharedPool, pingTimeoutMs);
+      responseTimeMs = pingResult.responseTimeMs;
+      if (!pingResult.success) {
+        status = "unhealthy";
+        error = pingResult.error;
+      } else if (pingResult.responseTimeMs && pingResult.responseTimeMs > pingTimeoutMs / 2) {
+        if (status === "ok") {
+          status = "degraded";
+        }
+      }
+    }
+    return { status, responseTimeMs, error };
+  }
+  /**
+   * Execute a ping query with timeout
+   */
+  async executePingQuery(pool, timeoutMs) {
+    const startTime = Date.now();
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("Health check ping timeout")), timeoutMs);
+      });
+      const queryPromise = pool.query("SELECT 1");
+      await Promise.race([queryPromise, timeoutPromise]);
+      return {
+        success: true,
+        responseTimeMs: Date.now() - startTime
+      };
+    } catch (err) {
+      return {
+        success: false,
+        responseTimeMs: Date.now() - startTime,
+        error: err.message
+      };
+    }
+  }
   /**
    * Manually evict a tenant pool
    */
@@ -795,6 +1016,12 @@ function createTenantManager(config) {
     async warmup(tenantIds, options) {
       return poolManager.warmup(tenantIds, options);
     },
+    async healthCheck(options) {
+      return poolManager.healthCheck(options);
+    },
+    getMetrics() {
+      return poolManager.getMetrics();
+    },
     async dispose() {
       await poolManager.dispose();
     }