@qwickapps/server 1.6.0 → 1.7.0

package/src/plugins/postgres/API_ROUTES.md

@@ -0,0 +1,243 @@
+# PostgreSQL Plugin API Routes
+
+This document describes the API routes needed to support the PostgresStatusWidget and PostgresManagementPage UI components.
+
+## Routes to Add
+
+All routes should be registered in the `onGatewayReady` hook of the postgres plugin.
+
+### 1. GET /api/plugins/postgres/stats
+
+Returns current pool statistics and health metrics.
+
+**Response:**
+```typescript
+{
+  total: number;           // Total connections in pool
+  idle: number;            // Idle connections
+  waiting: number;         // Waiting requests
+  active: number;          // Active connections (calculated)
+  utilization: number;     // Percentage (active/total * 100)
+  queryCount: number;      // Queries processed in last minute
+  avgQueryTime: number;    // Average query time in ms
+  health: 'healthy' | 'warning' | 'error';
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/postgres/stats', (req, res) => {
+  const instance = getPostgres(instanceName);
+  const poolStats = instance.getStats();
+
+  res.json({
+    total: poolStats.total,
+    idle: poolStats.idle,
+    waiting: poolStats.waiting,
+    active: poolStats.total - poolStats.idle,
+    utilization: ((poolStats.total - poolStats.idle) / poolStats.total) * 100,
+    queryCount: 0, // TODO: Implement query counter
+    avgQueryTime: 0, // TODO: Implement query timing
+    health: poolStats.waiting > 10 ? 'error' :
+            poolStats.waiting > 5 ? 'warning' : 'healthy',
+  });
+});
+```
+
+### 2. GET /api/plugins/postgres/connections
+
+Returns active database connections with query details.
+
+**Response:**
+```typescript
+Array<{
+  pid: number;
+  user: string;
+  database: string;
+  state: string;
+  query: string;
+  duration: number;
+  waitEvent: string | null;
+}>
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/postgres/connections', async (req, res) => {
+  try {
+    const instance = getPostgres(instanceName);
+    const connections = await instance.query(`
+      SELECT
+        pid,
+        usename as user,
+        datname as database,
+        state,
+        COALESCE(query, '<idle>') as query,
+        EXTRACT(EPOCH FROM (now() - query_start)) * 1000 as duration,
+        wait_event as "waitEvent"
+      FROM pg_stat_activity
+      WHERE datname = current_database()
+      ORDER BY query_start DESC NULLS LAST
+    `);
+
+    res.json(connections);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 3. GET /api/plugins/postgres/query-logs
+
+Returns recent query execution logs.
+
+**Response:**
+```typescript
+Array<{
+  id: string;
+  timestamp: string;
+  query: string;
+  duration: number;
+  rows: number;
+  status: 'success' | 'error';
+}>
+```
+
+**Implementation:**
+```typescript
+// Note: This requires query logging to be implemented in the plugin
+// For now, return empty array or sample data
+app.get('/api/plugins/postgres/query-logs', (req, res) => {
+  res.json([]);
+  // TODO: Implement query logging middleware
+});
+```
+
+### 4. GET /api/plugins/postgres/config
+
+Returns current pool configuration (masked sensitive data).
+
+**Response:**
+```typescript
+{
+  url: string;                 // Masked connection string
+  maxConnections: number;
+  minConnections: number;
+  idleTimeoutMs: number;
+  connectionTimeoutMs: number;
+  statementTimeoutMs: number;
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/postgres/config', (req, res) => {
+  res.json({
+    url: config.url.replace(/:[^:@]+@/, ':***@'),
+    maxConnections: config.maxConnections ?? 20,
+    minConnections: config.minConnections ?? 2,
+    idleTimeoutMs: config.idleTimeoutMs ?? 30000,
+    connectionTimeoutMs: config.connectionTimeoutMs ?? 5000,
+    statementTimeoutMs: config.statementTimeoutMs ?? 0,
+  });
+});
+```
+
+### 5. POST /api/plugins/postgres/connections/:pid/kill
+
+Terminates a specific database connection.
+
+**Request:**
+- URL param: `pid` - Process ID of connection to kill
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.post('/api/plugins/postgres/connections/:pid/kill', async (req, res) => {
+  try {
+    const instance = getPostgres(instanceName);
+    await instance.query('SELECT pg_terminate_backend($1)', [req.params.pid]);
+    res.json({ success: true, message: 'Connection terminated' });
+  } catch (err) {
+    res.status(500).json({ success: false, message: err.message });
+  }
+});
+```
+
+## Integration with Plugin
+
+These routes should be registered in the `onGatewayReady` hook:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register all API routes
+  app.get('/api/plugins/postgres/stats', ...);
+  app.get('/api/plugins/postgres/connections', ...);
+  app.get('/api/plugins/postgres/query-logs', ...);
+  app.get('/api/plugins/postgres/config', ...);
+  app.post('/api/plugins/postgres/connections/:pid/kill', ...);
+}
+```
+
+## Widget Registration
+
+The plugin should also register its status widget and management page:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register API routes (see above)
+
+  // Register control panel UI
+  registry.registerWidget({
+    id: 'postgres-status',
+    title: 'PostgreSQL Database',
+    component: 'PostgresStatusWidget',
+    props: { apiPrefix: '/api/plugins/postgres' },
+    order: 10,
+  });
+
+  registry.registerPage({
+    path: '/cpanel/plugins/postgres',
+    title: 'PostgreSQL Database',
+    component: 'PostgresManagementPage',
+    props: { apiPrefix: '/api/plugins/postgres' },
+  });
+}
+```
+
+## Query Logging Enhancement (Future)
+
+To implement query logging:
+
+1. Add query interceptor in the `query()` method
+2. Store query metadata in memory or database
+3. Track execution time, row count, errors
+4. Implement circular buffer to limit memory usage
+5. Expose via `/query-logs` endpoint
+
+Example structure:
+```typescript
+interface QueryLog {
+  id: string;
+  timestamp: Date;
+  query: string;
+  params?: unknown[];
+  duration: number;
+  rows: number;
+  status: 'success' | 'error';
+  error?: string;
+}
+
+const queryLogs: QueryLog[] = []; // Circular buffer, max 1000 entries
+```
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/postgres/PostgresManagementPage.test.tsx

