proteum 2.4.1 → 2.4.2

package/AGENTS.md

@@ -63,7 +63,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
     - `/Users/gaetan/Desktop/Projets/klair.work/apps/worker`
 - Inspect how the relevant reference apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
-- Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
+- Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
 - Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.

package/agents/project/AGENTS.md

@@ -27,7 +27,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
-- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` for read-only runtime/status/orientation/owner/route/trace/perf/log reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
+- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
@@ -231,6 +231,7 @@ Verify at the correct layer:
 ## Hard Stops
 
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
+- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
 - Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.

package/agents/project/diagnostics.md

@@ -4,7 +4,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Initial Triage
 
-- Start with compact machine-readable app state before reading large parts of the codebase. When a Proteum MCP client is available, call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Use the returned live `projectId` for follow-up MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_latest`, `trace_show`, `perf_top`, `perf_request`, and `logs_tail`.
+- Start with compact machine-readable app state before reading large parts of the codebase. When a Proteum MCP client is available, call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Use the returned live `projectId` for follow-up MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_latest`, `trace_show`, `perf_top`, `perf_request`, `logs_tail`, and `db_query`.
 - Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use compact CLI commands such as `npx proteum orient <query>`, `npx proteum runtime status`, `npx proteum connect`, `npx proteum explain`, `npx proteum doctor`, and `npx proteum doctor --contracts` when MCP is unavailable, when generated artifacts or manifest-owned files may be stale, or when you need a reproducible shell command, validation step, or CI-like output.
 - MCP payloads are compact `proteum-mcp-v1` JSON and are capped/paginated by default. Use selected instruction previews for read-only discovery and diagnostics; read full files or request full MCP detail only when returned `fullRead`/`fullReadPolicy` or omitted-detail hints require it.
 - Use full-detail escape hatches only after compact output identifies the missing detail: `npx proteum explain --manifest`, `npx proteum diagnose <target> --full`, `npx proteum trace show <requestId> --events`, or `npx proteum perf request <requestId> --full`.
@@ -39,7 +39,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Temporary Instrumentation
 
 - When manifest inspection, trace data, browser console output, and server errors are still insufficient, add temporary targeted logs in the code to confirm control flow, payload shape, query shape, or branch selection.
-- If SQL is needed during diagnosis, keep it read-only. Never use SQL to change database structure or execute schema-mutating DDL.
+- If SQL is needed during diagnosis, use MCP `db_query { projectId, sql }` or `npx proteum db query "<sql>"` against a running dev server. Keep it read-only: only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed, and the response includes rows, columns, elapsed milliseconds, and cap metadata. Never use SQL to change database structure or execute schema-mutating DDL.
 - Keep temporary logs narrow, contextual, and easy to remove. Do not leave broad debug noise in shared execution paths.
 - Re-run only the smallest relevant repro, request, or test after adding temporary instrumentation.
 - Temporary logs added in the code for diagnosis must be cleaned at the end of tests or the repro cycle and must never be committed.

package/agents/project/optimizations.md

@@ -19,7 +19,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 - Prefer established, flexible, well-typed, widely adopted, actively maintained packages.
 - Build custom or keep custom infrastructure only when packages would clearly hurt bundle size, SSR behavior, performance, typing quality, flexibility, licensing, explicit contracts, or long-term maintainability.
 - If you choose custom over a package, state briefly why.
-- For agent-facing repeated diagnostics, prefer the read-only Proteum MCP surface over adding broader CLI output. MCP should expose compact single-line `proteum-mcp-v1` JSON with capped, typed, paginated reads; the CLI should stay compact and reproducible.
+- For agent-facing repeated diagnostics, prefer the read-only Proteum MCP surface over adding broader CLI output. MCP should expose compact single-line `proteum-mcp-v1` JSON with capped, typed, paginated reads; the CLI should stay compact and reproducible. Database diagnostics are limited to one capped `SELECT`, `SHOW`, or `EXPLAIN` read through MCP `db_query` or CLI `proteum db query`.
 
 ## SSR And Page Size
 

package/agents/project/root/AGENTS.md

@@ -18,7 +18,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
 - If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
 - Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
-- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` for read-only runtime/status/orientation/owner/route/trace/perf/log reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
+- When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
@@ -222,6 +222,7 @@ Verify at the correct layer:
 ## Hard Stops
 
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
+- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
 - Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.

package/agents/project/server/services/AGENTS.md

@@ -31,6 +31,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - In database queries, prefer explicit `select` or narrow `include`.
 - For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually.
 - Never use raw SQL DDL or other schema-mutating SQL to change database structure.
+- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

package/cli/commands/db.ts

