feat(key-analytics): scan every non-empty logical database and honor dbIndex

apps/api/src/common/interfaces/database-port.interface.ts

@@ -96,7 +96,12 @@ export interface DatabasePort {
   getConfigValues(pattern: string): Promise<ConfigGetResponse>;
   getDbSize(): Promise<number>;
   getLastSaveTime(): Promise<number>;
-  collectKeyAnalytics(options: KeyAnalyticsOptions): Promise<KeyAnalyticsResult>;
+  /**
+   * One result per scanned logical database. Adapters that can discover
+   * sibling databases (via `INFO keyspace`) scan every non-empty one; others
+   * return a single result for the connected database.
+   */
+  collectKeyAnalytics(options: KeyAnalyticsOptions): Promise<KeyAnalyticsResult[]>;
   getVectorIndexList(): Promise<string[]>;
   getVectorIndexInfo(indexName: string): Promise<VectorIndexInfo>;
   getHashFieldBuffer(key: string, field: string): Promise<Buffer | null>;

apps/api/src/common/interfaces/storage-port.interface.ts

@@ -507,12 +507,14 @@ export interface StoragePort {
     startTime?: number,
     endTime?: number,
     connectionId?: string,
+    db?: number,
   ): Promise<KeyAnalyticsSummary | null>;
   getKeyPatternTrends(
     pattern: string,
     startTime: number,
     endTime: number,
     connectionId?: string,
+    db?: number,
   ): Promise<
     Array<{
       timestamp: number;
@@ -522,10 +524,18 @@ export interface StoragePort {
     }>
   >;
   pruneOldKeyPatternSnapshots(cutoffTimestamp: number, connectionId?: string): Promise<number>;
+  /** Distinct logical database indexes present in stored key-pattern snapshots. */
+  getKeyAnalyticsDatabases(connectionId?: string): Promise<number[]>;
 
   // Hot Key Stats Methods - connectionId required for writes, optional filter for reads
   saveHotKeys(entries: HotKeyEntry[], connectionId: string): Promise<number>;
   getHotKeys(options?: HotKeyQueryOptions): Promise<HotKeyEntry[]>;
+  /**
+   * Distinct logical database indexes present in stored hot-key stats. Separate
+   * from getKeyAnalyticsDatabases because hot-key / composite rows live in
+   * hot_key_stats, which can diverge from key_pattern_snapshots.
+   */
+  getHotKeyDatabases(connectionId?: string): Promise<number[]>;
   pruneOldHotKeys(cutoffTimestamp: number, connectionId?: string): Promise<number>;
 
   // Settings Methods (global, not connection-scoped)

apps/api/src/config/env.schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { MAX_RETENTION_DAYS, parseRetentionDaysToken } from '@betterdb/shared';
 import {
+  clampTopN,
   DEFAULT_KEY_DETAILS_TOP_N,
   DEFAULT_KEY_PATTERNS_TOP_N,
   DEFAULT_SLOT_STATS_TOP_N,
@@ -42,7 +43,7 @@ const topNEnv = (max: number, def: number) =>
     (value) => (typeof value === 'string' && value.trim() === '' ? undefined : value),
     z.coerce
       .number()
-      .transform((n) => (Number.isFinite(n) ? Math.min(max, Math.max(0, Math.floor(n))) : def))
+      .transform((n) => (Number.isFinite(n) ? clampTopN(n, max) : def))
       .default(def)
       .catch(def),
   );

apps/api/src/connections/connection-registry.service.ts

@@ -356,6 +356,7 @@ export class ConnectionRegistry implements OnModuleInit, OnModuleDestroy {
       port: config.port,
       username: config.username || 'default',
       password: config.password || '',
+      dbIndex: config.dbIndex,
       connectionName,
       tls: config.tls,
       tlsServername: config.membership?.origin === 'auto' ? config.membership.hostname : undefined,
@@ -645,6 +646,21 @@ export class ConnectionRegistry implements OnModuleInit, OnModuleDestroy {
       throw new Error(`Connection failed: ${errorMsg}`);
     }
 
+    // Validation parity with testConnection: a live connection tolerates a
+    // rejected SELECT by falling back to db0 (so stored configs survive an
+    // upgrade), but Save must not silently persist a connection that monitors
+    // a different database than the user asked for.
+    if (
+      adapter instanceof UnifiedDatabaseAdapter &&
+      (config.dbIndex ?? 0) > 0 &&
+      adapter.getActiveDbIndex() !== config.dbIndex
+    ) {
+      await adapter.disconnect().catch(() => {});
+      throw new Error(
+        `Connection failed: could not SELECT database ${config.dbIndex} — the server rejected it (index out of range, cluster mode, or ACL without +select)`,
+      );
+    }
+
     // Connection succeeded - now persist state
     // If storage fails, disconnect the adapter to prevent leaks
     try {
@@ -802,6 +818,7 @@ export class ConnectionRegistry implements OnModuleInit, OnModuleDestroy {
       username: request.username || 'default',
       password: request.password || '',
       tls: request.tls,
+      dbIndex: request.dbIndex,
       // Unique id so a test tunnel never collides with a live connection's tunnel.
       connectionId: `test:${randomUUID()}`,
       sshTunnel: this.sanitizeSshTunnelInput(request.sshTunnel),
@@ -810,6 +827,16 @@ export class ConnectionRegistry implements OnModuleInit, OnModuleDestroy {
 
     try {
       await adapter.connect();
+      // A live connection tolerates a rejected SELECT by falling back to db0
+      // (availability), but a TEST is validation: surface the bad index here
+      // so the user fixes it before saving instead of silently monitoring db0.
+      if ((request.dbIndex ?? 0) > 0 && adapter.getActiveDbIndex() !== request.dbIndex) {
+        await adapter.disconnect();
+        return {
+          success: false,
+          error: `Could not SELECT database ${request.dbIndex} — the server rejected it (index out of range, cluster mode, or ACL without +select)`,
+        };
+      }
       const capabilities = adapter.getCapabilities();
       await adapter.disconnect();
 
@@ -1152,6 +1179,11 @@ export class ConnectionRegistry implements OnModuleInit, OnModuleDestroy {
 
   async adoptChild(id: string, seedId: string, node: DesiredNode): Promise<void> {
     await this.setMembership(id, { seedId, origin: 'adopted', ...membershipFields(node) });
+    // The adopted connection keeps its configured dbIndex: whether SELECT on a
+    // non-zero db is legal on a cluster node depends on the server (illegal
+    // before Valkey 9, legal on Valkey 9 multi-db clusters), so the connect
+    // path decides at runtime — a rejected SELECT falls back to db0 with a
+    // warning instead of this registry guessing and clobbering the config.
   }
 
   async refreshChild(id: string, node: DesiredNode): Promise<void> {