@@ -0,0 +1,62 @@
+/**
+ * PostgresManagementPage Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { PostgresManagementPage } from './PostgresManagementPage';
+
+describe('PostgresManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ({}),
+      })
+    );
+
+    render(<PostgresManagementPage apiPrefix="/api/postgres" />);
+
+    expect(screen.getByText('PostgreSQL Database Management')).toBeInTheDocument();
+  });
+
+  it('fetches data from multiple endpoints on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ({}),
+      })
+    );
+
+    render(<PostgresManagementPage apiPrefix="/api/postgres" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/api/postgres/stats');
+      expect(global.fetch).toHaveBeenCalledWith('/api/postgres/connections');
+      expect(global.fetch).toHaveBeenCalledWith('/api/postgres/query-logs');
+      expect(global.fetch).toHaveBeenCalledWith('/api/postgres/config');
+    });
+  });
+
+  it('renders all tabs', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ({}),
+      })
+    );
+
+    render(<PostgresManagementPage apiPrefix="/api/postgres" />);
+
+    expect(screen.getByRole('tab', { name: /Overview/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Connections/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Query Logs/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Configuration/i })).toBeInTheDocument();
+  });
+});

package/src/plugins/postgres/PostgresManagementPage.tsx

@@ -0,0 +1,362 @@
+/**
+ * PostgreSQL Management Page Component
+ * Full dashboard for monitoring connections, queries, and database health
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, StatCard, type Column } from '@qwickapps/react-framework';
+
+export interface PostgresManagementPageProps {
+  apiPrefix?: string;
+}
+
+interface ConnectionInfo {
+  pid: number;
+  user: string;
+  database: string;
+  state: string;
+  query: string;
+  duration: number;
+  waitEvent: string | null;
+}
+
+interface QueryLog {
+  id: string;
+  timestamp: string;
+  query: string;
+  duration: number;
+  rows: number;
+  status: 'success' | 'error';
+}
+
+interface PoolConfig {
+  url: string;
+  maxConnections: number;
+  minConnections: number;
+  idleTimeoutMs: number;
+  connectionTimeoutMs: number;
+  statementTimeoutMs: number;
+}
+
+export const PostgresManagementPage: React.FC<PostgresManagementPageProps> = ({
+  apiPrefix = '/api/plugins/postgres',
+}) => {
+  const [connections, setConnections] = useState<ConnectionInfo[]>([]);
+  const [queryLogs, setQueryLogs] = useState<QueryLog[]>([]);
+  const [config, setConfig] = useState<PoolConfig | null>(null);
+  const [stats, setStats] = useState({
+    total: 0,
+    active: 0,
+    idle: 0,
+    waiting: 0,
+    utilization: 0,
+  });
+  const [loading, setLoading] = useState(true);
+  const [activeTab, setActiveTab] = useState<'overview' | 'connections' | 'queries' | 'config'>('overview');
+
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        const [statsRes, connectionsRes, logsRes, configRes] = await Promise.all([
+          fetch(`${apiPrefix}/stats`),
+          fetch(`${apiPrefix}/connections`),
+          fetch(`${apiPrefix}/query-logs`),
+          fetch(`${apiPrefix}/config`),
+        ]);
+
+        if (statsRes.ok) setStats(await statsRes.json());
+        if (connectionsRes.ok) setConnections(await connectionsRes.json());
+        if (logsRes.ok) setQueryLogs(await logsRes.json());
+        if (configRes.ok) setConfig(await configRes.json());
+      } catch (err) {
+        console.error('Failed to fetch postgres data:', err);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchData();
+    const interval = setInterval(fetchData, 5000);
+    return () => clearInterval(interval);
+  }, [apiPrefix]);
+
+  const connectionColumns: Column<ConnectionInfo>[] = [
+    {
+      key: 'pid',
+      label: 'PID',
+      sortable: true,
+      render: (_value, row) => <code className="text-sm">{row.pid}</code>,
+    },
+    {
+      key: 'user',
+      label: 'User',
+      sortable: true,
+    },
+    {
+      key: 'database',
+      label: 'Database',
+      sortable: true,
+    },
+    {
+      key: 'state',
+      label: 'State',
+      sortable: true,
+      render: (_value, row) => (
+        <span
+          className={`inline-block px-2 py-1 rounded text-xs ${
+            row.state === 'active'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200'
+              : 'bg-gray-100 dark:bg-gray-700 text-gray-600 dark:text-gray-300'
+          }`}
+        >
+          {row.state}
+        </span>
+      ),
+    },
+    {
+      key: 'duration',
+      label: 'Duration',
+      sortable: true,
+      render: (_value, row) => `${row.duration}ms`,
+    },
+    {
+      key: 'query',
+      label: 'Query',
+      render: (_value, row) => (
+        <code className="text-xs truncate max-w-xs block" title={row.query}>
+          {row.query}
+        </code>
+      ),
+    },
+  ];
+
+  const queryLogColumns: Column<QueryLog>[] = [
+    {
+      key: 'timestamp',
+      label: 'Time',
+      sortable: true,
+      render: (_value, row) => new Date(row.timestamp).toLocaleString(),
+    },
+    {
+      key: 'status',
+      label: 'Status',
+      sortable: true,
+      render: (_value, row) => (
+        <span
+          className={`inline-block px-2 py-1 rounded text-xs ${
+            row.status === 'success'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200'
+              : 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-200'
+          }`}
+        >
+          {row.status}
+        </span>
+      ),
+    },
+    {
+      key: 'duration',
+      label: 'Duration',
+      sortable: true,
+      render: (_value, row) => `${row.duration}ms`,
+    },
+    {
+      key: 'rows',
+      label: 'Rows',
+      sortable: true,
+    },
+    {
+      key: 'query',
+      label: 'Query',
+      render: (_value, row) => (
+        <code className="text-xs truncate max-w-md block" title={row.query}>
+          {row.query}
+        </code>
+      ),
+    },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="PostgreSQL Database"
+      description="Monitor connection pool, active queries, and database health"
+      breadcrumbs={[
+        { label: 'Control Panel', href: '/cpanel' },
+        { label: 'Plugins', href: '/cpanel/plugins' },
+        { label: 'PostgreSQL' },
+      ]}
+      loading={loading}
+    >
+      {/* Tab Navigation */}
+      <div className="border-b border-gray-200 dark:border-gray-700 mb-6">
+        <nav className="-mb-px flex space-x-8">
+          {(['overview', 'connections', 'queries', 'config'] as const).map((tab) => (
+            <button
+              key={tab}
+              onClick={() => setActiveTab(tab)}
+              className={`py-2 px-1 border-b-2 font-medium text-sm ${
+                activeTab === tab
+                  ? 'border-blue-500 text-blue-600 dark:text-blue-400'
+                  : 'border-transparent text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 hover:border-gray-300 dark:hover:border-gray-600'
+              }`}
+            >
+              {tab.charAt(0).toUpperCase() + tab.slice(1)}
+            </button>
+          ))}
+        </nav>
+      </div>
+
+      {/* Overview Tab */}
+      {activeTab === 'overview' && (
+        <div className="space-y-6">
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+            <StatCard
+              label="Total Connections"
+              value={stats.total}
+              status="info"
+            />
+            <StatCard
+              label="Active"
+              value={stats.active}
+              status={stats.utilization > 80 ? 'warning' : 'healthy'}
+            />
+            <StatCard
+              label="Idle"
+              value={stats.idle}
+              status="info"
+            />
+            <StatCard
+              label="Pool Utilization"
+              value={stats.utilization}
+              unit="%"
+              status={stats.utilization > 95 ? 'error' : stats.utilization > 80 ? 'warning' : 'healthy'}
+            />
+          </div>
+
+          <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+            <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow">
+              <h3 className="text-lg font-semibold mb-4 text-gray-900 dark:text-gray-100">
+                Recent Queries
+              </h3>
+              <DataTable
+                columns={queryLogColumns}
+                data={queryLogs.slice(0, 5)}
+                emptyMessage="No recent queries"
+              />
+            </div>
+
+            <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow">
+              <h3 className="text-lg font-semibold mb-4 text-gray-900 dark:text-gray-100">
+                Active Connections
+              </h3>
+              <DataTable
+                columns={connectionColumns}
+                data={connections.filter((c) => c.state === 'active').slice(0, 5)}
+                emptyMessage="No active connections"
+              />
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Connections Tab */}
+      {activeTab === 'connections' && (
+        <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow">
+          <DataTable
+            columns={connectionColumns}
+            data={connections}
+            emptyMessage="No connections found"
+            bulkActions={[
+              {
+                label: 'Kill Selected',
+                onClick: (selected) => {
+                  console.log('Kill connections:', selected);
+                },
+                variant: 'danger',
+              },
+            ]}
+            selectable
+            getRowKey={(row) => row.pid}
+          />
+        </div>
+      )}
+
+      {/* Queries Tab */}
+      {activeTab === 'queries' && (
+        <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow">
+          <DataTable
+            columns={queryLogColumns}
+            data={queryLogs}
+            emptyMessage="No query logs available"
+            getRowKey={(row) => row.id}
+          />
+        </div>
+      )}
+
+      {/* Config Tab */}
+      {activeTab === 'config' && config && (
+        <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow">
+          <h3 className="text-lg font-semibold mb-4 text-gray-900 dark:text-gray-100">
+            Connection Pool Configuration
+          </h3>
+          <dl className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Database URL
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                <code className="bg-gray-100 dark:bg-gray-700 px-2 py-1 rounded">
+                  {config.url.replace(/:[^:@]+@/, ':***@')}
+                </code>
+              </dd>
+            </div>
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Max Connections
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                {config.maxConnections}
+              </dd>
+            </div>
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Min Connections
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                {config.minConnections}
+              </dd>
+            </div>
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Idle Timeout
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                {config.idleTimeoutMs}ms
+              </dd>
+            </div>
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Connection Timeout
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                {config.connectionTimeoutMs}ms
+              </dd>
+            </div>
+            <div>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                Statement Timeout
+              </dt>
+              <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100">
+                {config.statementTimeoutMs}ms
+              </dd>
+            </div>
+          </dl>
+        </div>
+      )}
+    </PluginManagementPage>
+  );
+};
+
+export default PostgresManagementPage;