dsh-dbpulse

dsh-dbpulse

English | 中文

A dsh plugin that adds a database-monitoring agent mode plus a live monitoring panel: the dbpulse agent preset (数据库监控模式), its bundled db-monitor skill, and a browser panel (pulse icon in the session header) backed by a host-side dbpulse TypertRemote service. Focused on engine-agnostic operational monitoring, performance diagnosis, and incident triage. Built-in support for MySQL, PostgreSQL, SQLite, SQL Server, MongoDB and Redis — each with zero-trust read-only discipline, connection profiles persisted host-side only. The plugin consists of two official dsh mechanisms:

• cordis.patch.yml — the profile bundle patch declared by the manifest's dsh.bundle.patch field. It inserts two rows: the host-plane plugin that mounts the monitor service, and the @deepseek-ai/dsh-agent-preset declaration that materializes the 数据库监控模式 session mode.
• skills/db-monitor/ — the skill the preset mounts, shipped in this package and resolved from the installed dsh-dbpulse package at mount time.

Since harness 0.2 an agent preset is a declaration carried by a bundle patch, not a directory: the legacy $DSH_HOME/.agent-presets/<id>/ layout (preset.yml + agent.cordis.yml) is no longer read by anything, so the patch above is the single source of truth for the mode.

The panel talks to the host-side dbpulse remote: connection profiles persist under $DSH_HOME/.dbpulse/ (passwords stay host-side, never echoed to the client), and metric collection runs through host-side mysql2 / pg driver connections. On the agent side, the preset mounts a dbpulse_* tool family (driver-based read-only tools) for collection — no deployment database clients required.

Engine support

• Built-in example engines: MySQL and PostgreSQL — every check item (health, slow queries, locks/blocking, query plans, capacity/backup) ships with ready queries.
• Extensible: the skill is organized as "check item → per-engine query"; other engines (SQL Server, Oracle, OceanBase, SQLite, ...) are added in three steps via the "引擎扩展" (engine extension) section inside the skill. For engines not yet mapped, the agent first proposes an equivalent read-only query set, verifies it, then collects — no check item is skipped.

Install

One command, official profile plugin install:

dsh plugin --profile web add dsh-dbpulse

The bundle patch mounts two rows that make the mode and the panel work end to end:

• dbpulse — the bundle's main plugin (default entry lib/index.js) that registers the dbpulse TypertRemote service the browser panel calls.
• preset-dbpulse — the @deepseek-ai/dsh-agent-preset declaration that publishes 数据库监控模式 to the session-mode picker, mounting the dbpulse_* driver tools and the db-monitor skill for agents that select it.

Notes:

• The command applies per profile: run it once for every profile that should offer the mode. Plugin upgrades apply on the next boot, since the preset is declared by the installed package's patch rather than by files copied into your home directory.
• The skill is read from the installed dsh-dbpulse package (skills/), so upgrades ship skill changes with the package; there is nothing to sync and no directory to hand-edit.
• Runtime peer dependencies are the workspace:^ harness packages (cordis, dsh-typert-protocol, dsh-subprocess, dsh-client-*, ...) resolved by pnpm workspace / peer installs; the build toolchain (typescript, tsdown, vitest, react types) lives in devDependencies.
• To customize the mode, copy the row into your own profile patch and override preset-dbpulse by id: an override replaces the row's whole config, so restate id, name, description, order and plugins.

Monitoring panel

Open the pulse icon in the session header for the live monitor. The panel uses a multi-page layout: a sidebar groups pages under Overview / Tools / Monitor / Manage, the home page is a focused dashboard, every detailed concern lives on its own page, and a read-only SQL console doubles the panel as a lightweight database-management tool:

• Dashboard (home): overall status strip, health checks, four gauge cards (connections, cache hit, throughput, slow queries) with trend sparklines, the threshold-breach banner, and a capacity top-N preview.
• SQL Query: a read-only SQL console (SELECT / SHOW / DESCRIBE / EXPLAIN / WITH), ⌘/Ctrl+Enter to run, tabular results (row-capped with a truncation notice) and one-click CSV export; write statements are rejected host-side before execution.
• Connections: create / edit / delete connection profiles (engine, host, port, database, user, password); passwords persist host-side only ($DSH_HOME/.dbpulse/connections-v1.json) and are never echoed back. One-click probe per profile shows server version and latency. Persisted connection / threshold / history files (which include passwords) are written with 0600 permissions — keep $DSH_HOME/.dbpulse/ itself readable only by the current user.
• Metrics: every metric card grouped by category (connections / cache / performance / locks / replication / other).
• Sessions: active sessions sorted by running duration (SQL truncated for display), CSV export.
• Slow queries: slow-query TOP (MySQL via performance_schema digests, PostgreSQL via pg_stat_statements, clearly flagged when the extension is missing); clicking a row fills the EXPLAIN box and runs it in one click.
• Lock waits: blocked / blocker chain, wait seconds and statements.
• Replication: replica/channel IO and replay state, lag seconds.
• Capacity: per-database/tablespace sizes with stacked share bars, CSV export.
• Alert thresholds: per-connection warn/crit thresholds (connection usage, cache hit ratio, replication lag); saving re-tones the dashboard immediately.
• Auto refresh: off / 10s / 30s / 60s, plus manual refresh.