@@ -0,0 +1,160 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import {
+    defaultDatabaseReadTimeoutMs,
+    maxDatabaseReadLimit,
+    maxDatabaseReadTimeoutMs,
+    type TDatabaseReadQueryResponse,
+} from '../../common/dev/database';
+import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
+
+type TDbAction = 'query';
+
+const allowedActions = new Set<TDbAction>(['query']);
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const parsePositiveInteger = (value: unknown, label: string, max: number) => {
+    if (typeof value !== 'string' || !value.trim()) return undefined;
+
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) throw new UsageError(`${label} must be a positive integer.`);
+    if (parsed > max) throw new UsageError(`${label} must be ${max} or lower.`);
+
+    return parsed;
+};
+
+const requestJson = async <TResponse>(pathname: string, json: object) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: 'POST',
+                json,
+                responseType: 'json',
+                retry: { limit: 0 },
+                throwHttpErrors: false,
+            });
+
+            if (response.statusCode >= 400) {
+                const body = response.body as { error?: string } | undefined;
+                throw new UsageError(body?.error || `Database query failed with status ${response.statusCode}.`);
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum database diagnostics server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or pass `--url http://host:port` if it is bound elsewhere.',
+        ].join('\n'),
+    );
+};
+
+const buildFullCommand = (sql: string) =>
+    [
+        'proteum db query',
+        quoteCommandArgument(sql),
+        typeof cli.args.limit === 'string' && cli.args.limit ? `--limit ${cli.args.limit}` : '',
+        typeof cli.args.timeout === 'string' && cli.args.timeout ? `--timeout ${cli.args.timeout}` : '',
+        typeof cli.args.port === 'string' && cli.args.port ? `--port ${cli.args.port}` : '',
+        typeof cli.args.url === 'string' && cli.args.url ? `--url ${quoteCommandArgument(cli.args.url)}` : '',
+        '--full',
+    ]
+        .filter(Boolean)
+        .join(' ');
+
+export const run = async () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'query';
+    if (!allowedActions.has(action as TDbAction)) {
+        throw new UsageError(`Unsupported db action "${action}". Expected: query.`);
+    }
+
+    const sql = typeof cli.args.sql === 'string' ? cli.args.sql.trim() : '';
+    if (!sql) throw new UsageError('A SELECT, SHOW, or EXPLAIN SQL statement is required.');
+
+    const limit = parsePositiveInteger(cli.args.limit, '--limit', maxDatabaseReadLimit);
+    const timeoutMs = parsePositiveInteger(cli.args.timeout, '--timeout', maxDatabaseReadTimeoutMs);
+    const response = await requestJson<TDatabaseReadQueryResponse>('/__proteum/db/query', {
+        sql,
+        ...(limit !== undefined ? { limit } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+
+    if (cli.args.full === true) {
+        printJson(response);
+        return;
+    }
+
+    printAgentResponse({
+        summary: `${response.kind.toUpperCase()} returned ${response.rows.length}/${response.rowCount} rows in ${response.elapsedMs} ms${response.limited ? ` (limited to ${response.limit})` : ''}.`,
+        data: {
+            kind: response.kind,
+            elapsedMs: response.elapsedMs,
+            rowCount: response.rowCount,
+            returnedRowCount: response.rows.length,
+            limit: response.limit,
+            limited: response.limited,
+            columns: response.columns,
+            rows: response.rows,
+        },
+        fullDetailCommand: buildFullCommand(sql),
+        omitted: response.limited
+            ? [
+                  {
+                      reason: `Rows are capped at ${response.limit}. Raise --limit up to ${maxDatabaseReadLimit} or narrow the query for more detail.`,
+                      command: `proteum db query ${quoteCommandArgument(sql)} --limit ${Math.min(response.limit * 2, maxDatabaseReadLimit)} --timeout ${timeoutMs || defaultDatabaseReadTimeoutMs}`,
+                  },
+              ]
+            : undefined,
+    });
+};

package/cli/mcp/router.ts

@@ -58,6 +58,8 @@ const readOnlyAnnotations = {
 };
 
 const detailSchema = z.enum(['compact', 'full']).optional();
+const databaseLimitSchema = z.number().int().min(1).max(500).optional();
+const databaseTimeoutSchema = z.number().int().min(100).max(30_000).optional();
 const logsLevelSchema = z.enum(['silly', 'log', 'info', 'warn', 'error']).optional();
 const offsetSchema = z.number().int().min(0).max(10_000).optional();
 const positiveLimitSchema = z.number().int().min(1).max(100).optional();
@@ -824,6 +826,22 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         async (input) => await forwardTool('logs_tail', input),
     );
 
+    server.registerTool(
+        'db_query',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Run one capped read-only database diagnostic query for one live Proteum project.',
+            inputSchema: {
+                limit: databaseLimitSchema,
+                projectId: projectIdSchema,
+                sql: z.string().min(1).describe('One SELECT, SHOW, or EXPLAIN SQL statement.'),
+                timeoutMs: databaseTimeoutSchema,
+            },
+            title: 'Proteum Database Query',
+        },
+        async (input) => await forwardTool('db_query', input),
+    );
+
     const closeServer = server.close.bind(server);
     server.close = async () => {
         await closeAllClients();

package/cli/presentation/commands.ts

@@ -21,6 +21,7 @@ export const proteumCommandNames = [
     'orient',
     'diagnose',
     'perf',
+    'db',
     'runtime',
     'mcp',
     'trace',
@@ -59,7 +60,7 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
-    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'db', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
 
@@ -452,6 +453,26 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    db: {
+        name: 'db',
+        category: 'Manifest and contracts',
+        summary: 'Run one capped read-only database diagnostic query against a running Proteum dev server.',
+        usage: 'proteum db [query] <sql> [--limit <rows>] [--timeout <ms>] [--port <port>|--url <baseUrl>] [--full]',
+        bestFor:
+            'Inspecting live MySQL or MariaDB state during diagnosis without giving agents a write-capable SQL execution surface.',
+        examples: [
+            { description: 'Run a small SELECT diagnostic', command: 'proteum db query "SELECT id, email FROM User LIMIT 5"' },
+            { description: 'Inspect table metadata', command: 'proteum db "SHOW TABLES"' },
+            { description: 'Explain a query plan', command: 'proteum db query "EXPLAIN SELECT * FROM User WHERE id = 1"' },
+        ],
+        notes: [
+            'Only SELECT, SHOW, and EXPLAIN statements are allowed.',
+            'The dev runtime executes the query with the app DATABASE_URL and returns rows, columns, elapsedMs, and cap metadata.',
+            'Multi-statement SQL, EXPLAIN ANALYZE, locking reads, LOAD_FILE, SELECT INTO OUTFILE, sleep, and benchmark functions are rejected.',
+            'Default output is compact `proteum-agent-v1` JSON with capped rows; use `--full` for the raw dev endpoint payload.',
+        ],
+        status: 'experimental',
+    },
     runtime: {
         name: 'runtime',
         category: 'Manifest and contracts',

package/cli/runtime/commands.ts

@@ -695,6 +695,38 @@ class PerfCommand extends ProteumCommand {
     }
 }
 
+class DbCommand extends ProteumCommand {
+    public static paths = [['db']];
+
+    public static usage = buildUsage('db');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public limit = Option.String('--limit', { description: 'Maximum number of result rows to return, up to 500.' });
+    public timeout = Option.String('--timeout', { description: 'Database query timeout in milliseconds, up to 30000.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full database query payload.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [first = '', ...restArgs] = this.args;
+        const sql = first === 'query' ? restArgs.join(' ').trim() : [first, ...restArgs].join(' ').trim();
+
+        this.setCliArgs({
+            action: 'query',
+            full: this.full,
+            json: this.json,
+            limit: this.limit ?? '',
+            port: this.port ?? '',
+            sql,
+            timeout: this.timeout ?? '',
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/db'));
+    }
+}
+
 class RuntimeCommand extends ProteumCommand {
     public static paths = [['runtime']];
 
@@ -859,6 +891,7 @@ export const registeredCommands = {
     orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
+    db: DbCommand,
     runtime: RuntimeCommand,
     mcp: McpCommand,
     trace: TraceCommand,
@@ -894,6 +927,7 @@ export const createCli = (version: string) => {
     clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
+    clipanion.register(DbCommand);
     clipanion.register(RuntimeCommand);
     clipanion.register(McpCommand);
     clipanion.register(TraceCommand);

package/cli/utils/agents.ts

@@ -612,7 +612,7 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '',
         '1. When a Proteum MCP client is available, call MCP `workflow_start` first. Pass `cwd` when `projectId` is not known, or pass the stable `projectId` from `projects_list` when it is known.',
         '2. Use the `projectId` returned by live `workflow_start` for every follow-up app-bound MCP tool. If `workflow_start` is ambiguous or returns offline candidates, call MCP `project_resolve { cwd }`, select the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.',
-        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` for read-only runtime, owner, instruction, route, trace, perf, and log reads.',
+        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime, owner, instruction, route, trace, perf, log, and database reads.',
         '4. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after `workflow_start`, `orient`, or `explain_summary` already returned the owner.',
         '5. Treat selected instruction previews returned by MCP as the instruction source for read-only discovery and diagnostics. Read full files only before edits or git writes, when the returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
         '6. Use `npx proteum runtime status` before starting a dev server only when MCP runtime status is unavailable, so an existing tracked session can be reused and the configured router/HMR ports can be checked without probing page bodies. If it says health is unreachable, do not run `diagnose`, `trace`, or `perf`; stop/repair/start the dev session first.',
@@ -631,6 +631,7 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '- Never edit generated files under `.proteum`.',
         '- Never create or edit Prisma migration files manually.',
         '- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX`.',
+        '- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.',
         '- If `schema.prisma` changes, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue` before validation.',
         '- For production changes, add or update focused unit tests for touched behavior when applicable, targeting 100% meaningful coverage for changed production paths.',
         '- Do not run `git restore` or `git reset`.',

package/common/dev/database.ts

@@ -0,0 +1,226 @@
+export type TDatabaseReadQueryKind = 'explain' | 'select' | 'show';
+
+export type TDatabaseReadQueryInput = {
+    limit?: number;
+    sql: string;
+    timeoutMs?: number;
+};
+
+export type TDatabaseReadQueryColumn = {
+    name: string;
+    table?: string;
+    type?: number | string;
+};
+
+export type TDatabaseReadQueryValue = boolean | number | string | null;
+
+export type TDatabaseReadQueryRow = Record<string, TDatabaseReadQueryValue>;
+
+export type TDatabaseReadQueryResponse = {
+    columns: TDatabaseReadQueryColumn[];
+    elapsedMs: number;
+    kind: TDatabaseReadQueryKind;
+    limit: number;
+    limited: boolean;
+    rowCount: number;
+    rows: TDatabaseReadQueryRow[];
+    sql: string;
+};
+
+export type TValidatedDatabaseReadQuery = {
+    kind: TDatabaseReadQueryKind;
+    sql: string;
+};
+
+export const defaultDatabaseReadLimit = 50;
+export const maxDatabaseReadLimit = 500;
+export const defaultDatabaseReadTimeoutMs = 5_000;
+export const maxDatabaseReadTimeoutMs = 30_000;
+
+const allowedQueryKinds = new Set<TDatabaseReadQueryKind>(['explain', 'select', 'show']);
+const sqlKeywordPattern = /^[A-Za-z]+/;
+const sqlCommentPattern = /\/\*[\s\S]*?\*\//g;
+const sqlLineCommentPattern = /(?:^|\n)\s*(?:--|#).*?(?=\n|$)/g;
+
+const clampInteger = ({ fallback, max, min, value }: { fallback: number; max: number; min: number; value?: number }) => {
+    if (value === undefined || !Number.isInteger(value) || value < min) return fallback;
+
+    return Math.min(value, max);
+};
+
+export const normalizeDatabaseReadLimit = (limit?: number) =>
+    clampInteger({
+        fallback: defaultDatabaseReadLimit,
+        max: maxDatabaseReadLimit,
+        min: 1,
+        value: limit,
+    });
+
+export const normalizeDatabaseReadTimeoutMs = (timeoutMs?: number) =>
+    clampInteger({
+        fallback: defaultDatabaseReadTimeoutMs,
+        max: maxDatabaseReadTimeoutMs,
+        min: 100,
+        value: timeoutMs,
+    });
+
+const skipLeadingTrivia = (sql: string) => {
+    let index = 0;
+
+    while (index < sql.length) {
+        const char = sql[index];
+        const next = sql[index + 1];
+
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+
+        if (char === '-' && next === '-') {
+            index = sql.indexOf('\n', index + 2);
+            if (index === -1) return sql.length;
+            continue;
+        }
+
+        if (char === '#') {
+            index = sql.indexOf('\n', index + 1);
+            if (index === -1) return sql.length;
+            continue;
+        }
+
+        if (char === '/' && next === '*') {
+            const end = sql.indexOf('*/', index + 2);
+            if (end === -1) throw new Error('SQL contains an unterminated block comment.');
+            index = end + 2;
+            continue;
+        }
+
+        return index;
+    }
+
+    return index;
+};
+
+const stripSqlComments = (sql: string) =>
+    sql.replace(sqlCommentPattern, ' ').replace(sqlLineCommentPattern, '\n');
+
+const findFirstStatementEnd = (sql: string) => {
+    let quote: "'" | '"' | '`' | undefined;
+    let lineComment = false;
+    let blockComment = false;
+
+    for (let index = 0; index < sql.length; index += 1) {
+        const char = sql[index];
+        const next = sql[index + 1];
+
+        if (lineComment) {
+            if (char === '\n') lineComment = false;
+            continue;
+        }
+
+        if (blockComment) {
+            if (char === '*' && next === '/') {
+                blockComment = false;
+                index += 1;
+            }
+            continue;
+        }
+
+        if (quote) {
+            if (char === '\\') {
+                index += 1;
+                continue;
+            }
+            if (char === quote) quote = undefined;
+            continue;
+        }
+
+        if (char === '-' && next === '-') {
+            lineComment = true;
+            index += 1;
+            continue;
+        }
+
+        if (char === '#') {
+            lineComment = true;
+            continue;
+        }
+
+        if (char === '/' && next === '*') {
+            blockComment = true;
+            index += 1;
+            continue;
+        }
+
+        if (char === '\'' || char === '"' || char === '`') {
+            quote = char;
+            continue;
+        }
+
+        if (char === ';') return index;
+    }
+
+    if (quote) throw new Error('SQL contains an unterminated quoted string.');
+    if (blockComment) throw new Error('SQL contains an unterminated block comment.');
+
+    return -1;
+};
+
+const assertSingleStatement = (sql: string) => {
+    const end = findFirstStatementEnd(sql);
+    if (end === -1) return sql.trim();
+
+    const first = sql.slice(0, end).trim();
+    const rest = stripSqlComments(sql.slice(end + 1)).trim();
+    if (rest) throw new Error('Only one read-only SQL statement may be executed.');
+
+    return first;
+};
+
+const getReadQueryKind = (sql: string): TDatabaseReadQueryKind => {
+    const start = skipLeadingTrivia(sql);
+    const keyword = sql.slice(start).match(sqlKeywordPattern)?.[0]?.toLowerCase();
+
+    if (!keyword || !allowedQueryKinds.has(keyword as TDatabaseReadQueryKind)) {
+        throw new Error('Only SELECT, SHOW, and EXPLAIN SQL statements are allowed.');
+    }
+
+    return keyword as TDatabaseReadQueryKind;
+};
+
+const assertAllowedReadQueryShape = (sql: string) => {
+    const normalized = stripSqlComments(sql).replace(/\s+/g, ' ').trim().toLowerCase();
+
+    if (/\bexplain\s+analyze\b/.test(normalized)) {
+        throw new Error('EXPLAIN ANALYZE is not allowed because it executes the target query.');
+    }
+
+    if (/\binto\s+(?:out|dump)file\b/.test(normalized)) {
+        throw new Error('SELECT INTO OUTFILE and SELECT INTO DUMPFILE are not allowed.');
+    }
+
+    if (/\bload_file\s*\(/.test(normalized)) {
+        throw new Error('LOAD_FILE is not allowed in database diagnostics.');
+    }
+
+    if (/\bfor\s+update\b/.test(normalized) || /\block\s+in\s+share\s+mode\b/.test(normalized)) {
+        throw new Error('Locking read statements are not allowed in database diagnostics.');
+    }
+
+    if (/\b(?:sleep|benchmark)\s*\(/.test(normalized)) {
+        throw new Error('Sleep and benchmark functions are not allowed in database diagnostics.');
+    }
+};
+
+export const validateDatabaseReadQuery = (rawSql: string): TValidatedDatabaseReadQuery => {
+    const normalizedSql = rawSql.replace(/^\uFEFF/, '').trim();
+    if (!normalizedSql) throw new Error('SQL query is required.');
+    if (normalizedSql.length > 20_000) throw new Error('SQL query is too long for database diagnostics.');
+
+    const sql = assertSingleStatement(normalizedSql);
+    const kind = getReadQueryKind(sql);
+
+    assertAllowedReadQueryShape(sql);
+
+    return { kind, sql };
+};

package/common/dev/mcpPayloads.ts

@@ -1,4 +1,5 @@
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from './console';
+import type { TDatabaseReadQueryResponse } from './database';
 import type { TDoctorResponse } from './diagnostics';
 import { buildExplainSummaryItems } from './diagnostics';
 import { explainOwner, type TDiagnoseResponse, type TExplainOwnerResponse, type TOrientResponse } from './inspection';
@@ -733,6 +734,30 @@ export const compactLogsResponse = ({
                 : undefined,
     });
 
+export const compactDatabaseReadQueryResponse = (response: TDatabaseReadQueryResponse) =>
+    createMcpPayload({
+        summary: `${response.kind.toUpperCase()} returned ${response.rows.length}/${response.rowCount} rows in ${response.elapsedMs} ms${response.limited ? ` (limited to ${response.limit})` : ''}.`,
+        data: {
+            kind: response.kind,
+            elapsedMs: response.elapsedMs,
+            rowCount: response.rowCount,
+            returnedRowCount: response.rows.length,
+            limit: response.limit,
+            limited: response.limited,
+            columns: response.columns,
+            rows: response.rows,
+        },
+        omitted: response.limited
+            ? [
+                  {
+                      reason: `Rows are capped at ${response.limit}. Raise the limit up to 500 or make the read query narrower if more detail is needed.`,
+                      tool: 'db_query',
+                      toolArgs: { sql: response.sql, limit: Math.min(response.limit * 2, 500) },
+                  },
+              ]
+            : undefined,
+    });
+
 const readPreview = (filepath: string) => {
     if (fs === undefined) return undefined;
     try {

package/common/dev/mcpServer.ts

@@ -7,6 +7,7 @@ import { stringifyMcpPayload, type TProteumMcpPayload } from './mcpPayloads';
 export type TProteumMcpDetail = 'compact' | 'full';
 
 export type TProteumMcpProvider = {
+    dbQuery: (input: { limit?: number; sql: string; timeoutMs?: number }) => Promise<TProteumMcpPayload>;
     diagnose: (input: {
         logsLevel?: 'silly' | 'log' | 'info' | 'warn' | 'error';
         logsLimit?: number;
@@ -64,6 +65,8 @@ const detailSchema = z.enum(['compact', 'full']).optional();
 const logsLevelSchema = z.enum(['silly', 'log', 'info', 'warn', 'error']).optional();
 const positiveLimitSchema = z.number().int().min(1).max(100).optional();
 const offsetSchema = z.number().int().min(0).max(10_000).optional();
+const databaseLimitSchema = z.number().int().min(1).max(500).optional();
+const databaseTimeoutSchema = z.number().int().min(100).max(30_000).optional();
 
 export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpServerArgs) => {
     const server = new McpServer(
@@ -264,6 +267,21 @@ export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpS
         async ({ level, limit }) => jsonToolResult(await provider.logsTail({ level, limit })),
     );
 
+    server.registerTool(
+        'db_query',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Run one capped read-only database diagnostic query. Only SELECT, SHOW, and EXPLAIN are allowed.',
+            inputSchema: {
+                limit: databaseLimitSchema,
+                sql: z.string().min(1).describe('One SELECT, SHOW, or EXPLAIN SQL statement.'),
+                timeoutMs: databaseTimeoutSchema,
+            },
+            title: 'Proteum Database Query',
+        },
+        async ({ limit, sql, timeoutMs }) => jsonToolResult(await provider.dbQuery({ limit, sql, timeoutMs })),
+    );
+
     for (const [name, uri, description] of [
         ['runtime-status', 'proteum://runtime/status', 'Current compact runtime status.'],
         ['instructions-router', 'proteum://instructions/router', 'Current instruction routing contract.'],

package/docs/mcp.md

@@ -44,6 +44,7 @@ Example tool calls:
 {"tool":"route_candidates","arguments":{"projectId":"prj_0123abcd4567","query":"dashboard","limit":8}}
 {"tool":"explain_summary","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
 {"tool":"diagnose","arguments":{"projectId":"prj_0123abcd4567","path":"/dashboard"}}
+{"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
 ```
 
 `workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
@@ -131,6 +132,7 @@ App-bound tools require `projectId` when called through `proteum mcp`:
 | `perf_top` | Hot-path perf rollup |
 | `perf_request` | One-request waterfall and attribution |
 | `logs_tail` | Capped recent server logs |
+| `db_query` | Capped read-only database diagnostics for one `SELECT`, `SHOW`, or `EXPLAIN` statement |
 
 ## CLI Boundary
 
@@ -145,6 +147,7 @@ proteum diagnose /dashboard --port 3101
 proteum verify request /dashboard --port 3101
 proteum trace show <requestId> --events --port 3101
 proteum explain owner /dashboard
+proteum db query "SELECT id, email FROM User LIMIT 5" --port 3101
 proteum explain --routes --controllers --full # only when the raw route/controller arrays are required
 ```
 
@@ -163,10 +166,14 @@ trace_show { projectId, requestId }
 trace_latest { projectId }
 perf_request { projectId, query }
 logs_tail { projectId }
+db_query { projectId, sql, limit? }
 ```
 
 After an MCP read succeeds, do not run the equivalent CLI command for the same state, and do not run broad source searches for ownership that MCP already returned. CLI output is for fallback, validation, command evidence, and human-shareable reproductions.
 
+Database diagnostics are intentionally read-only. `db_query` and `proteum db query` accept only one `SELECT`, `SHOW`, or `EXPLAIN` statement, return rows, columns, elapsed milliseconds, and cap metadata, and reject multi-statement SQL, `EXPLAIN ANALYZE`, locking reads, file reads/writes, sleep, and benchmark functions.
+
+
 ## Benchmark
 
 The Product `/domains` diagnostic loop measured on May 7, 2026 used `ceil(UTF-8 bytes / 4)` as an output-token estimate:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.4.1",
+	"version": "2.4.2",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/devDiagnostics.ts

@@ -1,8 +1,19 @@
 import fs from 'fs-extra';
+import mysql from 'mysql2/promise';
 import path from 'path';
+import { performance } from 'perf_hooks';
 
 import type { Application } from './index';
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from '@common/dev/console';
+import {
+    normalizeDatabaseReadLimit,
+    normalizeDatabaseReadTimeoutMs,
+    validateDatabaseReadQuery,
+    type TDatabaseReadQueryInput,
+    type TDatabaseReadQueryResponse,
+    type TDatabaseReadQueryRow,
+    type TDatabaseReadQueryValue,
+} from '@common/dev/database';
 import {
     buildDoctorResponse,
     explainSectionNames,
@@ -30,12 +41,31 @@ import {
 } from '@common/dev/inspection';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
 import type { TRequestTrace } from '@common/dev/requestTrace';
+import { parseMariaDbDatabaseUrl } from '@server/services/prisma/mariadb';
 
 const isExplainSectionName = (value: string): value is TExplainSectionName =>
     explainSectionNames.includes(value as TExplainSectionName);
 const isConsoleLogLevel = (value: string): value is TDevConsoleLogLevel =>
     ['silly', 'log', 'info', 'warn', 'error'].includes(value);
 
+const normalizeDatabaseValue = (value: unknown): TDatabaseReadQueryValue => {
+    if (value === null || value === undefined) return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+    if (typeof value === 'bigint') return value.toString();
+    if (value instanceof Date) return value.toISOString();
+    if (Buffer.isBuffer(value)) return `[Buffer ${value.byteLength} bytes]`;
+
+    return JSON.stringify(value);
+};
+
+const normalizeDatabaseRow = (row: unknown): TDatabaseReadQueryRow => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return {};
+
+    return Object.fromEntries(
+        Object.entries(row).map(([key, value]) => [key, normalizeDatabaseValue(value)]),
+    ) as TDatabaseReadQueryRow;
+};
+
 export default class DevDiagnosticsRegistry {
     public constructor(private app: Application) {}
 
@@ -88,6 +118,68 @@ export default class DevDiagnosticsRegistry {
         return { logs: this.app.container.Console.listLogs(limit, isConsoleLogLevel(minimumLevel) ? minimumLevel : 'log') };
     }
 
+    public async databaseReadQuery({
+        limit: rawLimit,
+        sql: rawSql,
+        timeoutMs: rawTimeoutMs,
+    }: TDatabaseReadQueryInput): Promise<TDatabaseReadQueryResponse> {
+        const databaseUrl = process.env.DATABASE_URL;
+        if (!databaseUrl) throw new Error('DATABASE_URL is required before running database diagnostics.');
+
+        const { kind, sql } = validateDatabaseReadQuery(rawSql);
+        const limit = normalizeDatabaseReadLimit(rawLimit);
+        const timeoutMs = normalizeDatabaseReadTimeoutMs(rawTimeoutMs);
+        const connectionConfig = parseMariaDbDatabaseUrl(databaseUrl);
+        const connection = await mysql.createConnection({
+            host: connectionConfig.host,
+            port: connectionConfig.port,
+            user: connectionConfig.user,
+            password: connectionConfig.password,
+            database: connectionConfig.database,
+            connectTimeout: connectionConfig.connectTimeout,
+            multipleStatements: false,
+            supportBigNumbers: true,
+            bigNumberStrings: true,
+            dateStrings: true,
+        });
+        const startedAt = performance.now();
+
+        try {
+            await connection.query('START TRANSACTION READ ONLY');
+            const [rows, fields] = await connection.query({ sql, timeout: timeoutMs });
+            await connection.rollback();
+
+            const rowList = Array.isArray(rows) ? rows : [];
+            const normalizedRows = rowList.map(normalizeDatabaseRow);
+            const elapsedMs = Math.max(0, Math.round(performance.now() - startedAt));
+
+            return {
+                columns: Array.isArray(fields)
+                    ? fields.map((field) => ({
+                          name: field.name,
+                          table: field.table || undefined,
+                          type: field.type,
+                      }))
+                    : [],
+                elapsedMs,
+                kind,
+                limit,
+                limited: normalizedRows.length > limit,
+                rowCount: normalizedRows.length,
+                rows: normalizedRows.slice(0, limit),
+                sql,
+            };
+        } catch (error) {
+            try {
+                await connection.rollback();
+            } catch (_rollbackError) {}
+
+            throw error;
+        } finally {
+            await connection.end();
+        }
+    }
+
     private resolveRequestTrace({ path, requestId }: { path?: string; requestId?: string }): TRequestTrace | undefined {
         if (requestId) return this.app.container.Trace.getRequest(requestId);
         if (!path) return this.app.container.Trace.getLatestRequest();

package/server/app/devMcp.ts

@@ -2,6 +2,7 @@ import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
 import { buildDoctorResponse } from '@common/dev/diagnostics';
 import { buildOrientationResponse, explainOwner } from '@common/dev/inspection';
 import {
+    compactDatabaseReadQueryResponse,
     buildRuntimeStatusPayload,
     compactDiagnoseResponse,
     compactDoctorResponse,
@@ -189,6 +190,15 @@ export const createRuntimeProteumMcpProvider = ({
                 response: diagnostics().readLogs(limit, level),
             });
         },
+        async dbQuery({ limit, sql, timeoutMs }) {
+            return compactDatabaseReadQueryResponse(
+                await diagnostics().databaseReadQuery({
+                    limit,
+                    sql,
+                    timeoutMs,
+                }),
+            );
+        },
         async readResource(uri) {
             if (uri === 'proteum://runtime/status') return await provider.runtimeStatus({});
             if (uri === 'proteum://instructions/router') return await provider.instructionsResolve({});

package/server/services/prisma/mariadb.ts

@@ -19,7 +19,7 @@ const decodeUrlSegment = (value: string) => {
     return decodeURIComponent(value);
 };
 
-export const createMariaDbAdapter = (databaseUrl: string) => {
+export const parseMariaDbDatabaseUrl = (databaseUrl: string) => {
     const url = new URL(databaseUrl);
 
     if (url.protocol !== 'mysql:' && url.protocol !== 'mariadb:')
@@ -34,7 +34,7 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
     const connectTimeoutSeconds = parseInteger(url.searchParams.get('connect_timeout'));
     const idleTimeoutSeconds = parseInteger(url.searchParams.get('max_idle_connection_lifetime'));
 
-    return new PrismaMariaDb({
+    return {
         host: url.hostname,
         port: parseInteger(url.port) ?? defaultPort,
         user: decodeUrlSegment(url.username),
@@ -43,5 +43,9 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
         connectTimeout: connectTimeoutSeconds ? connectTimeoutSeconds * 1_000 : defaultConnectTimeout,
         idleTimeout: idleTimeoutSeconds ?? defaultIdleTimeout,
         ...(connectionLimit !== undefined ? { connectionLimit } : {}),
-    });
+    };
+};
+
+export const createMariaDbAdapter = (databaseUrl: string) => {
+    return new PrismaMariaDb(parseMariaDbDatabaseUrl(databaseUrl));
 };

package/server/services/router/http/index.ts

@@ -606,6 +606,31 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             }
         });
 
+        routes.post('/__proteum/db/query', async (req, res) => {
+            const sql = typeof req.body?.sql === 'string' ? req.body.sql : '';
+            const rawLimit = Number(req.body?.limit);
+            const rawTimeoutMs = Number(req.body?.timeoutMs);
+
+            try {
+                res.json(
+                    await this.app.getDevDiagnostics().databaseReadQuery({
+                        sql,
+                        limit: Number.isFinite(rawLimit) ? rawLimit : undefined,
+                        timeoutMs: Number.isFinite(rawTimeoutMs) ? rawTimeoutMs : undefined,
+                    }),
+                );
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isUsageError =
+                    message.includes('SQL') ||
+                    message.includes('allowed') ||
+                    message.includes('not allowed') ||
+                    message.includes('DATABASE_URL');
+
+                res.status(isUsageError ? 400 : 500).json({ error: message });
+            }
+        });
+
         routes.get('/__proteum/diagnose', (req, res) => {
             const readString = (value: unknown) => (Array.isArray(value) ? value[0] : value);
             const readNumber = (value: unknown, fallback: number) => {

package/tests/cli-mcp-command.test.cjs

@@ -110,6 +110,19 @@ test('mcp help describes projectId routing', () => {
     assert.match(output, /--stdio/);
 });
 
+test('db help describes read-only SQL diagnostics', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'db', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /SELECT, SHOW, and EXPLAIN/);
+    assert.match(output, /--limit/);
+    assert.match(output, /--timeout/);
+});
+
 test('explain help describes compact section summaries', () => {
     const result = spawnSync(process.execPath, [cliBin, 'explain', '--help'], {
         cwd: coreRoot,
@@ -219,6 +232,58 @@ test('runtime status reports occupied configured port without probing page bodie
     }
 });
 
+test('db query posts one read-only SQL statement to the running dev endpoint', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-db-'));
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    let receivedBody = '';
+    const server = http.createServer((req, res) => {
+        if (req.url === '/__proteum/db/query' && req.method === 'POST') {
+            req.on('data', (chunk) => {
+                receivedBody += chunk.toString();
+            });
+            req.on('end', () => {
+                res.setHeader('content-type', 'application/json');
+                res.end(
+                    JSON.stringify({
+                        kind: 'select',
+                        sql: 'SELECT 1',
+                        elapsedMs: 7,
+                        limit: 5,
+                        limited: false,
+                        rowCount: 1,
+                        columns: [{ name: 'value', type: 3 }],
+                        rows: [{ value: 1 }],
+                    }),
+                );
+            });
+            return;
+        }
+
+        res.statusCode = 404;
+        res.end('not found');
+    });
+    const port = await listen(server);
+
+    try {
+        createProteumApp(appRoot, { routerPort: port });
+
+        const result = await runCli(['db', 'query', 'SELECT 1', '--limit', '5'], {
+            cwd: appRoot,
+        });
+        const payload = JSON.parse(result.stdout);
+        const body = JSON.parse(receivedBody);
+
+        assert.equal(result.status, 0);
+        assert.equal(body.sql, 'SELECT 1');
+        assert.equal(body.limit, 5);
+        assert.equal(payload.ok, true);
+        assert.equal(payload.data.elapsedMs, 7);
+        assert.deepEqual(payload.data.rows, [{ value: 1 }]);
+    } finally {
+        await closeServer(server);
+    }
+});
+
 test('runtime status avoids starting a second dev server when the same app owns the port', async () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-same-port-'));
     const appRoot = path.join(repoRoot, 'apps', 'product');

package/tests/mcp.test.cjs

@@ -21,6 +21,10 @@ const {
     resolveInstructionRouting,
 } = require('../common/dev/mcpPayloads.ts');
 const { createProteumMcpServer } = require('../common/dev/mcpServer.ts');
+const {
+    normalizeDatabaseReadLimit,
+    validateDatabaseReadQuery,
+} = require('../common/dev/database.ts');
 const { createProteumMachineMcpServer } = require('../cli/mcp/router.ts');
 const {
     createDevSessionRecord,
@@ -126,6 +130,21 @@ test('instruction routing returns compact selected files for a page query', () =
     assert.equal(payload.data.readWhen.some((entry) => entry.file && entry.file.endsWith('diagnostics.md')), true);
 });
 
+test('database read query policy allows only capped SELECT SHOW and EXPLAIN diagnostics', () => {
+    assert.deepEqual(validateDatabaseReadQuery(' SELECT 1; '), { kind: 'select', sql: 'SELECT 1' });
+    assert.deepEqual(validateDatabaseReadQuery('/* plan */ EXPLAIN SELECT * FROM User'), {
+        kind: 'explain',
+        sql: '/* plan */ EXPLAIN SELECT * FROM User',
+    });
+    assert.deepEqual(validateDatabaseReadQuery('SHOW TABLES'), { kind: 'show', sql: 'SHOW TABLES' });
+    assert.equal(normalizeDatabaseReadLimit(999), 500);
+
+    assert.throws(() => validateDatabaseReadQuery('UPDATE User SET role = "admin"'), /Only SELECT, SHOW, and EXPLAIN/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT 1; DROP TABLE User'), /Only one read-only SQL statement/);
+    assert.throws(() => validateDatabaseReadQuery('EXPLAIN ANALYZE SELECT * FROM User'), /EXPLAIN ANALYZE/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT LOAD_FILE("/etc/passwd")'), /LOAD_FILE/);
+});
+
 test('instruction routing promotes triggered full instruction files', () => {
     const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-trigger-app-'));
     const fallbackRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-trigger-core-'));
@@ -367,6 +386,7 @@ test('trace payload keeps default output compact and paginates full details', ()
 test('MCP server registers the Proteum read-only tool contract', async () => {
     const payload = createMcpPayload({ summary: 'ok', data: { value: 1 } });
     const provider = {
+        dbQuery: async () => payload,
         diagnose: async () => payload,
         doctor: async () => payload,
         explainSummary: async () => payload,
@@ -396,6 +416,7 @@ test('MCP server registers the Proteum read-only tool contract', async () => {
     assert.equal(tools.tools.some((tool) => tool.name === 'runtime_status'), true);
     assert.equal(tools.tools.some((tool) => tool.name === 'workflow_start'), true);
     assert.equal(tools.tools.some((tool) => tool.name === 'route_candidates'), true);
+    assert.equal(tools.tools.some((tool) => tool.name === 'db_query'), true);
     assert.match(result.content[0].text, /proteum-mcp-v1/);
     assert.match(resource.contents[0].text, /proteum-mcp-v1/);