@wpmoo/toolkit 0.9.10 → 0.9.11

package/README.md

@@ -171,8 +171,8 @@ npx @wpmoo/toolkit doctor --json --postgres
 JSON output is optional; human-readable output remains the default.
 `doctor --postgres` adds read-only PostgreSQL health and performance diagnostics
 such as database size, sessions currently running queries with
-`pg_stat_activity.state = 'active'`, slow-query readiness, extension visibility,
-and settings.
+`pg_stat_activity.state = 'active'`, connection utilization against
+`max_connections`, slow-query readiness, extension visibility, and settings.
 `doctor --json --postgres` includes a structured `postgres` object for automation.
 Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 

package/dist/doctor.js

@@ -57,6 +57,15 @@ WITH metrics(metric, value) AS (
     WHERE datname IS NOT NULL
       AND state = 'active'
   UNION ALL
+  SELECT 'connection_count', count(*)::text
+    FROM pg_stat_activity
+    WHERE datname IS NOT NULL
+  UNION ALL
+  SELECT 'max_connections', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'max_connections'),
+    'unavailable'
+  )
+  UNION ALL
   SELECT 'total_database_size_bytes', COALESCE(sum(pg_database_size(datname)), 0)::text
     FROM pg_database
     WHERE datistemplate = false
@@ -83,16 +92,20 @@ FROM metrics
 ORDER BY CASE metric
   WHEN 'database_count' THEN 1
   WHEN 'active_connections' THEN 2
-  WHEN 'total_database_size_bytes' THEN 3
-  WHEN 'slow_query_logging' THEN 4
-  WHEN 'pg_stat_statements' THEN 5
-  WHEN 'shared_buffers' THEN 6
+  WHEN 'connection_count' THEN 3
+  WHEN 'max_connections' THEN 4
+  WHEN 'total_database_size_bytes' THEN 5
+  WHEN 'slow_query_logging' THEN 6
+  WHEN 'pg_stat_statements' THEN 7
+  WHEN 'shared_buffers' THEN 8
   ELSE 99
 END;
 `.trim();
 const postgresDiagnosticKeys = [
     'database_count',
     'active_connections',
+    'connection_count',
+    'max_connections',
     'total_database_size_bytes',
     'slow_query_logging',
     'pg_stat_statements',
@@ -127,9 +140,14 @@ function parsePostgresDiagnostics(output) {
     return diagnostics;
 }
 function renderPostgresDiagnostics(diagnostics) {
+    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
     const parts = postgresDiagnosticKeys.flatMap((key) => {
         const value = diagnostics[key];
-        return value ? [`${key}=${value}`] : [];
+        const rendered = value ? [`${key}=${value}`] : [];
+        if (key === 'max_connections' && connectionUtilizationPct !== undefined) {
+            rendered.push(`connection_utilization_pct=${connectionUtilizationPct}`);
+        }
+        return rendered;
     });
     return parts.length > 0 ? `OK PostgreSQL diagnostics ${parts.join(' ')}` : undefined;
 }
@@ -151,19 +169,50 @@ function malformedPostgresDiagnosticKeys(diagnostics) {
     const numericKeys = [
         'database_count',
         'active_connections',
+        'connection_count',
+        'max_connections',
         'total_database_size_bytes',
     ];
     return numericKeys.filter((key) => diagnostics[key] !== undefined && integerDiagnostic(diagnostics[key]) === undefined);
 }
+function postgresConnectionUtilizationPct(diagnostics) {
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    if (connectionCount === undefined || maxConnections === undefined || maxConnections <= 0) {
+        return undefined;
+    }
+    return Math.round((connectionCount / maxConnections) * 100);
+}
+function postgresConnectionUtilizationWarning(diagnostics) {
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    const utilizationPct = postgresConnectionUtilizationPct(diagnostics);
+    if (connectionCount === undefined ||
+        maxConnections === undefined ||
+        utilizationPct === undefined ||
+        utilizationPct < 80) {
+        return undefined;
+    }
+    return `PostgreSQL connection utilization is high: ${utilizationPct}% of max_connections used (${connectionCount}/${maxConnections}).`;
+}
 function structuredPostgresDiagnostics(diagnostics) {
     const structured = {};
     const databaseCount = integerDiagnostic(diagnostics.database_count);
     const activeConnections = integerDiagnostic(diagnostics.active_connections);
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
     const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
     if (databaseCount !== undefined)
         structured.databaseCount = databaseCount;
     if (activeConnections !== undefined)
         structured.activeConnections = activeConnections;
+    if (connectionCount !== undefined)
+        structured.connectionCount = connectionCount;
+    if (maxConnections !== undefined)
+        structured.maxConnections = maxConnections;
+    if (connectionUtilizationPct !== undefined)
+        structured.connectionUtilizationPct = connectionUtilizationPct;
     if (totalDatabaseSizeBytes !== undefined)
         structured.totalDatabaseSizeBytes = totalDatabaseSizeBytes;
     if (diagnostics.slow_query_logging)
@@ -584,6 +633,10 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                     available: true,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
                 };
+                const connectionUtilizationWarning = postgresConnectionUtilizationWarning(postgresDiagnostics);
+                if (connectionUtilizationWarning) {
+                    warnings.push(connectionUtilizationWarning);
+                }
             }
             else {
                 const warning = malformedKeys.length > 0

package/dist/help.js

@@ -110,7 +110,8 @@ Status and doctor:
   doctor --fix: applies safe file-level repairs. Runs doctor again after fixes.
   doctor --postgres: adds read-only PostgreSQL diagnostics such as database size,
     sessions currently running queries with pg_stat_activity.state = 'active',
-    slow-query readiness, extension visibility, and settings.
+    connection utilization against max_connections, slow-query readiness,
+    extension visibility, and settings.
     Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 Task recipes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/toolkit",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
   "type": "module",
   "repository": {