All panel data comes from host-side read-only collection; a failing item degrades individually and is noted in the panel, never a full-screen error. All metric collection runs through host-side database drivers (mysql2 / pg / mssql / node:sqlite / mongodb / redis), no local client binaries required. On the agent side, the preset mounts a dbpulse_* tool family (driver-based read-only tools) for collection.

Engine support

Engine	Snapshot	Sessions	Locks	Slow queries	Replication	EXPLAIN	Capacity	Console
MySQL	✅	✅	✅	✅ perf schema	✅ replication	✅ standard	✅ information_schema	✅ SQL
PostgreSQL	✅	✅	✅	⚠️ pg_stat_statements	✅ pg_stat_replication	✅ ANALYZE BUFFERS	✅ pg_database_size	✅ SQL
SQL Server	✅	✅ sys.dm_exec_*	✅ blocking_session_id	⚠️ dm_exec_query_stats	✅ AG replicas	✅ SHOWPLAN_ALL	✅ master_files	✅ SQL
SQLite	✅ PRAGMA	— (embedded)	—	—	—	✅ QUERY PLAN	✅ file size	✅ SQL
MongoDB	✅ serverStatus	✅ currentOp	—	⚠️ profiler enabled	✅ replSetGetStatus	—	✅ listDatabases+dbStats	—
Redis	✅ INFO	✅ CLIENT LIST	—	✅ SLOWLOG GET	✅ INFO replication	—	⚠️ DBSIZE keys	⚠️ read-only whitelist

Usage

Two complementary entry points: the 数据库监控模式 agent preset for conversational diagnosis, and the pulse-icon panel for visual monitoring. Conversational examples:

• "Run a health check on this MySQL instance and flag any risks"
• "Analyze the 20 slowest queries and give optimization advice"
• "PostgreSQL connections are maxed out — investigate"
• "Check for lock waits and who is blocking whom"

Driver libraries (mysql2 / pg / mssql / node:sqlite / mongodb / redis) are declared dependencies; the plugin connects host-side without shelling out to any binary. Credentials stay server-side only. On the agent side, the preset mounts a dbpulse_* tool family (driver-based read-only tools) for collection — no deployment database clients required.

Model-visible surface

The preset contributes model-visible text and tools: the persona (a database-ops expert with read-only-first discipline and dangerous-operation confirmation), the db-monitor skill in the catalog, and the dbpulse_* driver-tool family (dsh-dbpulse/tools) that the skill collects through. Everything else matches the standard mode (shell, filesystem, web, skills, goals, subagents, workflows); diagnostic power comes from the skill's check-item workflows, executed via those driver tools rather than by shelling out to deployment database clients. Tool calls and prompt sections reconstruct from session logs like any other preset's contributions.

KV Cache impact

No direct impact; the effect of each preset row is the responsibility of its owning package.

Known limitations and deferrals

• No local clients needed. Driver libraries (mysql2 / pg / mssql / node:sqlite / mongodb / redis) are declared dependencies; the plugin connects host-side without shelling out to any binary. Credentials stay server-side only.
• NoSQL engines have reduced surfaces: MongoDB does not support the SQL console or lock-wait pages; Redis supports a curated read-only command whitelist instead of arbitrary SQL. Their sessions/capacity sections still provide useful insights.
• Extensions must be enabled on the target. E.g. pg_stat_statements needs to be enabled; the skill probes availability first and gives the enabling instructions rather than skipping analysis.
• Bundle installs per profile. Run the install command once per profile that should offer the mode; the preset itself is global.
• No scheduled collection or alerting yet. Current scope is on-demand in-session monitoring and diagnosis; periodic sweeps, metric persistence, and alert delivery are deferred to later versions (evolvable as a standalone service plugin).