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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Show top queries and hit ratios per database
Juan Denisdc08f6975cb7
diff --git a/backend/app/api/databases.py b/backend/app/api/databases.pyindex 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.pyindex 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+@classmethoddef _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.pynew file mode 100644index 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 resultdiff --git a/backend/tests/test_db_insights.py b/backend/tests/test_db_insights.pynew file mode 100644index 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 == 400diff --git a/backend/tests/test_real_db_insights_docker.py b/backend/tests/test_real_db_insights_docker.pynew file mode 100644index 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.mdindex 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.jsxnew file mode 100644index 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.jsonindex 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.jsonindex 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.jsxindex 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.jsindex 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, pasheaders,});}++// 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.scssindex 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);+ }+}