Merge pull request #64 from Relwave/develop

Release v0.6.0-beta.1

Author: Yashh56

FEATURES.md

@@ -12,6 +12,7 @@ This document provides a comprehensive breakdown of all features and capabilitie
 - [Core Pages and Navigation](#core-pages-and-navigation)
 - [Git Version Control](#git-version-control)
 - [Visual Tools](#visual-tools)
+- [Monitoring](#monitoring)
 - [UI and Design System](#ui-and-design-system)
 - [Integration and Architecture](#integration-and-architecture)
 - [Performance](#performance)
@@ -297,27 +298,13 @@ Interactive entity-relationship diagram visualization.
 
 - ReactFlow-based interactive canvas
 - Automatic table node generation with column and type information
-- Primary key highlighting
-- Foreign key relationship lines between tables
-- Auto-layout algorithms
 - Minimap for large diagrams
 - Pan, zoom, and fit-to-screen controls
-- Drag to reposition tables
-- Hover tooltips for relationship details
-
----
-
 ### 7. Settings
 
-Application appearance and preference management.
-
-**Theme Mode**
 
 - Light, dark, and system-preference (auto) modes
-- Real-time theme switching
-
 **Accent Colors**
-
 - Multiple color variants: Blue (default), Purple, Green, Pink, Orange, and more
 - Visual color preview with live UI element updates
 - Persistent preferences
@@ -435,6 +422,87 @@ RelWave includes native Git integration powered by `simple-git`, providing a ful
 
 ---
 
+## Monitoring
+
+RelWave includes a dedicated monitoring feature for live database and bridge health metrics. It provides low-latency charts, gauges, and streaming query insights to help diagnose performance and availability issues.
+
+### The Architecture
+
+- The Poller (Backend): a background worker queries the database every 2–5 seconds (configurable). Use a separate monitoring connection pool.
+- The Stream: metrics are pushed to the UI via WebSockets for real-time charts; HTTP polling is available as a fallback.
+- The Chart (Frontend): time-series charts (Recharts/ApexCharts) append incoming samples and support zoom/hover for details.
+
+### 1. Application-Level Health Checks
+
+- Add a `/health` or `/ping` endpoint that runs a lightweight query to confirm DB availability.
+
+```sql
+SELECT 1;
+```
+
+### 2. Database-Level Monitoring (Metrics & Request Counts)
+
+- PostgreSQL exposes statistics via `pg_stat_database` and `pg_stat_activity` for live query and transaction counts.
+
+Postgres example — total transactions:
+```sql
+SELECT xact_commit + xact_rollback AS total_transactions
+FROM pg_stat_database
+WHERE datname = 'your_db_name';
+```
+
+MySQL/MariaDB example — queries counter:
+```sql
+SHOW GLOBAL STATUS LIKE 'Queries';
+```
+
+### 3. Active Connections (Gauge)
+
+Postgres:
+```sql
+SELECT
+  (SELECT count(*) FROM pg_stat_activity) AS active_connections,
+  (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections;
+```
+
+MySQL/MariaDB:
+```sql
+SHOW GLOBAL STATUS LIKE 'Threads_connected';
+SHOW VARIABLES LIKE 'max_connections';
+```
+
+### 4. Database Throughput / QPS (Time-Series)
+
+- Track total transaction counters over time and compute deltas to derive requests-per-second.
+
+Example calculation: sample the `total_transactions` value every N seconds and compute `(current - previous) / N`.
+
+### 5. Cache Hit Ratio (Health Percentage)
+
+For Postgres the cache hit ratio is:
+$$\text{Cache Hit Ratio} = \left( \frac{\text{blks\_hit}}{\text{blks\_read} + \text{blks\_hit}} \right) \times 100$$
+
+SQL example:
+```sql
+SELECT
+  datname,
+  round(100 * blks_hit / (blks_read + blks_hit + 1), 2) AS cache_hit_ratio
+FROM pg_stat_database
+WHERE datname = 'your_db_name';
+```
+
+MySQL/MariaDB (InnoDB buffer pool): fetch `Innodb_buffer_pool_read_requests` and `Innodb_buffer_pool_reads` and compute:
+$$\text{Buffer Pool Hit Ratio} = \left( 1 - \frac{\text{Innodb\_buffer\_pool\_reads}}{\text{Innodb\_buffer\_pool\_read\_requests}} \right) \times 100$$
+
+### Implementation Tips
+
+- Use a separate connection pool for monitoring queries so UI monitoring doesn't starve application queries.
+- Default polling interval: 2–5 seconds; allow users to increase for low-impact polling.
+- Prefer WebSocket streaming for live dashboards; fallback to polling for environments without persistent sockets.
+- Monitoring queries are low-overhead (read internal stats) but should be rate-limited on large fleets.
+
+---
+
 ## UI and Design System
 
 ### Layout Components
@@ -444,9 +512,9 @@ RelWave includes native Git integration powered by `simple-git`, providing a ful
 - Native minimize, maximize, and close buttons
 - Proper z-index layering
 
-**Vertical Icon Bar**
+-**Vertical Icon Bar**
 - Fixed 60px left sidebar with navigation icons
-- Pages: Home, Settings, SQL Workspace, Query Builder, Schema Explorer, ER Diagram
+- Pages: Home, Settings, SQL Workspace, Query Builder, Schema Explorer, ER Diagram, Monitoring
 - Active state indicators and tooltip labels
 
 **Slide-Out Panels**

bridge/__tests__/monitoringHandlers.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test, jest, beforeEach } from "@jest/globals";
+import { MonitoringHandlers } from "../src/handlers/monitoringHandlers";
+import { DBType } from "../src/types";
+import type { Rpc } from "../src/types";
+
+function createMockRpc(): Rpc & { _responses: any[]; _errors: any[] } {
+    const responses: any[] = [];
+    const errors: any[] = [];
+
+    return {
+        sendResponse: jest.fn((id: number | string, payload: any) => {
+            responses.push({ id, payload });
+        }),
+        sendError: jest.fn((id: number | string, err: any) => {
+            errors.push({ id, err });
+        }),
+        _responses: responses,
+        _errors: errors,
+    };
+}
+
+function createMockLogger(): any {
+    return {
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+        debug: jest.fn(),
+        child: jest.fn().mockReturnThis(),
+    };
+}
+
+function createMockDbService() {
+    return {
+        getDatabaseConnection: jest.fn(),
+    };
+}
+
+function createMockMonitoringService() {
+    return {
+        getSnapshot: jest.fn(),
+    };
+}
+
+describe("MonitoringHandlers", () => {
+    let rpc: ReturnType<typeof createMockRpc>;
+    let logger: any;
+    let dbService: ReturnType<typeof createMockDbService>;
+    let monitoringService: ReturnType<typeof createMockMonitoringService>;
+    let handlers: MonitoringHandlers;
+
+    beforeEach(() => {
+        rpc = createMockRpc();
+        logger = createMockLogger();
+        dbService = createMockDbService();
+        monitoringService = createMockMonitoringService();
+        handlers = new MonitoringHandlers(rpc, logger, dbService as any, monitoringService as any);
+    });
+
+    test("returns BAD_REQUEST when db id is missing", async () => {
+        await handlers.handleGetSnapshot({}, 1);
+
+        expect(rpc.sendError).toHaveBeenCalledWith(1, {
+            code: "BAD_REQUEST",
+            message: "Missing id",
+        });
+        expect(dbService.getDatabaseConnection).not.toHaveBeenCalled();
+    });
+
+    test("returns monitoring snapshot for a valid database", async () => {
+        const conn = { connection: true };
+        const snapshot = {
+            databaseType: DBType.POSTGRES,
+            sampledAt: "2026-05-16T00:00:00.000Z",
+            health: { ok: true, latencyMs: 12 },
+            connections: { active: 2, max: 100, usagePct: 2 },
+            throughput: { qps: 3.5, totalQueries: 1000 },
+            cacheHitRatio: 99.2,
+            activeQueries: [],
+        };
+
+        (dbService.getDatabaseConnection as any).mockResolvedValue({ conn, dbType: DBType.POSTGRES });
+        (monitoringService.getSnapshot as any).mockResolvedValue(snapshot);
+
+        await handlers.handleGetSnapshot({ id: "db-1" }, 2);
+
+        expect(dbService.getDatabaseConnection).toHaveBeenCalledWith("db-1");
+        expect(monitoringService.getSnapshot).toHaveBeenCalledWith("db-1", conn, DBType.POSTGRES);
+        expect(rpc.sendResponse).toHaveBeenCalledWith(2, {
+            ok: true,
+            data: snapshot,
+        });
+    });
+
+    test("returns MONITORING_ERROR when snapshot generation fails", async () => {
+        (dbService.getDatabaseConnection as any).mockResolvedValue({ conn: {}, dbType: DBType.POSTGRES });
+        (monitoringService.getSnapshot as any).mockRejectedValue(new Error("snapshot failed"));
+
+        await handlers.handleGetSnapshot({ id: "db-1" }, 3);
+
+        expect(logger.error).toHaveBeenCalled();
+        expect(rpc.sendError).toHaveBeenCalledWith(3, {
+            code: "MONITORING_ERROR",
+            message: "snapshot failed",
+        });
+    });
+});