Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Show top queries and hit ratios per database

Juan Denisdc08f6975cb7
diff --git a/backend/app/api/databases.py b/backend/app/api/databases.py
index 63084906..b56641f0 100644
--- a/backend/app/api/databases.py
+++ b/backend/app/api/databases.py
@@ -960,6 +960,40 @@ def kill_docker_db_process(container, pid):
return jsonify(result), 200
+# ==================== INSIGHTS (plan 86 §A3) ====================
+# Read-only top queries + connection / cache-hit gauges for a Docker database
+# container, and the one write it offers: turning pg_stat_statements on
+# (through the config tuner, so its rollback undoes it).
+
+def _docker_db_target(container, source):
+ return {
+ 'engine': source.get('type') or 'mysql',
+ 'container': container,
+ 'user': source.get('user'),
+ 'password': request.headers.get('X-DB-Password'),
+ 'database': source.get('database'),
+ }
+
+
+@databases_bp.route('/docker/<container>/insights', methods=['GET'])
+@admin_required
+def docker_db_insights(container):
+ from app.services.db_insights_service import DbInsightsService
+ result = DbInsightsService.insights(_docker_db_target(container, request.args))
+ if 'error' in result:
+ return _process_error_response(result)
+ return jsonify(result), 200
+
+
+@databases_bp.route('/docker/<container>/insights/pg-stat-statements', methods=['POST'])
+@admin_required
+def enable_pg_stat_statements(container):
+ from app.services.db_config_tuner_service import DbConfigTunerService
+ data = request.get_json(silent=True) or {}
+ target = _docker_db_target(container, dict(data, type='postgresql'))
+ return jsonify(DbConfigTunerService.enable_pg_stat_statements(target)), 200
+
+
# ==================== UTILITY ====================
@databases_bp.route('/generate-password', methods=['GET'])
diff --git a/backend/app/services/db_config_tuner_service.py b/backend/app/services/db_config_tuner_service.py
index ecb95928..da89a5b4 100644
--- a/backend/app/services/db_config_tuner_service.py
+++ b/backend/app/services/db_config_tuner_service.py
@@ -502,6 +502,54 @@ class DbConfigTunerService:
return cls._restart_and_verify(target, backup, auto_conf, settings)
+ @classmethod
+ def enable_pg_stat_statements(cls, target):
+ """Preload pg_stat_statements, restart, and create the extension
+ (plan 86 §A3), through the same backup/restart/verify path as
+ :meth:`apply`, so :meth:`rollback` undoes it.
+
+ ``shared_preload_libraries`` is a list: the current value is kept and
+ the library appended, never replaced.
+ """
+ cls._guard(target)
+ if target['engine'] != 'postgresql':
+ raise ValidationError('pg_stat_statements is a PostgreSQL extension')
+ res = cls._exec_sql(target, 'SHOW shared_preload_libraries;')
+ if not res['success']:
+ raise DependencyUnavailableError(res.get('error') or 'Could not read preload libraries')
+ first_line = ((res['output'] or '').strip().splitlines() or [''])[0]
+ current = [lib.strip().strip('"') for lib in first_line.split(',') if lib.strip().strip('"')]
+ if 'pg_stat_statements' in current:
+ created = cls._exec_sql(target, 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements;')
+ if not created['success']:
+ raise DependencyUnavailableError(created.get('error') or 'CREATE EXTENSION failed')
+ return {'success': True, 'restarted': False, 'already_preloaded': True}
+
+ res = cls._exec_sql(target, 'SHOW data_directory;')
+ data_dir = ((res.get('output') or '').strip().splitlines() or [''])[0].strip()
+ if not res['success'] or not data_dir:
+ raise DependencyUnavailableError(res.get('error') or 'Could not determine the data directory')
+ auto_conf = data_dir.rstrip('/') + '/postgresql.auto.conf'
+ backup = cls._snapshot_container_file(target, auto_conf, '.auto.conf')
+
+ libraries = ', '.join(current + ['pg_stat_statements'])
+ literal = "'" + libraries.replace("'", "''") + "'"
+ res = cls._exec_sql(target, f'ALTER SYSTEM SET shared_preload_libraries = {literal};')
+ if not res['success']:
+ cls._restore_container_file(target, backup, auto_conf)
+ raise DependencyUnavailableError(f"ALTER SYSTEM failed: {res['error']}")
+ with open(os.path.join(cls._state_dir(target, create=True), 'applied.json'), 'w') as fh:
+ json.dump({'auto_conf': auto_conf,
+ 'settings': {'shared_preload_libraries': libraries}}, fh)
+
+ result = cls._restart_and_verify(target, backup, auto_conf,
+ {'shared_preload_libraries': libraries})
+ created = cls._exec_sql(target, 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements;')
+ if not created['success']:
+ raise DependencyUnavailableError(
+ f"Preloaded, but CREATE EXTENSION failed: {created.get('error')}")
+ return result
+
@classmethod
def _restart_and_verify(cls, target, backup, container_path, settings):
"""Shared apply tail: restart, ping, roll back on failure."""
diff --git a/backend/app/services/db_insights_service.py b/backend/app/services/db_insights_service.py
new file mode 100644
index 00000000..15269232
--- /dev/null
+++ b/backend/app/services/db_insights_service.py
@@ -0,0 +1,165 @@
+"""Read-only database visibility: top queries and health gauges (plan 86 §A3).
+
+For the Database Explorer's Insights tab, per server or container, with the
+same target shape as :mod:`db_process_service`:
+
+* **gauges**: connections in use vs ``max_connections``, and the cache hit
+ ratio (PostgreSQL ``pg_stat_database`` ``blks_hit/blks_read``, InnoDB buffer
+ pool ``read_requests/reads``);
+* **top queries** by total time: ``pg_stat_statements`` and
+ ``performance_schema.events_statements_summary_by_digest``. Each needs the
+ engine to be collecting; when it is not, the response says why and what
+ turns it on (``DbConfigTunerService.enable_pg_stat_statements``, or
+ ``performance_schema=ON`` for MariaDB, where it is off by default).
+
+Nothing here writes. Status counters come from ``SHOW GLOBAL STATUS``, which
+works on MySQL and MariaDB alike (MySQL 8 has no
+``information_schema.GLOBAL_STATUS``, MariaDB often runs with
+``performance_schema`` off).
+"""
+from typing import Dict, List, Optional
+
+from app.services import db_exec
+
+SUPPORTED_ENGINES = ('mysql', 'postgresql')
+TOP_LIMIT = 20
+
+_PG_GAUGES = (
+ "SELECT (SELECT setting FROM pg_settings WHERE name = 'max_connections'), "
+ "(SELECT count(*) FROM pg_stat_activity), "
+ "COALESCE(sum(blks_hit), 0), COALESCE(sum(blks_read), 0), "
+ "(SELECT count(*) FROM pg_extension WHERE extname = 'pg_stat_statements'), "
+ "(SELECT count(*) FROM pg_settings WHERE name = 'shared_preload_libraries' "
+ "AND setting LIKE '%pg_stat_statements%') "
+ "FROM pg_stat_database;"
+)
+# calls | total ms | mean ms | rows | query (LAST, flattened server-side, so a
+# tab or newline in user SQL can never shift the columns).
+_PG_TOP = (
+ "SELECT calls, round(total_exec_time::numeric, 1), round(mean_exec_time::numeric, 2), "
+ "rows, regexp_replace(query, E'[\\n\\r\\t]+', ' ', 'g') "
+ f"FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT {TOP_LIMIT};"
+)
+_MYSQL_STATUS = (
+ "SHOW GLOBAL STATUS WHERE Variable_name IN "
+ "('Threads_connected', 'Innodb_buffer_pool_read_requests', 'Innodb_buffer_pool_reads');"
+)
+# Timer columns are picoseconds; /1e9 = milliseconds.
+_MYSQL_TOP = (
+ "SELECT COUNT_STAR, ROUND(SUM_TIMER_WAIT / 1e9, 1), ROUND(AVG_TIMER_WAIT / 1e9, 2), "
+ "SUM_ROWS_SENT, REPLACE(REPLACE(REPLACE(DIGEST_TEXT, '\\n', ' '), '\\r', ' '), '\\t', ' ') "
+ "FROM performance_schema.events_statements_summary_by_digest "
+ f"WHERE DIGEST_TEXT IS NOT NULL ORDER BY SUM_TIMER_WAIT DESC LIMIT {TOP_LIMIT};"
+)
+
+
+def _rows(output: str) -> List[List[str]]:
+ return [line.split('\t') for line in (output or '').splitlines() if line.strip()]
+
+
+def _ratio(hits: float, misses: float) -> Optional[float]:
+ total = hits + misses
+ return hits / total if total > 0 else None
+
+
+def _num(value, cast=float):
+ try:
+ return cast(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _queries(rows) -> List[Dict]:
+ out = []
+ for row in rows:
+ if len(row) < 5:
+ continue
+ out.append({'calls': _num(row[0], int), 'total_ms': _num(row[1]),
+ 'mean_ms': _num(row[2]), 'rows': _num(row[3], int),
+ 'query': '\t'.join(row[4:]).strip()})
+ return out
+
+
+class DbInsightsService:
+
+ @staticmethod
+ def _exec_sql(target, sql):
+ """One exec seam (tests stub it), parse-friendly output."""
+ return db_exec.exec_sql(target, sql, machine_readable=True)
+
+ @classmethod
+ def insights(cls, target) -> Dict:
+ engine = (target.get('engine') or '').lower()
+ engine = 'postgresql' if engine in db_exec.POSTGRES_ALIASES else engine
+ engine = 'mysql' if engine in db_exec.MYSQL_ALIASES else engine
+ if engine not in SUPPORTED_ENGINES:
+ return {'error': 'unsupported engine'}
+ if not target.get('container'):
+ # Dockerised engines only (the host executors don't return
+ # parse-friendly output).
+ return {'error': 'insights need a Docker database container'}
+ target = dict(target, engine=engine)
+ return cls._postgres(target) if engine == 'postgresql' else cls._mysql(target)
+
+ @classmethod
+ def _postgres(cls, target) -> Dict:
+ res = cls._exec_sql(target, _PG_GAUGES)
+ if not res['success']:
+ return {'error': res.get('error') or 'query failed'}
+ row = (_rows(res['output']) or [[]])[0]
+ if len(row) < 6:
+ return {'error': 'unexpected output from pg_stat_database'}
+ max_conn, in_use, hit, read, has_ext, preloaded = row[:6]
+ result = {
+ 'engine': 'postgresql',
+ 'connections': {'in_use': _num(in_use, int), 'max': _num(max_conn, int)},
+ 'cache_hit_ratio': _ratio(_num(hit) or 0, _num(read) or 0),
+ 'top_queries': [],
+ 'top_queries_source': 'pg_stat_statements',
+ }
+ if _num(has_ext, int):
+ top = cls._exec_sql(target, _PG_TOP)
+ if top['success']:
+ result['top_queries'] = _queries(_rows(top['output']))
+ result['top_queries_available'] = True
+ return result
+ result['top_queries_reason'] = top.get('error') or 'pg_stat_statements query failed'
+ elif _num(preloaded, int):
+ result['top_queries_reason'] = ('pg_stat_statements is preloaded but the extension '
+ 'is not created in this database')
+ else:
+ result['top_queries_reason'] = 'pg_stat_statements is not enabled'
+ result['top_queries_available'] = False
+ result['can_enable'] = bool(target.get('container'))
+ return result
+
+ @classmethod
+ def _mysql(cls, target) -> Dict:
+ res = cls._exec_sql(target, _MYSQL_STATUS)
+ if not res['success']:
+ return {'error': res.get('error') or 'query failed'}
+ status = {row[0]: row[1] for row in _rows(res['output']) if len(row) >= 2}
+ max_conn = cls._exec_sql(target, 'SELECT @@max_connections;')
+ max_value = (_rows(max_conn['output']) or [[None]])[0][0] if max_conn['success'] else None
+ requests = _num(status.get('Innodb_buffer_pool_read_requests')) or 0
+ disk_reads = _num(status.get('Innodb_buffer_pool_reads')) or 0
+ result = {
+ 'engine': 'mysql',
+ 'connections': {'in_use': _num(status.get('Threads_connected'), int),
+ 'max': _num(max_value, int)},
+ # read_requests counts every logical read; reads are the misses
+ # that went to disk.
+ 'cache_hit_ratio': _ratio(max(requests - disk_reads, 0), disk_reads),
+ 'top_queries': [],
+ 'top_queries_source': 'performance_schema',
+ }
+ top = cls._exec_sql(target, _MYSQL_TOP)
+ if top['success']:
+ result['top_queries'] = _queries(_rows(top['output']))
+ result['top_queries_available'] = True
+ else:
+ result['top_queries_available'] = False
+ result['top_queries_reason'] = (
+ 'performance_schema is not collecting statement digests '
+ '(set performance_schema=ON; it is off by default on MariaDB)')
+ return result
diff --git a/backend/tests/test_db_insights.py b/backend/tests/test_db_insights.py
new file mode 100644
index 00000000..1daff42f
--- /dev/null
+++ b/backend/tests/test_db_insights.py
@@ -0,0 +1,135 @@
+"""Database insights parsing and the pg_stat_statements switch (plan 86 §A3).
+
+Hermetic: SQL is scripted through the services' exec seams. The real-engine
+round trip is test_real_db_insights_docker.py.
+"""
+import pytest
+
+from app.exceptions import ValidationError
+from app.services.db_config_tuner_service import DbConfigTunerService
+from app.services.db_insights_service import DbInsightsService
+
+PG = {'engine': 'postgresql', 'container': 'pg'}
+MY = {'engine': 'mariadb', 'container': 'db'}
+
+
+def _script(monkeypatch, answers, cls=DbInsightsService):
+ seen = []
+
+ def fake(target, sql):
+ seen.append(sql)
+ for needle, result in answers:
+ if needle in sql:
+ return result
+ raise AssertionError(f'unscripted SQL: {sql}')
+ monkeypatch.setattr(cls, '_exec_sql', staticmethod(fake) if cls is DbInsightsService
+ else classmethod(lambda c, t, s: fake(t, s)))
+ return seen
+
+
+def ok(output=''):
+ return {'success': True, 'output': output, 'error': None}
+
+
+def fail(error='boom'):
+ return {'success': False, 'output': '', 'error': error}
+
+
+def test_postgres_without_the_extension_says_what_turns_it_on(monkeypatch):
+ _script(monkeypatch, [('pg_stat_database', ok('100\t7\t990\t10\t0\t0\n'))])
+ result = DbInsightsService.insights(PG)
+ assert result['connections'] == {'in_use': 7, 'max': 100}
+ assert result['cache_hit_ratio'] == pytest.approx(0.99)
+ assert result['top_queries_available'] is False
+ assert result['top_queries_reason'] == 'pg_stat_statements is not enabled'
+ assert result['can_enable'] is True
+
+
+def test_postgres_top_queries_parse_even_with_tabs_in_sql(monkeypatch):
+ _script(monkeypatch, [
+ ('pg_stat_database', ok('100\t3\t5\t5\t1\t1\n')),
+ ('FROM pg_stat_statements', ok('42\t1234.5\t29.39\t42\tSELECT a\tb FROM t\n')),
+ ])
+ (q,) = DbInsightsService.insights(PG)['top_queries']
+ assert q == {'calls': 42, 'total_ms': 1234.5, 'mean_ms': 29.39, 'rows': 42,
+ 'query': 'SELECT a\tb FROM t'}
+
+
+def test_mysql_hit_ratio_and_a_closed_performance_schema(monkeypatch):
+ _script(monkeypatch, [
+ ('SHOW GLOBAL STATUS', ok('Innodb_buffer_pool_read_requests\t1000\n'
+ 'Innodb_buffer_pool_reads\t50\nThreads_connected\t4\n')),
+ ('@@max_connections', ok('151\n')),
+ ('events_statements_summary_by_digest', fail("Table doesn't exist")),
+ ])
+ result = DbInsightsService.insights(MY)
+ assert result['engine'] == 'mysql'
+ assert result['connections'] == {'in_use': 4, 'max': 151}
+ # 1000 logical reads, 50 of them missed and went to disk.
+ assert result['cache_hit_ratio'] == pytest.approx(950 / 1000)
+ assert result['top_queries_available'] is False
+ assert 'performance_schema' in result['top_queries_reason']
+
+
+def test_empty_counters_mean_no_ratio_not_zero(monkeypatch):
+ _script(monkeypatch, [('pg_stat_database', ok('100\t1\t0\t0\t0\t0\n'))])
+ assert DbInsightsService.insights(PG)['cache_hit_ratio'] is None
+
+
[email protected]('target,error', [
+ ({'engine': 'sqlite', 'container': 'x'}, 'unsupported engine'),
+ ({'engine': 'postgresql'}, 'insights need a Docker database container'),
+])
+def test_refused_targets(target, error):
+ assert DbInsightsService.insights(target) == {'error': error}
+
+
+class TestEnablePgStatStatements:
+ @pytest.fixture
+ def tuner(self, monkeypatch, tmp_path):
+ monkeypatch.setattr(DbConfigTunerService, '_linux_supported', classmethod(lambda cls: True))
+ monkeypatch.setattr(DbConfigTunerService, 'STATE_DIR', str(tmp_path))
+ monkeypatch.setattr(DbConfigTunerService, '_snapshot_container_file',
+ classmethod(lambda cls, t, p, s: str(tmp_path / 'previous-1.auto.conf')))
+ restarts = []
+ monkeypatch.setattr(DbConfigTunerService, '_restart_and_verify',
+ classmethod(lambda cls, t, b, p, s: restarts.append(s) or
+ {'success': True, 'restarted': True}))
+ return restarts
+
+ def test_existing_preloads_are_kept(self, monkeypatch, tuner):
+ seen = _script(monkeypatch, [
+ ('SHOW shared_preload_libraries', ok('auto_explain, timescaledb\n')),
+ ('SHOW data_directory', ok('/var/lib/postgresql/data\n')),
+ ('ALTER SYSTEM', ok()), ('CREATE EXTENSION', ok()),
+ ], cls=DbConfigTunerService)
+
+ DbConfigTunerService.enable_pg_stat_statements(PG)
+
+ alter = next(s for s in seen if s.startswith('ALTER SYSTEM'))
+ assert alter == ("ALTER SYSTEM SET shared_preload_libraries = "
+ "'auto_explain, timescaledb, pg_stat_statements';")
+ assert tuner == [{'shared_preload_libraries': 'auto_explain, timescaledb, pg_stat_statements'}]
+ assert seen[-1] == 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements;'
+
+ def test_already_preloaded_only_creates_the_extension(self, monkeypatch, tuner):
+ seen = _script(monkeypatch, [
+ ('SHOW shared_preload_libraries', ok('pg_stat_statements\n')),
+ ('CREATE EXTENSION', ok()),
+ ], cls=DbConfigTunerService)
+ result = DbConfigTunerService.enable_pg_stat_statements(PG)
+ assert result['restarted'] is False and tuner == []
+ assert not any(s.startswith('ALTER SYSTEM') for s in seen)
+
+ def test_mysql_is_refused(self, tuner):
+ with pytest.raises(ValidationError):
+ DbConfigTunerService.enable_pg_stat_statements({'engine': 'mysql', 'container': 'db'})
+
+
+def test_api(client, auth_headers, monkeypatch):
+ _script(monkeypatch, [('pg_stat_database', ok('100\t2\t1\t1\t0\t0\n'))])
+ ok_resp = client.get('/api/v1/databases/docker/pg/insights?type=postgresql',
+ headers={**auth_headers, 'X-DB-Password': 'x'})
+ assert ok_resp.status_code == 200 and ok_resp.get_json()['connections']['max'] == 100
+ bad = client.get('/api/v1/databases/docker/pg/insights?type=oracle', headers=auth_headers)
+ assert bad.status_code == 400
diff --git a/backend/tests/test_real_db_insights_docker.py b/backend/tests/test_real_db_insights_docker.py
new file mode 100644
index 00000000..35f2a12e
--- /dev/null
+++ b/backend/tests/test_real_db_insights_docker.py
@@ -0,0 +1,111 @@
+"""Database insights against REAL engines (plan 86 §A3).
+
+PostgreSQL 16: insights say pg_stat_statements is off, the tuner enables it
+(preload + restart + CREATE EXTENSION), and a query that ran afterwards shows
+up in the top list. MySQL 8: performance_schema collects digests by default,
+so the top list and the InnoDB hit ratio come back straight away.
+
+ SERVERKIT_DOCKER_BUILDS=1 pytest tests -m docker_builds
+"""
+import os
+import shutil
+import subprocess
+import time
+import uuid
+
+import pytest
+
+from app.services.db_config_tuner_service import DbConfigTunerService
+from app.services.db_insights_service import DbInsightsService
+
+
+def _docker_ready() -> bool:
+ if shutil.which('docker') is None:
+ return False
+ try:
+ return subprocess.run(['docker', 'info'], capture_output=True,
+ timeout=20).returncode == 0
+ except (OSError, subprocess.TimeoutExpired):
+ return False
+
+
+pytestmark = [
+ pytest.mark.docker_builds,
+ pytest.mark.skipif(os.environ.get('SERVERKIT_DOCKER_BUILDS') != '1',
+ reason='docker-builds leg; opt in with SERVERKIT_DOCKER_BUILDS=1'),
+ pytest.mark.skipif(not _docker_ready(), reason='docker daemon not reachable'),
+]
+
+PASSWORD = 'insights-pw'
+
+
+def _start(name, image, env):
+ argv = ['docker', 'run', '-d', '--name', name]
+ for key, value in env.items():
+ argv += ['-e', f'{key}={value}']
+ subprocess.run(argv + [image], check=True, capture_output=True, timeout=300)
+
+
+def _wait(fn, what, timeout=120):
+ deadline = time.time() + timeout
+ while True:
+ result = fn()
+ if result:
+ return result
+ assert time.time() < deadline, f'{what} never happened'
+ time.sleep(2)
+
+
+def test_postgres_top_queries_after_enabling_pg_stat_statements(app, monkeypatch, tmp_path):
+ # The tuner is Linux-gated for the panel; the docker daemon is what it
+ # actually needs, and this leg has one.
+ monkeypatch.setattr(DbConfigTunerService, '_linux_supported', classmethod(lambda cls: True))
+ monkeypatch.setattr(DbConfigTunerService, 'STATE_DIR', str(tmp_path))
+ name = f'skc-pg-{uuid.uuid4().hex[:8]}'
+ target = {'engine': 'postgresql', 'container': name, 'user': 'postgres',
+ 'password': PASSWORD, 'database': 'postgres'}
+ try:
+ _start(name, 'postgres:16-alpine', {'POSTGRES_PASSWORD': PASSWORD})
+ before = _wait(lambda: (lambda r: r if 'error' not in r else None)(
+ DbInsightsService.insights(target)), 'postgres ready')
+ assert before['top_queries_available'] is False
+ assert before['can_enable'] is True
+ assert before['connections']['max'] == 100
+ assert 0 <= (before['cache_hit_ratio'] or 0) <= 1
+
+ DbConfigTunerService.enable_pg_stat_statements(target)
+ DbInsightsService._exec_sql(target, 'SELECT count(*) FROM pg_class;')
+
+ after = DbInsightsService.insights(target)
+ assert after['top_queries_available'] is True, after
+ assert any('pg_class' in q['query'] for q in after['top_queries']), after['top_queries']
+ # Enabling twice is a no-op, not a second restart.
+ again = DbConfigTunerService.enable_pg_stat_statements(target)
+ assert again['restarted'] is False
+
+ # The tuner's rollback undoes it (the plan's "rollback comes for free").
+ DbConfigTunerService.rollback(target)
+ preload = DbInsightsService._exec_sql(target, 'SHOW shared_preload_libraries;')
+ assert 'pg_stat_statements' not in preload['output']
+ finally:
+ subprocess.run(['docker', 'rm', '-f', name], capture_output=True, timeout=60)
+
+
+def test_mysql_top_queries_and_buffer_pool_ratio(app):
+ name = f'skc-my-{uuid.uuid4().hex[:8]}'
+ target = {'engine': 'mysql', 'container': name, 'user': 'root', 'password': PASSWORD}
+ try:
+ _start(name, 'mysql:8.4', {'MYSQL_ROOT_PASSWORD': PASSWORD})
+ _wait(lambda: DbInsightsService._exec_sql(target, 'SELECT 1;')['success'],
+ 'mysql ready', timeout=180)
+ DbInsightsService._exec_sql(target, 'SELECT count(*) FROM information_schema.tables;')
+
+ result = DbInsightsService.insights(target)
+ assert 'error' not in result, result
+ assert result['top_queries_available'] is True, result
+ assert any('information_schema' in q['query'].lower() for q in result['top_queries'])
+ assert result['connections']['in_use'] >= 1
+ assert result['connections']['max'] >= 100
+ assert result['cache_hit_ratio'] is not None
+ finally:
+ subprocess.run(['docker', 'rm', '-f', name], capture_output=True, timeout=60)
diff --git a/docs/API_SURFACE.md b/docs/API_SURFACE.md
index 64ca589f..a3564aad 100644
--- a/docs/API_SURFACE.md
+++ b/docs/API_SURFACE.md
@@ -243,6 +243,7 @@ Regenerate (backend/):
- `GET /databases/docker/app/{app_id}`
- `GET /databases/docker/databases`
- `GET /databases/docker/{container}/databases`
+- `GET /databases/docker/{container}/insights`
- `GET /databases/docker/{container}/processes`
- `GET /databases/docker/{container}/{database}/tables`
- `GET /databases/engines`
@@ -853,6 +854,7 @@ Regenerate (backend/):
- `POST /dashboards`
- `POST /dashboards/`
- `POST /dashboards/{board_id}/reset`
+- `POST /databases/docker/{container}/insights/pg-stat-statements`
- `POST /databases/docker/{container}/processes/{pid}/kill`
- `POST /databases/docker/{container}/{database}/query`
- `POST /databases/engines`
diff --git a/frontend/src/components/databases/InsightsPanel.jsx b/frontend/src/components/databases/InsightsPanel.jsx
new file mode 100644
index 00000000..b7982a45
--- /dev/null
+++ b/frontend/src/components/databases/InsightsPanel.jsx
@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { RefreshCw } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import api from '../../services/api';
+import { useToast } from '../../contexts/useToast.js';
+import { useConfirm } from '../../hooks/useConfirm';
+import { Button } from '@/components/ui/button';
+import { formatNumber, formatPercent } from '@/utils/intl';
+
+const QUERY_PREVIEW_LEN = 160;
+
+function formatMs(ms) {
+ if (ms == null) return '—';
+ return ms >= 1000
+ ? `${formatNumber(ms / 1000, { maximumFractionDigits: 1 })} s`
+ : `${formatNumber(ms, { maximumFractionDigits: 1 })} ms`;
+}
+
+// Top queries + connection / cache-hit gauges for a Docker database container
+// (plan 86 §A3). Read-only, except the one switch PostgreSQL needs before it
+// records statements: pg_stat_statements, applied through the config tuner
+// (restart included, rollback available there).
+export default function InsightsPanel({ conn, engine, isAdmin }) {
+ const { t } = useTranslation();
+ const toast = useToast();
+ const { confirm } = useConfirm();
+ const [data, setData] = useState(null);
+ const [error, setError] = useState('');
+ const [enabling, setEnabling] = useState(false);
+ const inFlight = useRef(false);
+ const type = conn?.dockerType || engine;
+
+ const load = useCallback(async () => {
+ if (inFlight.current) return;
+ inFlight.current = true;
+ try {
+ setData(await api.getDockerDbInsights(conn.container, type, conn.user, conn.password));
+ setError('');
+ } catch (err) {
+ setError(err.message || t('app.dbInsights.failedToLoad', 'Failed to load insights'));
+ } finally {
+ inFlight.current = false;
+ }
+ }, [conn, type, t]);
+
+ useEffect(() => { load(); }, [load]);
+
+ async function enableStatements() {
+ if (!await confirm({
+ title: t('app.dbInsights.enableTitle', 'Enable pg_stat_statements'),
+ message: t('app.dbInsights.enableMessage', 'PostgreSQL restarts once to load the extension; open connections drop. The change can be undone from the config tuner.'),
+ confirmText: t('app.dbInsights.enableAndRestart', 'Enable and restart'),
+ })) return;
+ setEnabling(true);
+ try {
+ await api.enablePgStatStatements(conn.container, conn.user, conn.password);
+ toast.success(t('app.dbInsights.enabled', 'pg_stat_statements is on. Queries show up as they run.'));
+ await load();
+ } catch (err) {
+ toast.error(err.message);
+ } finally {
+ setEnabling(false);
+ }
+ }
+
+ if (error) return <div className="dbx-insights"><p className="dbx-insights__error">{error}</p></div>;
+ if (!data) return <div className="dbx-insights"><p>{t('common.loading', 'Loading…')}</p></div>;
+
+ const { connections, cache_hit_ratio: hitRatio } = data;
+ const connShare = connections?.max ? connections.in_use / connections.max : null;
+
+ return (
+ <div className="dbx-insights">
+ <div className="dbx-insights__head">
+ <div className="dbx-insights__gauges">
+ <div className="dbx-insights__gauge">
+ <span className="dbx-insights__label">{t('app.dbInsights.connections', 'Connections')}</span>
+ <span className="dbx-insights__value">
+ {connections?.in_use ?? '—'} / {connections?.max ?? '—'}
+ </span>
+ {connShare != null && (
+ <span className="dbx-insights__sub">{formatPercent(connShare * 100)}</span>
+ )}
+ </div>
+ <div className="dbx-insights__gauge">
+ <span className="dbx-insights__label">
+ {data.engine === 'postgresql'
+ ? t('app.dbInsights.cacheHitPg', 'Buffer cache hit ratio')
+ : t('app.dbInsights.cacheHitMysql', 'InnoDB buffer pool hit ratio')}
+ </span>
+ <span className="dbx-insights__value">
+ {hitRatio == null ? '—' : formatPercent(hitRatio * 100, { decimals: 1 })}
+ </span>
+ </div>
+ </div>
+ <Button variant="outline" size="sm" onClick={load}>
+ <RefreshCw size={14} />
+ {t('common.actions.refresh', 'Refresh')}
+ </Button>
+ </div>
+
+ <h3 className="dbx-insights__title">{t('app.dbInsights.topQueries', 'Top queries by total time')}</h3>
+ {data.top_queries_available ? (
+ data.top_queries.length ? (
+ <table className="dbx-insights__table">
+ <thead>
+ <tr>
+ <th>{t('app.dbInsights.query', 'Query')}</th>
+ <th>{t('app.dbInsights.calls', 'Calls')}</th>
+ <th>{t('app.dbInsights.total', 'Total')}</th>
+ <th>{t('app.dbInsights.mean', 'Mean')}</th>
+ <th>{t('app.dbInsights.rows', 'Rows')}</th>
+ </tr>
+ </thead>
+ <tbody>
+ {data.top_queries.map((q, i) => (
+ <tr key={`${i}-${q.query.slice(0, 32)}`}>
+ <td className="dbx-insights__query" title={q.query}>
+ {q.query.length > QUERY_PREVIEW_LEN
+ ? `${q.query.slice(0, QUERY_PREVIEW_LEN)}…` : q.query}
+ </td>
+ <td>{formatNumber(q.calls)}</td>
+ <td>{formatMs(q.total_ms)}</td>
+ <td>{formatMs(q.mean_ms)}</td>
+ <td>{formatNumber(q.rows)}</td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ ) : (
+ <p className="dbx-insights__note">{t('app.dbInsights.noQueriesYet', 'No statements recorded yet.')}</p>
+ )
+ ) : (
+ <div className="dbx-insights__note">
+ <p>{data.top_queries_reason}</p>
+ {data.can_enable && isAdmin && (
+ <Button size="sm" onClick={enableStatements} disabled={enabling}>
+ {enabling
+ ? t('app.dbInsights.enabling', 'Restarting…')
+ : t('app.dbInsights.enable', 'Enable pg_stat_statements')}
+ </Button>
+ )}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 56edd7eb..8d493c87 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -1580,6 +1580,7 @@
"filterTables": "Filter tables…",
"hideSources": "Hide sources",
"importSqlDump": "Import SQL dump…",
+ "insights": "Insights",
"installADatabaseEngine": "Install a database engine…",
"installADatabaseEngine2": "Install a database engine",
"managed": "Managed",
@@ -1637,6 +1638,25 @@
"wasCreatedOnInstall": "was created on install",
"willBeCreatedOnceTheEngine": "will be created once the engine reports healthy"
},
+ "dbInsights": {
+ "cacheHitMysql": "InnoDB buffer pool hit ratio",
+ "cacheHitPg": "Buffer cache hit ratio",
+ "calls": "Calls",
+ "connections": "Connections",
+ "enable": "Enable pg_stat_statements",
+ "enableAndRestart": "Enable and restart",
+ "enableMessage": "PostgreSQL restarts once to load the extension; open connections drop. The change can be undone from the config tuner.",
+ "enableTitle": "Enable pg_stat_statements",
+ "enabled": "pg_stat_statements is on. Queries show up as they run.",
+ "enabling": "Restarting…",
+ "failedToLoad": "Failed to load insights",
+ "mean": "Mean",
+ "noQueriesYet": "No statements recorded yet.",
+ "query": "Query",
+ "rows": "Rows",
+ "topQueries": "Top queries by total time",
+ "total": "Total"
+ },
"dbUsersPanel": {
"drop": "Drop",
"dropUser": "Drop user “{{username}}”?",
diff --git a/frontend/src/i18n/locales/es.json b/frontend/src/i18n/locales/es.json
index 160af1bc..cb33065a 100644
--- a/frontend/src/i18n/locales/es.json
+++ b/frontend/src/i18n/locales/es.json
@@ -1392,7 +1392,8 @@
"showSources": "Mostrar orígenes",
"sqlConsole": "Consola SQL",
"tableOrCollection": "Tabla o colección",
- "utf8": "UTF-8"
+ "utf8": "UTF-8",
+ "insights": "Estadísticas"
},
"dbAdapter": {
"dockerApps": "Apps de Docker",
@@ -6732,6 +6733,25 @@
"redeploying": "Despliegue iniciado.",
"service": "Servicio",
"title": "Servicios conectados"
+ },
+ "dbInsights": {
+ "cacheHitMysql": "Tasa de aciertos del buffer pool de InnoDB",
+ "cacheHitPg": "Tasa de aciertos de la caché de búferes",
+ "calls": "Llamadas",
+ "connections": "Conexiones",
+ "enable": "Activar pg_stat_statements",
+ "enableAndRestart": "Activar y reiniciar",
+ "enableMessage": "PostgreSQL se reinicia una vez para cargar la extensión; las conexiones abiertas se cortan. El cambio se puede deshacer desde el ajustador de configuración.",
+ "enableTitle": "Activar pg_stat_statements",
+ "enabled": "pg_stat_statements está activo. Las consultas aparecen a medida que se ejecutan.",
+ "enabling": "Reiniciando…",
+ "failedToLoad": "No se pudieron cargar las estadísticas",
+ "mean": "Media",
+ "noQueriesYet": "Todavía no hay sentencias registradas.",
+ "query": "Consulta",
+ "rows": "Filas",
+ "topQueries": "Consultas principales por tiempo total",
+ "total": "Total"
}
},
"auth": {
diff --git a/frontend/src/pages/Databases.jsx b/frontend/src/pages/Databases.jsx
index b7903a27..5b0b95f0 100644
--- a/frontend/src/pages/Databases.jsx
+++ b/frontend/src/pages/Databases.jsx
@@ -4,7 +4,7 @@ import {
PanelLeftClose, PanelLeftOpen, X, RefreshCw, Plus, Terminal,
Archive, Database, Table2, Server, ChevronDown,
Trash2, DatabaseBackup, Copy, FileCode2, Lock, BookMarked, Activity,
- SlidersHorizontal, Layers, ExternalLink, Download,
+ SlidersHorizontal, Layers, ExternalLink, Download, Gauge,
} from 'lucide-react';
import api from '../services/api';
import Modal from '@/components/Modal';
@@ -19,6 +19,7 @@ import ConsoleTab from '../components/databases/ConsoleTab';
import TableDataTab from '../components/databases/TableDataTab';
import BackupsTab from '../components/databases/BackupsTab';
import ProcessListPanel from '../components/databases/ProcessListPanel';
+import InsightsPanel from '../components/databases/InsightsPanel';
import ConfigTunerPanel from '../components/databases/ConfigTunerPanel';
import {
CreateDatabaseModal, CreateMySQLUserModal, CreatePostgreSQLUserModal,
@@ -80,6 +81,7 @@ function dockerDbNode(engine, db, i) {
function TabIcon({ tab }) {
if (tab.kind === 'backups') return <Archive size={13} aria-hidden="true" />;
if (tab.kind === 'processes') return <Activity size={13} aria-hidden="true" />;
+ if (tab.kind === 'insights') return <Gauge size={13} aria-hidden="true" />;
if (tab.kind === 'console') return <Terminal size={13} aria-hidden="true" />;
return <Table2 size={13} aria-hidden="true" />;
}
@@ -437,6 +439,14 @@ export default function Databases() {
showTab(id);
}
+ function openInsights(conn, engine) {
+ // One insights tab per container, like processes.
+ const id = `insights:${engine}:${conn.container}`;
+ setTabs((prev) => prev.some((t) => t.id === id) ? prev
+ : [...prev, { id, kind: 'insights', title: `Insights · ${conn.container}`, conn, engine }]);
+ showTab(id);
+ }
+
function openBackups() {
setTabs((prev) => prev.some((t) => t.id === 'backups') ? prev : [...prev, { id: 'backups', kind: 'backups', titleKey: 'common.labels.backups', title: 'Backups' }]);
showTab('backups');
@@ -629,6 +639,8 @@ export default function Databases() {
if (node.conn?.dbType === 'docker' && node.conn.container) {
// Curated config tuner is container-scoped (docker-only).
actions.splice(2, 0, { labelKey: 'app.databases.configTuner', label: 'Config tuner', icon: SlidersHorizontal, onClick: () => setTunerTarget({ container: node.conn.container, engine: node.engine, password: node.conn.password }) });
+ // Top queries + hit ratio (plan 86 §A3), docker-only too.
+ actions.splice(2, 0, { labelKey: 'app.databases.insights', label: 'Insights', icon: Gauge, onClick: () => openInsights(node.conn, node.engine) });
}
actions.splice(2, 0, { labelKey: 'app.databases.backUpDatabase', label: 'Back up database', icon: DatabaseBackup, onClick: () => backupDatabase(node) });
actions.push({ labelKey: 'app.databases.dropDatabase', label: 'Drop database', icon: Trash2, danger: true, onClick: () => dropDatabase(node) });
@@ -952,6 +964,9 @@ export default function Databases() {
isAdmin={isAdmin}
/>
)}
+ {tab.kind === 'insights' && (
+ <InsightsPanel conn={tab.conn} engine={tab.engine} isAdmin={isAdmin} />
+ )}
{tab.kind === 'backups' && <BackupsTab />}
</div>
))}
diff --git a/frontend/src/services/api/dbProcesses.js b/frontend/src/services/api/dbProcesses.js
index 62dd4eb0..47ce5884 100644
--- a/frontend/src/services/api/dbProcesses.js
+++ b/frontend/src/services/api/dbProcesses.js
@@ -24,3 +24,21 @@ export async function killDockerDbProcess(container, pid, type, user = null, pas
headers,
});
}
+
+// Top queries + connection / cache-hit gauges for a Docker database container
+// (plan 86 §A3), and the switch PostgreSQL needs before it records statements.
+export async function getDockerDbInsights(container, type, user = null, password = null) {
+ const headers = password ? { 'X-DB-Password': password } : {};
+ const params = new URLSearchParams({ type: type || 'mysql' });
+ if (user) params.set('user', user);
+ return this.request(`/databases/docker/${container}/insights?${params.toString()}`, { headers });
+}
+
+export async function enablePgStatStatements(container, user = null, password = null) {
+ const headers = password ? { 'X-DB-Password': password } : {};
+ return this.request(`/databases/docker/${container}/insights/pg-stat-statements`, {
+ method: 'POST',
+ body: { user },
+ headers,
+ });
+}
diff --git a/frontend/src/styles/pages/_bandwidth.scss b/frontend/src/styles/pages/_bandwidth.scss
index 0d77e4b9..1b74121d 100644
--- a/frontend/src/styles/pages/_bandwidth.scss
+++ b/frontend/src/styles/pages/_bandwidth.scss
@@ -153,3 +153,94 @@
color: var(--text-dim);
}
}
+
+// Database Explorer: Insights tab (plan 86 §A3).
+// Component: databases/InsightsPanel.
+.dbx-insights {
+ padding: 16px;
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ overflow: auto;
+
+ &__head {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 16px;
+ }
+
+ &__gauges {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 32px;
+ }
+
+ &__gauge {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ }
+
+ &__label,
+ &__sub {
+ font-size: 11.5px;
+ color: var(--text-dim);
+ }
+
+ &__value {
+ font-family: var(--mono);
+ font-size: 18px;
+ color: var(--text);
+ }
+
+ &__title {
+ margin: 8px 0 0;
+ font-size: 13px;
+ color: var(--text);
+ }
+
+ &__table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 12.5px;
+
+ th {
+ text-align: start;
+ font-weight: 500;
+ color: var(--text-dim);
+ padding: 6px 8px;
+ border-bottom: 1px solid var(--border-soft);
+ }
+
+ td {
+ padding: 6px 8px;
+ border-bottom: 1px solid var(--border-soft);
+ font-family: var(--mono);
+ white-space: nowrap;
+ }
+ }
+
+ &__query {
+ max-width: 0;
+ width: 60%;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ }
+
+ &__note {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: 8px;
+ margin: 0;
+ font-size: 12.5px;
+ color: var(--text-dim);
+
+ p { margin: 0; }
+ }
+
+ &__error {
+ color: var(--red);
+ }
+}