sql-dev-inspector 0.0.0-stage → 1.0.0

package/dist/node.d.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface SqlInspector {
+    /** False when the environment switched the inspector off; every other member is then a no-op. */
+    enabled: boolean;
+    /** Connect / Express style middleware. Mount it before your routes. */
+    middleware: (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+    /**
+     * For plain `http` servers and other frameworks: serves the inspector's own pages and
+     * returns true when it did, in which case the request must not be handled further.
+     */
+    handle: (req: IncomingMessage, res: ServerResponse) => boolean;
+    /** Runs `fn` as one traced request; everything awaited inside is attributed to it. */
+    track: <T>(req: IncomingMessage, res: ServerResponse, fn: () => T) => T;
+    /** Runs `fn` as one traced unit of work that is not an HTTP request (job, cron, script). */
+    task: <T>(name: string, fn: () => T | Promise<T>) => Promise<T>;
+}
+/**
+ * Framework-agnostic entry point for any Node server whose SQL goes through mysql2
+ * (directly, or via Drizzle, Knex, Sequelize, TypeORM, Prisma's mysql2 adapter…).
+ */
+export declare function createSqlInspector(): SqlInspector;
+declare module "node:http" {
+    interface IncomingMessage {
+        /** Set by Express when a router rewrites `url`. */
+        originalUrl?: string;
+    }
+}

package/dist/node.js

@@ -0,0 +1,52 @@
+import { handleInspectorRequest, inspectorSubPath } from "./inspector-server.js";
+import { startInspector } from "./setup.js";
+import { runInRequest } from "./tracer.js";
+/**
+ * Framework-agnostic entry point for any Node server whose SQL goes through mysql2
+ * (directly, or via Drizzle, Knex, Sequelize, TypeORM, Prisma's mysql2 adapter…).
+ */
+export function createSqlInspector() {
+    const inspector = startInspector();
+    if (!inspector) {
+        return {
+            enabled: false,
+            middleware: (_req, _res, next) => next(),
+            handle: () => false,
+            track: (_req, _res, fn) => fn(),
+            task: async (_name, fn) => await fn()
+        };
+    }
+    const { store } = inspector;
+    const handle = (req, res) => {
+        const subPath = inspectorSubPath(req.url);
+        if (subPath === null) {
+            return false;
+        }
+        handleInspectorRequest(req, res, subPath, inspector);
+        return true;
+    };
+    const track = (req, res, fn) => {
+        const trace = store.startRequest(req.method ?? "GET", req.originalUrl ?? req.url ?? "/");
+        res.once("close", () => store.finishRequest(trace, res.statusCode));
+        return runInRequest(trace, fn);
+    };
+    return {
+        enabled: true,
+        handle,
+        track,
+        middleware: (req, res, next) => {
+            if (!handle(req, res)) {
+                track(req, res, () => next());
+            }
+        },
+        task: async (name, fn) => {
+            const trace = store.startRequest("TASK", name);
+            try {
+                return await runInRequest(trace, fn);
+            }
+            finally {
+                store.finishRequest(trace, 0);
+            }
+        }
+    };
+}

package/dist/nuxt.d.ts

@@ -0,0 +1,20 @@
+interface NuxtLike {
+    options: {
+        dev: boolean;
+        nitro: {
+            plugins?: string[];
+        };
+        plugins: (string | {
+            src: string;
+            mode?: string;
+        })[];
+    };
+}
+/**
+ * Nuxt module. In `nuxt dev` only, registers the SQL Inspector Nitro plugin (server) and the
+ * floating launcher (client), so `nuxt build` and `nuxt generate` never see them and nothing
+ * ships to a deployed environment. Written as a plain function (no `@nuxt/kit`), so it adds no
+ * dependency: `modules: ["<package>/nuxt"]`.
+ */
+export default function sqlInspectorModule(_options: unknown, nuxt: NuxtLike): void;
+export {};

package/dist/nuxt.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The compiled `.js` when installed from npm, the `.ts` source when used from a checkout. */
+function resolveSibling(path) {
+    const js = fileURLToPath(new URL(`${path}.js`, import.meta.url));
+    return existsSync(js) ? js : fileURLToPath(new URL(`${path}.ts`, import.meta.url));
+}
+/**
+ * Nuxt module. In `nuxt dev` only, registers the SQL Inspector Nitro plugin (server) and the
+ * floating launcher (client), so `nuxt build` and `nuxt generate` never see them and nothing
+ * ships to a deployed environment. Written as a plain function (no `@nuxt/kit`), so it adds no
+ * dependency: `modules: ["<package>/nuxt"]`.
+ */
+export default function sqlInspectorModule(_options, nuxt) {
+    if (!nuxt.options.dev) {
+        return;
+    }
+    nuxt.options.nitro.plugins ||= [];
+    nuxt.options.nitro.plugins.push(resolveSibling("./nitro-plugin"));
+    nuxt.options.plugins.push({ src: resolveSibling("./client/nuxt-plugin.client"), mode: "client" });
+}

package/dist/report.d.ts

@@ -0,0 +1,24 @@
+import type { QueryEvent, RequestReport, RequestTrace, TraceNode } from "./types.js";
+import { type Locale } from "./i18n/index.js";
+export interface ReportOptions {
+    slowMs: number;
+    nPlusOneThreshold: number;
+    manyQueriesThreshold: number;
+    /**
+     * Opt-in team convention check: reads belong outside a transaction, and a transaction is only
+     * for writes. Off by default because it is a style rule, not a defect.
+     */
+    transactionConvention: boolean;
+    /** Language of `Insight.message`. The structured fields are language-neutral. */
+    locale: Locale;
+}
+export declare const DEFAULT_REPORT_OPTIONS: ReportOptions;
+/**
+ * Rebuilds the call structure of one request: statements run in a transaction nest under it,
+ * savepoints nest under their parent transaction, and everything else sits at the top level.
+ *
+ * Nesting is per connection. A transaction owns one connection, so two transactions running
+ * at once in the same request (Promise.all) stay apart instead of interleaving.
+ */
+export declare function buildTree(queries: QueryEvent[]): TraceNode[];
+export declare function buildReport(trace: RequestTrace, options?: ReportOptions): RequestReport;

package/dist/report.js

@@ -0,0 +1,182 @@
+import { DEFAULT_LOCALE, translate } from "./i18n/index.js";
+import { isControlStatement, isWriteStatement } from "./sql-analyzer.js";
+export const DEFAULT_REPORT_OPTIONS = {
+    slowMs: 100,
+    nPlusOneThreshold: 3,
+    manyQueriesThreshold: 30,
+    transactionConvention: false,
+    locale: DEFAULT_LOCALE
+};
+const endOf = (query) => query.startedAt + (query.durationMs ?? 0);
+/**
+ * Rebuilds the call structure of one request: statements run in a transaction nest under it,
+ * savepoints nest under their parent transaction, and everything else sits at the top level.
+ *
+ * Nesting is per connection. A transaction owns one connection, so two transactions running
+ * at once in the same request (Promise.all) stay apart instead of interleaving.
+ */
+export function buildTree(queries) {
+    const roots = [];
+    const openByConnection = new Map();
+    const place = (node, connectionId) => {
+        const stack = openByConnection.get(connectionId);
+        const parent = stack?.at(-1);
+        if (parent) {
+            parent.children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    };
+    const open = (query, type) => {
+        const node = {
+            type,
+            connectionId: query.connectionId,
+            name: query.analysis.savepoint,
+            status: "open",
+            startedAt: query.startedAt,
+            durationMs: null,
+            children: []
+        };
+        place(node, query.connectionId);
+        const stack = openByConnection.get(query.connectionId) ?? [];
+        stack.push(node);
+        openByConnection.set(query.connectionId, stack);
+    };
+    const close = (query, status, until) => {
+        const stack = openByConnection.get(query.connectionId) ?? [];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            node.status = status;
+            node.durationMs = endOf(query) - node.startedAt;
+            if (until(node)) {
+                break;
+            }
+        }
+    };
+    for (const query of [...queries].sort((a, b) => a.seq - b.seq)) {
+        switch (query.analysis.kind) {
+            case "tx-begin":
+                open(query, "transaction");
+                break;
+            case "savepoint":
+                open(query, "savepoint");
+                break;
+            case "tx-commit":
+                close(query, "committed", () => false);
+                break;
+            case "tx-rollback":
+                close(query, "rolled-back", () => false);
+                break;
+            case "savepoint-release":
+                close(query, "committed", node => node.name === query.analysis.savepoint);
+                break;
+            case "savepoint-rollback":
+                close(query, "rolled-back", node => node.name === query.analysis.savepoint);
+                break;
+            case "tx-config":
+                break;
+            default:
+                place({ type: "query", query }, query.connectionId);
+        }
+    }
+    return roots;
+}
+function* walk(nodes, insideTransaction = false) {
+    for (const node of nodes) {
+        if (node.type === "query") {
+            yield { query: node.query, insideTransaction };
+        }
+        else {
+            yield* walk(node.children, true);
+        }
+    }
+}
+function groupBy(items, keyOf) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        groups.set(key, [...(groups.get(key) ?? []), item]);
+    }
+    return groups;
+}
+const shorten = (text, max = 90) => text.length > max ? `${text.slice(0, max)}…` : text;
+const sumMs = (queries) => queries.reduce((total, q) => total + (q.durationMs ?? 0), 0);
+const formatMs = (value) => value < 1000 ? `${value.toFixed(value < 10 ? 2 : 1)}ms` : `${(value / 1000).toFixed(2)}s`;
+/** Findings as data (type + params), so any front end can phrase them in its own language. */
+function findInsights(tree, queries, options) {
+    const insights = [];
+    const statements = queries.filter(q => !isControlStatement(q.analysis.kind));
+    const flagged = new Set();
+    for (const group of groupBy(statements.filter(q => q.analysis.kind === "select"), q => q.analysis.fingerprint).values()) {
+        if (group.length < options.nPlusOneThreshold) {
+            continue;
+        }
+        const distinctSql = new Set(group.map(q => q.sql)).size;
+        // Same text repeated is plain duplication; same shape with different values is the N+1 signature.
+        const isNPlusOne = distinctSql > 1;
+        insights.push({
+            type: isNPlusOne ? "n-plus-one" : "duplicate",
+            severity: "warn",
+            params: isNPlusOne
+                ? { count: group.length, total: formatMs(sumMs(group)), sql: shorten(group[0].analysis.fingerprint) }
+                : { count: group.length, sql: shorten(group[0].sql) },
+            seqs: group.map(q => q.seq)
+        });
+        group.forEach(q => flagged.add(q.seq));
+    }
+    for (const group of groupBy(statements.filter(q => !flagged.has(q.seq)), q => q.sql).values()) {
+        if (group.length >= 2) {
+            insights.push({ type: "duplicate", severity: "warn", params: { count: group.length, sql: shorten(group[0].sql) }, seqs: group.map(q => q.seq) });
+        }
+    }
+    for (const query of statements) {
+        if (query.error) {
+            insights.push({ type: "error", severity: "error", params: { error: query.error }, seqs: [query.seq] });
+        }
+        if (query.durationMs !== null && query.durationMs >= options.slowMs) {
+            insights.push({
+                type: "slow",
+                severity: "warn",
+                params: { ms: formatMs(query.durationMs), threshold: formatMs(options.slowMs), sql: shorten(query.sql) },
+                seqs: [query.seq]
+            });
+        }
+        if (query.analysis.selectStar) {
+            insights.push({ type: "select-star", severity: "info", params: { tables: query.analysis.tables.join(", ") || "?" }, seqs: [query.seq] });
+        }
+        if (query.analysis.subqueryDepth >= 3) {
+            insights.push({ type: "deep-subquery", severity: "info", params: { depth: query.analysis.subqueryDepth }, seqs: [query.seq] });
+        }
+    }
+    const placed = [...walk(tree)];
+    const readsInside = placed.filter(p => p.insideTransaction && p.query.analysis.kind === "select");
+    if (options.transactionConvention && readsInside.length > 0) {
+        insights.push({ type: "select-in-transaction", severity: "info", params: { count: readsInside.length }, seqs: readsInside.map(p => p.query.seq) });
+    }
+    const writesOutside = placed.filter(p => !p.insideTransaction && isWriteStatement(p.query.analysis.kind));
+    if (options.transactionConvention && writesOutside.length >= 2) {
+        insights.push({ type: "write-outside-transaction", severity: "info", params: { count: writesOutside.length }, seqs: writesOutside.map(p => p.query.seq) });
+    }
+    if (statements.length >= options.manyQueriesThreshold) {
+        insights.push({ type: "many-queries", severity: "warn", params: { count: statements.length }, seqs: [] });
+    }
+    return insights;
+}
+export function buildReport(trace, options = DEFAULT_REPORT_OPTIONS) {
+    const tree = buildTree(trace.queries);
+    const statements = trace.queries.filter(q => !isControlStatement(q.analysis.kind));
+    return {
+        trace,
+        tree,
+        insights: findInsights(tree, trace.queries, options).map(insight => ({
+            ...insight,
+            message: translate(options.locale, `insight.msg.${insight.type}`, insight.params)
+        })),
+        totals: {
+            queryCount: statements.length,
+            sqlTimeMs: sumMs(statements),
+            maxSubqueryDepth: Math.max(0, ...statements.map(q => q.analysis.subqueryDepth))
+        }
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,21 @@
+import { type Locale } from "./i18n/index.js";
+import { type ReportOptions } from "./report.js";
+import { TraceStore } from "./store.js";
+export interface Inspector {
+    store: TraceStore;
+    report: ReportOptions;
+    logToTerminal: boolean;
+    /** Language of server-side text (terminal output, `Insight.message`). */
+    locale: Locale;
+    /** Set only when `SQL_INSPECTOR_LANG` was given: tells the web UI which language to start in. */
+    localeHint: Locale | null;
+}
+/**
+ * Development only. Never in production (`NODE_ENV=production` is a hard stop, even with
+ * `SQL_INSPECTOR=1`); otherwise on when `NODE_ENV=development` (what `nuxt dev`, `next dev`,
+ * `vite` and most dev scripts set) or when asked for with `SQL_INSPECTOR=1`.
+ * `SQL_INSPECTOR=0` switches it off.
+ */
+export declare function isInspectorEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** One inspector per process, however many bundles import this module. */
+export declare function getInspector(env?: NodeJS.ProcessEnv): Inspector;

package/dist/runtime.js

@@ -0,0 +1,42 @@
+import process from "node:process";
+import { chosenLocale, DEFAULT_LOCALE } from "./i18n/index.js";
+import { DEFAULT_REPORT_OPTIONS } from "./report.js";
+import { TraceStore } from "./store.js";
+const KEY = Symbol.for("sqlDevInspector.runtime");
+function positiveNumber(raw, fallback) {
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/**
+ * Development only. Never in production (`NODE_ENV=production` is a hard stop, even with
+ * `SQL_INSPECTOR=1`); otherwise on when `NODE_ENV=development` (what `nuxt dev`, `next dev`,
+ * `vite` and most dev scripts set) or when asked for with `SQL_INSPECTOR=1`.
+ * `SQL_INSPECTOR=0` switches it off.
+ */
+export function isInspectorEnabled(env = process.env) {
+    if (env.NODE_ENV === "production" || env.SQL_INSPECTOR === "0") {
+        return false;
+    }
+    return env.SQL_INSPECTOR === "1" || env.NODE_ENV === "development";
+}
+/** One inspector per process, however many bundles import this module. */
+export function getInspector(env = process.env) {
+    const holder = globalThis;
+    const hint = chosenLocale(env);
+    holder[KEY] ??= {
+        locale: hint ?? DEFAULT_LOCALE,
+        localeHint: hint,
+        store: new TraceStore({
+            maxRequests: positiveNumber(env.SQL_INSPECTOR_MAX_REQUESTS, 200),
+            maxQueriesPerRequest: positiveNumber(env.SQL_INSPECTOR_MAX_QUERIES, 1000)
+        }),
+        report: {
+            ...DEFAULT_REPORT_OPTIONS,
+            slowMs: positiveNumber(env.SQL_INSPECTOR_SLOW_MS, DEFAULT_REPORT_OPTIONS.slowMs),
+            transactionConvention: env.SQL_INSPECTOR_TX_CONVENTION === "1",
+            locale: hint ?? DEFAULT_LOCALE
+        },
+        logToTerminal: env.SQL_INSPECTOR_LOG !== "0"
+    };
+    return holder[KEY];
+}

package/dist/setup.d.ts

@@ -0,0 +1,8 @@
+import { type Inspector } from "./runtime.js";
+/**
+ * Patches mysql2 and starts the terminal printer, once per process. Returns null when the
+ * environment says no (production, opted out), in which case nothing has been touched.
+ */
+export declare function startInspector(env?: NodeJS.ProcessEnv): Inspector | null;
+/** Test helper: forget that the inspector was started, so the next start installs again. */
+export declare function resetInspectorForTests(): void;

package/dist/setup.js

@@ -0,0 +1,44 @@
+import process from "node:process";
+import { buildReport } from "./report.js";
+import { getInspector, isInspectorEnabled } from "./runtime.js";
+import { hasVisibleStatements, renderReport } from "./terminal.js";
+import { installTracer } from "./tracer.js";
+const STARTED = Symbol.for("sqlDevInspector.started");
+/**
+ * Patches mysql2 and starts the terminal printer, once per process. Returns null when the
+ * environment says no (production, opted out), in which case nothing has been touched.
+ */
+export function startInspector(env = process.env) {
+    if (!isInspectorEnabled(env)) {
+        return null;
+    }
+    const inspector = getInspector(env);
+    const holder = globalThis;
+    if (holder[STARTED]) {
+        return inspector;
+    }
+    holder[STARTED] = true;
+    const { store } = inspector;
+    installTracer(store);
+    if (inspector.logToTerminal) {
+        store.subscribe((change) => {
+            if (change.type !== "request-end") {
+                return;
+            }
+            const trace = store.get(change.requestId);
+            if (!trace) {
+                return;
+            }
+            const report = buildReport(trace, inspector.report);
+            if (hasVisibleStatements(report)) {
+                console.log(`\n${renderReport(report, inspector.locale)}`);
+            }
+        });
+    }
+    return inspector;
+}
+/** Test helper: forget that the inspector was started, so the next start installs again. */
+export function resetInspectorForTests() {
+    const holder = globalThis;
+    holder[STARTED] = false;
+}

package/dist/sql-analyzer.d.ts

@@ -0,0 +1,12 @@
+import type { SqlAnalysis, StatementKind } from "./types.js";
+/** Replace string literals and comments with placeholders; keep everything else intact. */
+export declare function maskLiterals(sql: string): string;
+export declare function fingerprintOf(sql: string): string;
+export declare function analyzeSql(sql: string): SqlAnalysis;
+export declare function isControlStatement(kind: StatementKind): kind is "tx-begin" | "tx-commit" | "tx-rollback" | "tx-config" | "savepoint" | "savepoint-release" | "savepoint-rollback";
+export declare function isWriteStatement(kind: StatementKind): kind is "insert" | "update" | "delete" | "replace";
+/**
+ * Indents by subquery depth and starts a new line at each major clause, so a nested Drizzle
+ * relational query reads as a tree. Display only — never executed.
+ */
+export declare function formatSql(sql: string): string;

package/dist/sql-analyzer.js

@@ -0,0 +1,214 @@
+/**
+ * Not a SQL parser. Drizzle only emits well-formed statements, so a tokenizer that knows
+ * about string literals, identifiers and comments is enough to classify them, find their
+ * tables and measure subquery nesting. Anything it cannot read degrades to `other` rather
+ * than throwing — a query inspector must never break the query path.
+ */
+const TOKEN = /'(?:[^'\\]|\\.|'')*'|"(?:[^"\\]|\\.|"")*"|`[^`]*`|\/\*[\s\S]*?\*\/|--[^\n]*|#[^\n]*|\w+|[\s\S]/g;
+/** Replace string literals and comments with placeholders; keep everything else intact. */
+export function maskLiterals(sql) {
+    return sql.replace(TOKEN, (token) => {
+        if (token.startsWith("'") || token.startsWith("\"")) {
+            return "?";
+        }
+        if (token.startsWith("/*") || token.startsWith("--") || token.startsWith("#")) {
+            return " ";
+        }
+        return token;
+    });
+}
+const WHITESPACE_RUN = /\s+/g;
+const BACKTICKS = /`/g;
+const PAREN_TOKEN = /\(\s*(select|with)\b|\(|\)/gi;
+const LEADING_PARENS = /^\(+/;
+const FIRST_WORD = /^(\w+)/;
+const QUOTES_AND_SEMICOLON = /[`;]/g;
+const START_TRANSACTION = /^start\s+transaction\b/;
+const ROLLBACK_TO = /^rollback\s+to\b/;
+const ROLLBACK_TO_NAME = /^rollback\s+to\s+(?:savepoint\s+)?(\S+)/;
+const SAVEPOINT_NAME = /^savepoint\s+(\S+)/;
+const RELEASE_SAVEPOINT = /^release\s+savepoint\b/;
+const RELEASE_NAME = /^release\s+savepoint\s+(\S+)/;
+const SET_TRANSACTION = /^set\s+(?:session\s+|global\s+)?transaction\b/;
+const SELECT_STAR = /\bselect\s+(?:distinct\s+)?(?:\w+\.)?\*/i;
+const SUBQUERY_KEYWORD = /^(?:select|with)$/i;
+const WORD = /^\w+$/;
+const NUMBER_LITERAL = /\b\d+(?:\.\d+)?\b/g;
+const IN_LIST = /\bin\s*\(\s*\?(?:\s*,\s*\?)*\s*\)/gi;
+const VALUES_ROWS = /\bvalues\s*\(\s*\?(?:\s*,\s*\?)*\s*\)(?:\s*,\s*\(\s*\?(?:\s*,\s*\?)*\s*\))*/gi;
+export function fingerprintOf(sql) {
+    return maskLiterals(sql)
+        .replace(NUMBER_LITERAL, "?")
+        .replace(WHITESPACE_RUN, " ")
+        .replace(IN_LIST, "in (?)")
+        .replace(VALUES_ROWS, "values (?)")
+        .trim()
+        .toLowerCase();
+}
+const TABLE_REFERENCE = /(?<!\bon\s)(?<!\bkey\s)(?<!\bfor\s)\b(from|join|into|update)\s+((?:`[^`]+`|\w+)(?:\.(?:`[^`]+`|\w+))?)/gi;
+const NOT_A_TABLE = new Set(["select", "set", "values", "lateral", "dual"]);
+function tablesOf(masked) {
+    const tables = new Set();
+    for (const match of masked.matchAll(TABLE_REFERENCE)) {
+        const name = match[2].replace(BACKTICKS, "");
+        if (!NOT_A_TABLE.has(name.toLowerCase())) {
+            tables.add(name);
+        }
+    }
+    return [...tables];
+}
+function measureSubqueries(masked) {
+    // Each open paren is remembered with whether it opens a subquery, so `IN (1, 2)` and
+    // `COUNT(*)` do not count towards the depth and `((SELECT ...))` counts once.
+    const stack = [];
+    let depth = 0;
+    let count = 0;
+    let open = 0;
+    for (const match of masked.matchAll(PAREN_TOKEN)) {
+        const token = match[0];
+        if (token === ")") {
+            if (stack.pop()) {
+                open--;
+            }
+            continue;
+        }
+        const opensSubquery = match[1] !== undefined;
+        stack.push(opensSubquery);
+        if (opensSubquery) {
+            open++;
+            count++;
+            depth = Math.max(depth, open);
+        }
+    }
+    return { depth, count };
+}
+function kindOf(masked) {
+    const text = masked.trim().replace(LEADING_PARENS, "").toLowerCase();
+    const word = FIRST_WORD.exec(text)?.[1] ?? "";
+    const clean = (name) => name?.replace(QUOTES_AND_SEMICOLON, "") ?? null;
+    if (word === "select" || word === "with") {
+        return { kind: "select", savepoint: null };
+    }
+    if (word === "insert" || word === "update" || word === "delete" || word === "replace") {
+        return { kind: word, savepoint: null };
+    }
+    if (word === "begin" || START_TRANSACTION.test(text)) {
+        return { kind: "tx-begin", savepoint: null };
+    }
+    if (word === "commit") {
+        return { kind: "tx-commit", savepoint: null };
+    }
+    if (ROLLBACK_TO.test(text)) {
+        return { kind: "savepoint-rollback", savepoint: clean(ROLLBACK_TO_NAME.exec(text)?.[1]) };
+    }
+    if (word === "rollback") {
+        return { kind: "tx-rollback", savepoint: null };
+    }
+    if (word === "savepoint") {
+        return { kind: "savepoint", savepoint: clean(SAVEPOINT_NAME.exec(text)?.[1]) };
+    }
+    if (RELEASE_SAVEPOINT.test(text)) {
+        return { kind: "savepoint-release", savepoint: clean(RELEASE_NAME.exec(text)?.[1]) };
+    }
+    if (SET_TRANSACTION.test(text)) {
+        return { kind: "tx-config", savepoint: null };
+    }
+    return { kind: "other", savepoint: null };
+}
+export function analyzeSql(sql) {
+    try {
+        const masked = maskLiterals(sql);
+        const { kind, savepoint } = kindOf(masked);
+        const subqueries = measureSubqueries(masked);
+        return {
+            kind,
+            tables: tablesOf(masked),
+            subqueryDepth: subqueries.depth,
+            subqueryCount: subqueries.count,
+            fingerprint: fingerprintOf(sql),
+            selectStar: SELECT_STAR.test(masked),
+            savepoint
+        };
+    }
+    catch {
+        return { kind: "other", tables: [], subqueryDepth: 0, subqueryCount: 0, fingerprint: sql, selectStar: false, savepoint: null };
+    }
+}
+export function isControlStatement(kind) {
+    return kind === "tx-begin" || kind === "tx-commit" || kind === "tx-rollback" || kind === "tx-config"
+        || kind === "savepoint" || kind === "savepoint-release" || kind === "savepoint-rollback";
+}
+export function isWriteStatement(kind) {
+    return kind === "insert" || kind === "update" || kind === "delete" || kind === "replace";
+}
+const BREAK_BEFORE = /^(?:select|from|where|group|order|having|limit|offset|union|set|values|left|right|inner|cross|join|for)$/i;
+const JOIN_MODIFIER = /^(?:left|right|inner|cross|full|outer|natural)$/i;
+const WHITESPACE = /^\s+$/;
+function nextSignificantToken(tokens, from) {
+    for (let i = from; i < tokens.length; i++) {
+        if (!WHITESPACE.test(tokens[i])) {
+            return tokens[i];
+        }
+    }
+    return "";
+}
+/**
+ * Indents by subquery depth and starts a new line at each major clause, so a nested Drizzle
+ * relational query reads as a tree. Display only — never executed.
+ */
+export function formatSql(sql) {
+    const out = [];
+    const subqueryParens = [];
+    let indent = 0;
+    let previousWord = "";
+    let line = "";
+    const newline = () => {
+        if (line.trim()) {
+            out.push(line.trimEnd());
+        }
+        line = "  ".repeat(indent);
+    };
+    const tokens = sql.match(TOKEN) ?? [];
+    for (const [i, token] of tokens.entries()) {
+        if (WHITESPACE.test(token)) {
+            if (line.trim() && !line.endsWith(" ")) {
+                line += " ";
+            }
+            continue;
+        }
+        if (token === "(") {
+            const opensSubquery = SUBQUERY_KEYWORD.test(nextSignificantToken(tokens, i + 1));
+            subqueryParens.push(opensSubquery);
+            line += "(";
+            if (opensSubquery) {
+                indent++;
+                newline();
+            }
+            previousWord = "";
+            continue;
+        }
+        if (token === ")") {
+            if (subqueryParens.pop()) {
+                indent = Math.max(0, indent - 1);
+                newline();
+            }
+            line += ")";
+            previousWord = "";
+            continue;
+        }
+        const word = token.toLowerCase();
+        if (WORD.test(token)) {
+            if (word === "and" || word === "or") {
+                newline();
+                line += "  ";
+            }
+            else if (BREAK_BEFORE.test(word) && !(word === "join" && JOIN_MODIFIER.test(previousWord))) {
+                newline();
+            }
+        }
+        line += token;
+        previousWord = WORD.test(token) ? word : "";
+    }
+    newline();
+    return out.join("\n");
+}