@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/api/database.js

@@ -0,0 +1,1019 @@
+/**
+ * Database management API handlers for the Eliza Control UI.
+ *
+ * Provides endpoints for:
+ * - Database provider configuration (PGLite vs Postgres)
+ * - Connection testing for remote Postgres
+ * - Table browsing and introspection
+ * - Row-level CRUD operations
+ * - Raw SQL query execution
+ * - Database status and health
+ *
+ * All data endpoints use the active runtime's database adapter (Drizzle ORM)
+ * so they work identically for both PGLite and Postgres.
+ */
+import dns from "node:dns";
+import net from "node:net";
+import { promisify } from "node:util";
+import { logger } from "@elizaos/core";
+import { loadElizaConfig, saveElizaConfig } from "../config/config";
+import { isLoopbackHost, normalizeHostLike, normalizeIpForPolicy, } from "../security/network-policy";
+import { readJsonBody as parseJsonBody, sendJson, sendJsonError, } from "./http-helpers";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readJsonBody(req, res) {
+    return parseJsonBody(req, res, {
+        maxBytes: 2 * 1024 * 1024,
+    });
+}
+/**
+ * Safely quote a SQL identifier (table or column name).
+ * Postgres uses double-quote escaping: embedded " becomes "".
+ */
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Build a Postgres connection string from individual credential fields.
+ */
+function buildConnectionString(creds) {
+    if (creds.connectionString)
+        return creds.connectionString;
+    const host = creds.host ?? "localhost";
+    const port = creds.port ?? 5432;
+    const user = encodeURIComponent(creds.user ?? "postgres");
+    const password = creds.password ? encodeURIComponent(creds.password) : "";
+    const database = creds.database ?? "postgres";
+    const auth = password ? `${user}:${password}` : user;
+    const sslParam = creds.ssl ? "?sslmode=require" : "";
+    return `postgresql://${auth}@${host}:${port}/${database}${sslParam}`;
+}
+/**
+ * Return a copy of credentials with host pinned to a validated IP address.
+ * For connection strings, rewrites URL hostname to avoid re-resolution later.
+ */
+function withPinnedHost(creds, pinnedHost) {
+    const normalizedPinned = pinnedHost.replace(/^::ffff:/i, "");
+    const next = { ...creds, host: normalizedPinned };
+    if (next.connectionString) {
+        try {
+            const parsed = new URL(next.connectionString);
+            parsed.hostname = normalizedPinned;
+            // Preserve DNS pinning even when libpq-style query params are present.
+            // `host` / `hostaddr` can override URI hostname; force both to pinned IP.
+            parsed.searchParams.set("host", normalizedPinned);
+            parsed.searchParams.set("hostaddr", normalizedPinned);
+            next.connectionString = parsed.toString();
+        }
+        catch {
+            // Validation has already parsed this once, but if URL rewriting fails,
+            // force builder path to use the pinned host.
+            delete next.connectionString;
+        }
+    }
+    return next;
+}
+// ---------------------------------------------------------------------------
+// Host validation — prevent SSRF via database connection endpoints
+// ---------------------------------------------------------------------------
+const dnsLookupAll = promisify(dns.lookup);
+/**
+ * IP ranges that are ALWAYS blocked regardless of bind address.
+ * Cloud metadata and "this" network are never legitimate Postgres targets.
+ */
+const ALWAYS_BLOCKED_IP_PATTERNS = [
+    /^169\.254\./, // Link-local / cloud metadata (AWS, GCP, Azure)
+    /^0\./, // "This" network
+    /^fe[89ab][0-9a-f]:/i, // IPv6 link-local fe80::/10
+];
+/**
+ * Private/internal IP ranges — blocked only when the API is bound to a
+ * non-loopback address (i.e. remotely reachable).  When bound to 127.0.0.1
+ * (the default), these are allowed since local Postgres is the most common
+ * setup and an attacker who can reach the loopback API already has local
+ * network access.
+ */
+const PRIVATE_IP_PATTERNS = [
+    /^127\./, // IPv4 loopback
+    /^10\./, // RFC 1918 Class A
+    /^172\.(1[6-9]|2\d|3[01])\./, // RFC 1918 Class B
+    /^192\.168\./, // RFC 1918 Class C
+    /^::1$/, // IPv6 loopback
+    /^f[cd][0-9a-f]{2}:/i, // IPv6 ULA (fc00::/7 includes fc00::–fdff::)
+];
+/**
+ * Returns true when the API server is bound to a loopback-only address.
+ * In that case, private/internal IP ranges are allowed for DB connections
+ * since only local processes can reach the API.
+ */
+function isApiLoopbackOnly() {
+    let bind = (process.env.ELIZA_API_BIND ?? "127.0.0.1").trim().toLowerCase();
+    if (!bind)
+        bind = "127.0.0.1";
+    // Accept accidental URL-shaped bind values.
+    if (bind.startsWith("http://") || bind.startsWith("https://")) {
+        try {
+            const parsed = new URL(bind);
+            bind = parsed.hostname.toLowerCase();
+        }
+        catch {
+            // Fall through and treat as raw host value.
+        }
+    }
+    // [::1]:2138 -> ::1
+    const bracketedIpv6 = /^\[([^\]]+)\](?::\d+)?$/.exec(bind);
+    if (bracketedIpv6?.[1]) {
+        bind = bracketedIpv6[1];
+    }
+    else {
+        // localhost:2138 -> localhost, 127.0.0.1:2138 -> 127.0.0.1
+        const singleColonHostPort = /^([^:]+):(\d+)$/.exec(bind);
+        if (singleColonHostPort?.[1]) {
+            bind = singleColonHostPort[1];
+        }
+    }
+    bind = bind.replace(/^\[|\]$/g, "");
+    // Reuse the strict loopback classifier to avoid hostname prefix bypasses
+    // such as "127.evil.com" that are not literal 127.0.0.0/8 IPs.
+    return isLoopbackHost(bind);
+}
+/**
+ * Extract all potential hosts from a Postgres connection string or credentials object.
+ * Includes query params like ?host= and ?hostaddr= which Postgres clients honor.
+ * Returns empty array if no host can be determined.
+ */
+function extractHosts(creds) {
+    if (creds.connectionString) {
+        try {
+            const url = new URL(creds.connectionString);
+            const hosts = [];
+            // PostgreSQL connection strings can have ?host= param that overrides URI hostname
+            const hostParam = url.searchParams.get("host");
+            if (hostParam) {
+                hosts.push(...hostParam
+                    .split(",")
+                    .map((h) => normalizeHostLike(h))
+                    .filter(Boolean));
+            }
+            // Also check hostaddr param
+            const hostAddrParam = url.searchParams.get("hostaddr");
+            if (hostAddrParam) {
+                hosts.push(...hostAddrParam
+                    .split(",")
+                    .map((h) => normalizeHostLike(h))
+                    .filter(Boolean));
+            }
+            // Include URI hostname
+            if (url.hostname) {
+                hosts.push(normalizeHostLike(url.hostname));
+            }
+            return [...new Set(hosts)];
+        }
+        catch {
+            return []; // Unparseable — will be rejected
+        }
+    }
+    if (creds.host) {
+        const host = normalizeHostLike(creds.host);
+        return host ? [host] : [];
+    }
+    return [];
+}
+/**
+ * Check whether an IP address falls in a blocked range.
+ * When the API is remotely reachable, private ranges are also blocked.
+ */
+function isBlockedIp(ip) {
+    const normalized = normalizeIpForPolicy(ip);
+    if (ALWAYS_BLOCKED_IP_PATTERNS.some((p) => p.test(normalized)))
+        return true;
+    if (!isApiLoopbackOnly() &&
+        PRIVATE_IP_PATTERNS.some((p) => p.test(normalized)))
+        return true;
+    return false;
+}
+/**
+ * Validate that all target hosts do not resolve to blocked addresses.
+ *
+ * Performs DNS resolution to catch hostnames like `metadata.google.internal`
+ * or `169.254.169.254.nip.io` that resolve to link-local / cloud metadata
+ * IPs.  Also handles IPv6-mapped IPv4 addresses (e.g. `::ffff:169.254.x.y`).
+ *
+ * Returns a validation result including a pinned host IP when successful.
+ */
+async function validateDbHost(creds, opts = {}) {
+    const hosts = extractHosts(creds);
+    if (hosts.length === 0) {
+        return {
+            error: "Could not determine target host from the provided credentials.",
+            pinnedHost: null,
+        };
+    }
+    let pinnedHost = null;
+    for (const host of hosts) {
+        const literalNormalized = normalizeIpForPolicy(host);
+        // First check the literal host string (catches raw IPs without DNS lookup)
+        if (isBlockedIp(literalNormalized)) {
+            return {
+                error: `Connection to "${host}" is blocked: link-local and metadata addresses are not allowed.`,
+                pinnedHost: null,
+            };
+        }
+        // Literal IPs are already pinned and do not require DNS.
+        if (net.isIP(literalNormalized)) {
+            if (!pinnedHost)
+                pinnedHost = literalNormalized;
+            continue;
+        }
+        // Resolve DNS and check all resulting IPs
+        try {
+            const results = await dnsLookupAll(host, { all: true });
+            const addresses = Array.isArray(results) ? results : [results];
+            for (const entry of addresses) {
+                const ip = typeof entry === "string"
+                    ? entry
+                    : entry.address;
+                const normalized = normalizeIpForPolicy(ip);
+                if (isBlockedIp(normalized)) {
+                    return {
+                        error: `Connection to "${host}" is blocked: it resolves to ${ip} ` +
+                            `which is a link-local or metadata address.`,
+                        pinnedHost: null,
+                    };
+                }
+                if (!pinnedHost)
+                    pinnedHost = normalized;
+            }
+        }
+        catch {
+            // For "save config" flows we allow unresolved hostnames so users can
+            // persist remote endpoints that are only resolvable from their runtime
+            // network. For "test connection" flows we keep strict DNS requirements.
+            if (!opts.allowUnresolvedHostnames) {
+                return {
+                    error: `Connection to "${host}" failed DNS resolution during validation. ` +
+                        "Use a resolvable hostname or a literal IP address.",
+                    pinnedHost: null,
+                };
+            }
+        }
+    }
+    if (!pinnedHost) {
+        if (opts.allowUnresolvedHostnames) {
+            return { error: null, pinnedHost: null };
+        }
+        return {
+            error: "Could not validate any host to a concrete IP address.",
+            pinnedHost: null,
+        };
+    }
+    return { error: null, pinnedHost };
+}
+/** Convert a JS value to a SQL literal for use in raw queries. */
+function sqlLiteral(v) {
+    if (v === null || v === undefined)
+        return "NULL";
+    if (typeof v === "number")
+        return String(v);
+    if (typeof v === "boolean")
+        return v ? "TRUE" : "FALSE";
+    if (typeof v === "object")
+        return `'${JSON.stringify(v).replace(/'/g, "''")}'::jsonb`;
+    return `'${String(v).replace(/'/g, "''")}'`;
+}
+/** Build a "col = val" SQL assignment clause. */
+function sqlAssign(col, val) {
+    if (val === null || val === undefined)
+        return `${quoteIdent(col)} = NULL`;
+    return `${quoteIdent(col)} = ${sqlLiteral(val)}`;
+}
+/** Build a "col = val" or "col IS NULL" SQL WHERE predicate. */
+function sqlPredicate(col, val) {
+    if (val === null || val === undefined)
+        return `${quoteIdent(col)} IS NULL`;
+    return `${quoteIdent(col)} = ${sqlLiteral(val)}`;
+}
+// Cached drizzle-orm sql helper; resolved once on first call.
+let _sqlHelper = null;
+async function getDrizzleSql() {
+    if (!_sqlHelper) {
+        const drizzle = await import("drizzle-orm");
+        _sqlHelper = drizzle.sql;
+    }
+    return _sqlHelper;
+}
+/** Execute raw SQL via the runtime's Drizzle adapter. */
+async function executeRawSql(runtime, sqlText) {
+    const drizzleSql = await getDrizzleSql();
+    const db = runtime.adapter.db;
+    const rawQuery = drizzleSql?.raw(sqlText);
+    if (!rawQuery)
+        throw new Error("SQL module not available");
+    const result = await db.execute(rawQuery);
+    const rows = Array.isArray(result.rows)
+        ? result.rows
+        : result;
+    let columns = [];
+    if (result.fields && Array.isArray(result.fields)) {
+        columns = result.fields.map((f) => f.name);
+    }
+    else if (rows.length > 0) {
+        columns = Object.keys(rows[0]);
+    }
+    return { rows, columns };
+}
+/**
+ * Detect the current database provider from environment / runtime state.
+ */
+function detectCurrentProvider() {
+    return process.env.POSTGRES_URL ? "postgres" : "pglite";
+}
+/** Verify a table name refers to a real user table. */
+async function assertTableExists(runtime, tableName) {
+    const safe = tableName.replace(/'/g, "''");
+    const { rows } = await executeRawSql(runtime, `SELECT 1 FROM information_schema.tables
+     WHERE table_name = '${safe}'
+       AND table_schema NOT IN ('pg_catalog', 'information_schema')
+       AND table_type = 'BASE TABLE'
+     LIMIT 1`);
+    return rows.length > 0;
+}
+// ---------------------------------------------------------------------------
+// Route handlers
+// ---------------------------------------------------------------------------
+/**
+ * GET /api/database/status
+ * Returns current connection status, provider, table count, version.
+ */
+async function handleGetStatus(_req, res, runtime) {
+    const provider = detectCurrentProvider();
+    if (!runtime?.adapter) {
+        sendJson(res, {
+            provider,
+            connected: false,
+            serverVersion: null,
+            tableCount: 0,
+            pgliteDataDir: process.env.PGLITE_DATA_DIR ?? null,
+            postgresHost: null,
+        });
+        return;
+    }
+    const { rows } = await executeRawSql(runtime, "SELECT version()");
+    const serverVersion = rows.length > 0
+        ? String(rows[0].version ?? "")
+        : null;
+    const tableResult = await executeRawSql(runtime, `SELECT count(*) AS cnt
+       FROM information_schema.tables
+      WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+        AND table_type = 'BASE TABLE'`);
+    const tableCount = tableResult.rows.length > 0
+        ? Number(tableResult.rows[0].cnt ?? 0)
+        : 0;
+    const status = {
+        provider,
+        connected: true,
+        serverVersion,
+        tableCount,
+        pgliteDataDir: provider === "pglite" ? (process.env.PGLITE_DATA_DIR ?? null) : null,
+        postgresHost: provider === "postgres"
+            ? (process.env.POSTGRES_URL?.replace(/^postgresql:\/\/[^@]*@/, "").replace(/\/.*$/, "") ?? null)
+            : null,
+    };
+    sendJson(res, status);
+}
+/**
+ * GET /api/database/config
+ * Returns the persisted database configuration from eliza.json.
+ */
+function handleGetConfig(_req, res) {
+    const config = loadElizaConfig();
+    const dbConfig = config.database ?? { provider: "pglite" };
+    // Mask the password in the response
+    const sanitized = { ...dbConfig };
+    if (sanitized.postgres?.password) {
+        sanitized.postgres = {
+            ...sanitized.postgres,
+            password: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
+        };
+    }
+    if (sanitized.postgres?.connectionString) {
+        // Mask password in connection string
+        sanitized.postgres = {
+            ...sanitized.postgres,
+            connectionString: sanitized.postgres.connectionString.replace(/:([^@]+)@/, ":\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022@"),
+        };
+    }
+    sendJson(res, {
+        config: sanitized,
+        activeProvider: detectCurrentProvider(),
+        needsRestart: (dbConfig.provider ?? "pglite") !== detectCurrentProvider(),
+    });
+}
+/**
+ * PUT /api/database/config
+ * Saves new database configuration. Does NOT restart the agent automatically;
+ * the UI prompts the user to restart.
+ */
+async function handlePutConfig(req, res) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    // Validate
+    if (body.provider &&
+        body.provider !== "pglite" &&
+        body.provider !== "postgres") {
+        sendJsonError(res, `Invalid provider: ${String(body.provider)}. Must be "pglite" or "postgres".`);
+        return;
+    }
+    // Load current config so validation can account for unchanged provider.
+    const config = loadElizaConfig();
+    const existingDb = config.database ?? {};
+    const effectiveProvider = body.provider ?? existingDb.provider ?? "pglite";
+    let validatedPostgres = null;
+    if (body.postgres) {
+        const pg = body.postgres;
+        if (effectiveProvider === "postgres" && !pg.connectionString && !pg.host) {
+            sendJsonError(res, "Postgres configuration requires either a connectionString or at least a host.");
+            return;
+        }
+        const validation = await validateDbHost(pg, {
+            allowUnresolvedHostnames: Boolean(pg.connectionString),
+        });
+        if (validation.error) {
+            sendJsonError(res, validation.error);
+            return;
+        }
+        validatedPostgres = validation.pinnedHost
+            ? withPinnedHost(pg, validation.pinnedHost)
+            : pg;
+    }
+    // Merge: keep existing postgres/pglite sub-configs unless explicitly provided
+    const merged = {
+        ...existingDb,
+        ...body,
+    };
+    // If switching to postgres, ensure postgres config is present
+    if (merged.provider === "postgres" && body.postgres) {
+        merged.postgres = {
+            ...existingDb.postgres,
+            ...(validatedPostgres ?? body.postgres),
+        };
+    }
+    // If switching to pglite, ensure pglite config is present
+    if (merged.provider === "pglite" && body.pglite) {
+        merged.pglite = { ...existingDb.pglite, ...body.pglite };
+    }
+    config.database = merged;
+    saveElizaConfig(config);
+    logger.info({ src: "database-api", provider: merged.provider }, "Database configuration saved");
+    sendJson(res, {
+        saved: true,
+        config: merged,
+        needsRestart: (merged.provider ?? "pglite") !== detectCurrentProvider(),
+    });
+}
+/**
+ * POST /api/database/test
+ * Tests a Postgres connection without persisting anything.
+ * Body: { connectionString?, host?, port?, user?, password?, database?, ssl? }
+ */
+async function handleTestConnection(req, res) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    const validation = await validateDbHost(body);
+    if (validation.error) {
+        sendJsonError(res, validation.error);
+        return;
+    }
+    const pinnedCreds = validation.pinnedHost
+        ? withPinnedHost(body, validation.pinnedHost)
+        : body;
+    const connectionString = buildConnectionString(pinnedCreds);
+    const start = Date.now();
+    // Dynamically import pg to avoid hard-coupling (it is a peer dep via plugin-sql)
+    let Pool;
+    try {
+        const pgModule = await import("pg");
+        Pool = pgModule.default?.Pool ?? pgModule.Pool;
+    }
+    catch {
+        sendJson(res, {
+            success: false,
+            serverVersion: null,
+            error: "PostgreSQL client library (pg) is not available. Ensure @elizaos/plugin-sql is installed.",
+            durationMs: Date.now() - start,
+        });
+        return;
+    }
+    const pool = new Pool({
+        connectionString,
+        max: 1,
+        connectionTimeoutMillis: 10000,
+        idleTimeoutMillis: 5000,
+    });
+    let client = null;
+    try {
+        client = await pool.connect();
+        const versionResult = await client.query("SELECT version()");
+        const serverVersion = String(versionResult.rows[0]?.version ?? "");
+        const durationMs = Date.now() - start;
+        sendJson(res, {
+            success: true,
+            serverVersion,
+            error: null,
+            durationMs,
+        });
+    }
+    catch (err) {
+        const durationMs = Date.now() - start;
+        const message = err instanceof Error ? err.message : String(err);
+        sendJson(res, {
+            success: false,
+            serverVersion: null,
+            error: message,
+            durationMs,
+        });
+    }
+    finally {
+        if (client)
+            client.release();
+        await pool.end();
+    }
+}
+/**
+ * GET /api/database/tables
+ * Lists all user tables with column metadata and approximate row counts.
+ */
+async function handleGetTables(_req, res, runtime) {
+    // Get all user tables
+    const tablesResult = await executeRawSql(runtime, `SELECT
+       t.table_schema AS schema,
+       t.table_name AS name,
+       COALESCE(s.n_live_tup, 0) AS row_count
+     FROM information_schema.tables t
+     LEFT JOIN pg_stat_user_tables s
+       ON s.schemaname = t.table_schema
+       AND s.relname = t.table_name
+     WHERE t.table_schema NOT IN ('pg_catalog', 'information_schema')
+       AND t.table_type = 'BASE TABLE'
+     ORDER BY t.table_schema, t.table_name`);
+    // Get columns for all tables in one query
+    const columnsResult = await executeRawSql(runtime, `SELECT
+       c.table_schema AS schema,
+       c.table_name AS table_name,
+       c.column_name AS name,
+       c.data_type AS type,
+       (c.is_nullable = 'YES') AS nullable,
+       c.column_default AS default_value,
+       COALESCE(
+         (SELECT true
+          FROM information_schema.table_constraints tc
+          JOIN information_schema.key_column_usage kcu
+            ON tc.constraint_name = kcu.constraint_name
+           AND tc.table_schema = kcu.table_schema
+          WHERE tc.constraint_type = 'PRIMARY KEY'
+            AND tc.table_schema = c.table_schema
+            AND tc.table_name = c.table_name
+            AND kcu.column_name = c.column_name),
+         false
+       ) AS is_primary_key
+     FROM information_schema.columns c
+     WHERE c.table_schema NOT IN ('pg_catalog', 'information_schema')
+     ORDER BY c.table_schema, c.table_name, c.ordinal_position`);
+    // Group columns by table
+    const columnsByTable = new Map();
+    for (const row of columnsResult.rows) {
+        const key = `${String(row.schema)}.${String(row.table_name)}`;
+        const cols = columnsByTable.get(key) ?? [];
+        cols.push({
+            name: String(row.name),
+            type: String(row.type),
+            nullable: Boolean(row.nullable),
+            defaultValue: row.default_value != null ? String(row.default_value) : null,
+            isPrimaryKey: Boolean(row.is_primary_key),
+        });
+        columnsByTable.set(key, cols);
+    }
+    const tables = tablesResult.rows.map((row) => {
+        const key = `${String(row.schema)}.${String(row.name)}`;
+        return {
+            name: String(row.name),
+            schema: String(row.schema),
+            rowCount: Number(row.row_count ?? 0),
+            columns: columnsByTable.get(key) ?? [],
+        };
+    });
+    sendJson(res, { tables });
+}
+/**
+ * GET /api/database/tables/:table/rows?offset=0&limit=50&sort=col&order=asc&search=term
+ * Paginated row retrieval for a specific table.
+ */
+async function handleGetRows(req, res, runtime, tableName) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const offset = Math.max(0, Number(url.searchParams.get("offset") ?? "0"));
+    const limit = Math.min(500, Math.max(1, Number(url.searchParams.get("limit") ?? "50")));
+    const sortCol = url.searchParams.get("sort") ?? "";
+    const sortOrder = url.searchParams.get("order") === "desc" ? "DESC" : "ASC";
+    const search = url.searchParams.get("search") ?? "";
+    if (!(await assertTableExists(runtime, tableName))) {
+        sendJsonError(res, `Table "${tableName}" not found`, 404);
+        return;
+    }
+    // Get column names for this table (for search and sort validation)
+    const safeTableName = tableName.replace(/'/g, "''");
+    const colResult = await executeRawSql(runtime, `SELECT column_name, data_type
+     FROM information_schema.columns
+     WHERE table_name = '${safeTableName}'
+       AND table_schema NOT IN ('pg_catalog', 'information_schema')
+     ORDER BY ordinal_position`);
+    const columnNames = colResult.rows.map((r) => String(r.column_name));
+    const columnTypes = new Map(colResult.rows.map((r) => [String(r.column_name), String(r.data_type)]));
+    // Validate sort column
+    const validSort = sortCol && columnNames.includes(sortCol) ? sortCol : "";
+    // Build search clause: search across all text-castable columns
+    let whereClause = "";
+    if (search.trim()) {
+        // Escape ILIKE special characters: backslash first (since it becomes
+        // the escape character), then the ILIKE wildcards % and _.
+        const escapedSearch = search
+            .replace(/'/g, "''")
+            .replace(/\\/g, "\\\\")
+            .replace(/%/g, "\\%")
+            .replace(/_/g, "\\_");
+        const textColumns = columnNames.filter((col) => {
+            const t = columnTypes.get(col) ?? "";
+            return (t.includes("char") ||
+                t.includes("text") ||
+                t === "uuid" ||
+                t === "jsonb" ||
+                t === "json" ||
+                t === "integer" ||
+                t === "bigint" ||
+                t === "numeric" ||
+                t === "timestamp" ||
+                t.includes("timestamp"));
+        });
+        if (textColumns.length > 0) {
+            const conditions = textColumns.map((col) => `${quoteIdent(col)}::text ILIKE '%${escapedSearch}%' ESCAPE '\\'`);
+            whereClause = `WHERE (${conditions.join(" OR ")})`;
+        }
+    }
+    // Count total (with search filter)
+    const countResult = await executeRawSql(runtime, `SELECT count(*) AS total FROM ${quoteIdent(tableName)} ${whereClause}`);
+    const total = Number(countResult.rows[0]?.total ?? 0);
+    // Fetch rows
+    const orderClause = validSort
+        ? `ORDER BY ${quoteIdent(validSort)} ${sortOrder}`
+        : "";
+    const query = `SELECT * FROM ${quoteIdent(tableName)} ${whereClause} ${orderClause} LIMIT ${limit} OFFSET ${offset}`;
+    const result = await executeRawSql(runtime, query);
+    sendJson(res, {
+        table: tableName,
+        rows: result.rows,
+        columns: result.columns,
+        total,
+        offset,
+        limit,
+    });
+}
+/**
+ * POST /api/database/tables/:table/rows
+ * Insert a new row. Body: { data: Record<string, unknown> }
+ */
+async function handleInsertRow(req, res, runtime, tableName) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    if (!body.data ||
+        typeof body.data !== "object" ||
+        Object.keys(body.data).length === 0) {
+        sendJsonError(res, "Request body must include a non-empty 'data' object.");
+        return;
+    }
+    if (!(await assertTableExists(runtime, tableName))) {
+        sendJsonError(res, `Table "${tableName}" not found`, 404);
+        return;
+    }
+    const columns = Object.keys(body.data);
+    const values = Object.values(body.data);
+    const colList = columns.map((c) => quoteIdent(c)).join(", ");
+    const valList = values.map(sqlLiteral).join(", ");
+    const result = await executeRawSql(runtime, `INSERT INTO ${quoteIdent(tableName)} (${colList}) VALUES (${valList}) RETURNING *`);
+    sendJson(res, { inserted: true, row: result.rows[0] ?? null }, 201);
+}
+/**
+ * PUT /api/database/tables/:table/rows
+ * Update a row. Body: { where: Record<string, unknown>, data: Record<string, unknown> }
+ */
+async function handleUpdateRow(req, res, runtime, tableName) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    if (!body.where || Object.keys(body.where).length === 0) {
+        sendJsonError(res, "Request body must include a non-empty 'where' object for row identification.");
+        return;
+    }
+    if (!body.data || Object.keys(body.data).length === 0) {
+        sendJsonError(res, "Request body must include a non-empty 'data' object with fields to update.");
+        return;
+    }
+    const setClauses = Object.entries(body.data).map(([col, val]) => sqlAssign(col, val));
+    const whereClauses = Object.entries(body.where).map(([col, val]) => sqlPredicate(col, val));
+    const result = await executeRawSql(runtime, `UPDATE ${quoteIdent(tableName)}
+        SET ${setClauses.join(", ")}
+      WHERE ${whereClauses.join(" AND ")}
+      RETURNING *`);
+    if (result.rows.length === 0) {
+        sendJsonError(res, "No matching row found to update.", 404);
+        return;
+    }
+    sendJson(res, { updated: true, row: result.rows[0] });
+}
+/**
+ * DELETE /api/database/tables/:table/rows
+ * Delete a row. Body: { where: Record<string, unknown> }
+ */
+async function handleDeleteRow(req, res, runtime, tableName) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    if (!body.where || Object.keys(body.where).length === 0) {
+        sendJsonError(res, "Request body must include a non-empty 'where' object for row identification.");
+        return;
+    }
+    const whereClauses = Object.entries(body.where).map(([col, val]) => sqlPredicate(col, val));
+    const result = await executeRawSql(runtime, `DELETE FROM ${quoteIdent(tableName)}
+      WHERE ${whereClauses.join(" AND ")}
+      RETURNING *`);
+    if (result.rows.length === 0) {
+        sendJsonError(res, "No matching row found to delete.", 404);
+        return;
+    }
+    sendJson(res, { deleted: true, row: result.rows[0] });
+}
+/**
+ * POST /api/database/query
+ * Execute a raw SQL query. Body: { sql: string, readOnly?: boolean }
+ */
+async function handleQuery(req, res, runtime) {
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    if (!body.sql ||
+        typeof body.sql !== "string" ||
+        body.sql.trim().length === 0) {
+        sendJsonError(res, "Request body must include a non-empty 'sql' string.");
+        return;
+    }
+    const sqlText = body.sql.trim();
+    // If readOnly mode, reject mutation statements.
+    // Strip SQL comments, then scan for mutation keywords *anywhere* in the
+    // query — not just the leading keyword. This prevents bypass via CTEs
+    // (WITH ... AS (DELETE ...)) and other SQL constructs that nest mutations.
+    if (body.readOnly !== false) {
+        // Strip block comments (/* ... */) and line comments (-- ...).
+        // Use empty-string replacement (not space) to mirror how PostgreSQL
+        // concatenates tokens across comments — e.g. DE/* */LETE → DELETE.
+        // A space replacement would turn it into "DE LETE", hiding the keyword.
+        const stripped = sqlText
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+            .replace(/--.*$/gm, "")
+            .trim();
+        // Strip string literals so that mutation keywords/functions inside quoted
+        // strings are ignored. Handles single-quoted ('...'), dollar-quoted
+        // ($$...$$), and tagged dollar-quoted ($tag$...$tag$) strings.
+        const noLiterals = stripped
+            .replace(/\$([A-Za-z0-9_]*)\$[\s\S]*?\$\1\$/g, " ")
+            .replace(/'(?:[^']|'')*'/g, " ");
+        // For keyword checks, also strip double-quoted identifiers to avoid
+        // matching words inside quoted table/column names.
+        const noStrings = noLiterals.replace(/"(?:[^"]|"")*"/g, " ");
+        const mutationKeywords = [
+            // ── DML ────────────────────────────────────────────────────────────
+            "INSERT",
+            "UPDATE",
+            "DELETE",
+            "INTO",
+            "COPY",
+            "MERGE",
+            // ── DDL ────────────────────────────────────────────────────────────
+            "DROP",
+            "ALTER",
+            "TRUNCATE",
+            "CREATE",
+            "COMMENT",
+            // ── Admin / privilege ──────────────────────────────────────────────
+            "GRANT",
+            "REVOKE",
+            "SET",
+            "RESET",
+            "LOAD",
+            // ── Maintenance ────────────────────────────────────────────────────
+            "VACUUM",
+            "REINDEX",
+            "CLUSTER",
+            "REFRESH",
+            "DISCARD",
+            // ── Procedural ─────────────────────────────────────────────────────
+            "CALL",
+            "DO",
+            // ── Async notifications (side-effects) ─────────────────────────────
+            "LISTEN",
+            "UNLISTEN",
+            "NOTIFY",
+            // ── Prepared statements (can wrap mutations) ───────────────────────
+            "PREPARE",
+            "EXECUTE",
+            "DEALLOCATE",
+            // ── Locking ────────────────────────────────────────────────────────
+            "LOCK",
+        ];
+        // Match mutation keywords as whole words (word boundary) anywhere in the
+        // query, catching them inside CTEs, subqueries, etc.
+        const mutationPattern = new RegExp(`\\b(${mutationKeywords.join("|")})\\b`, "i");
+        const match = mutationPattern.exec(noStrings);
+        if (match) {
+            sendJsonError(res, `Query rejected: "${match[1].toUpperCase()}" is a mutation keyword. Set readOnly: false to execute mutations.`);
+            return;
+        }
+        // PostgreSQL built-in functions that can read/write server files, mutate
+        // server state, or cause denial of service.  These appear inside otherwise
+        // valid SELECT expressions, so keyword checks alone won't catch them.
+        //
+        // ── File I/O (arbitrary file read/write on the DB server) ─────────
+        //   lo_import('/etc/passwd')        — load file into large object
+        //   lo_export(oid, '/tmp/evil')     — write large object to file
+        //   lo_unlink(oid)                  — delete large object
+        //   pg_read_file('/etc/passwd')     — read server file (superuser)
+        //   pg_read_binary_file(...)        — same, binary
+        //   pg_write_file(...)              — write to server files (ext. module)
+        //   pg_stat_file(...)               — stat a server file
+        //   pg_ls_dir(...)                  — list server directory
+        //
+        // ── Sequence / state mutation ────────────────────────────────────
+        //   nextval('seq'), setval('seq', n)
+        //
+        // ── Denial of service ────────────────────────────────────────────
+        //   pg_sleep(n)                     — block connection for n seconds
+        //   pg_sleep_for(interval)          — same, interval version
+        //   pg_sleep_until(timestamp)       — same, deadline version
+        //
+        // ── Session / backend control ────────────────────────────────────
+        //   pg_terminate_backend(pid)       — kill another connection
+        //   pg_cancel_backend(pid)          — cancel a running query
+        //   pg_reload_conf()                — reload server configuration
+        //   pg_rotate_logfile()             — rotate the server log
+        //   set_config(name, value, local)  — SET equivalent as function
+        //
+        // ── Advisory locks (can deadlock other connections) ───────────────
+        //   pg_advisory_lock(key)           — session-level advisory lock
+        //   pg_advisory_lock_shared(key)
+        //   pg_try_advisory_lock(key)
+        const dangerousFunctions = [
+            // File I/O
+            "lo_import",
+            "lo_export",
+            "lo_unlink",
+            "lo_put",
+            "lo_from_bytea",
+            "pg_read_file",
+            "pg_read_binary_file",
+            "pg_write_file",
+            "pg_stat_file",
+            "pg_ls_dir",
+            "pg_ls_logdir",
+            "pg_ls_waldir",
+            "pg_ls_tmpdir",
+            "pg_ls_archive_statusdir",
+            // Sequence / state mutation
+            "nextval",
+            "setval",
+            // Denial of service
+            "pg_sleep",
+            "pg_sleep_for",
+            "pg_sleep_until",
+            // Session / backend control
+            "pg_terminate_backend",
+            "pg_cancel_backend",
+            "pg_reload_conf",
+            "pg_rotate_logfile",
+            "set_config",
+            // Advisory locks
+            "pg_advisory_lock",
+            "pg_advisory_lock_shared",
+            "pg_try_advisory_lock",
+            "pg_try_advisory_lock_shared",
+            "pg_advisory_xact_lock",
+            "pg_advisory_xact_lock_shared",
+            "pg_advisory_unlock",
+            "pg_advisory_unlock_shared",
+            "pg_advisory_unlock_all",
+        ];
+        const dangerousFnPattern = new RegExp(`(?:^|[^\\w$])"?(?:${dangerousFunctions.join("|")})"?\\s*\\(`, "i");
+        const fnMatch = dangerousFnPattern.exec(noLiterals);
+        if (fnMatch) {
+            // Extract the function name from the match for the error message.
+            const fnNameMatch = fnMatch[0].match(new RegExp(`(${dangerousFunctions.join("|")})`, "i"));
+            const fnName = fnNameMatch ? fnNameMatch[1].toUpperCase() : "UNKNOWN";
+            sendJsonError(res, `Query rejected: "${fnName}" is a dangerous function that can modify server state. Set readOnly: false to execute this query.`);
+            return;
+        }
+        // Reject multi-statement queries (naive: any semicolon not at the very end)
+        const trimmedForSemicolon = stripped.replace(/;\s*$/, "");
+        if (trimmedForSemicolon.includes(";")) {
+            sendJsonError(res, "Query rejected: multi-statement queries are not allowed in read-only mode.");
+            return;
+        }
+    }
+    const start = Date.now();
+    const result = await executeRawSql(runtime, sqlText);
+    const durationMs = Date.now() - start;
+    const queryResult = {
+        columns: result.columns,
+        rows: result.rows,
+        rowCount: result.rows.length,
+        durationMs,
+    };
+    sendJson(res, queryResult);
+}
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+/**
+ * Route a database API request. Returns true if handled, false if not matched.
+ *
+ * Expected URL patterns:
+ *   GET    /api/database/status
+ *   GET    /api/database/config
+ *   PUT    /api/database/config
+ *   POST   /api/database/test
+ *   GET    /api/database/tables
+ *   GET    /api/database/tables/:table/rows
+ *   POST   /api/database/tables/:table/rows
+ *   PUT    /api/database/tables/:table/rows
+ *   DELETE /api/database/tables/:table/rows
+ *   POST   /api/database/query
+ */
+export async function handleDatabaseRoute(req, res, runtime, pathname) {
+    const method = req.method ?? "GET";
+    // ── GET /api/database/status ──────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/database/status") {
+        await handleGetStatus(req, res, runtime);
+        return true;
+    }
+    // ── GET /api/database/config ──────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/database/config") {
+        handleGetConfig(req, res);
+        return true;
+    }
+    // ── PUT /api/database/config ──────────────────────────────────────────
+    if (method === "PUT" && pathname === "/api/database/config") {
+        await handlePutConfig(req, res);
+        return true;
+    }
+    // ── POST /api/database/test ───────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/database/test") {
+        await handleTestConnection(req, res);
+        return true;
+    }
+    // Routes below require a live runtime with a database adapter
+    if (!runtime?.adapter) {
+        sendJsonError(res, "Database not available. The agent may not be running or the database adapter is not initialized.", 503);
+        return true;
+    }
+    // ── GET /api/database/tables ──────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/database/tables") {
+        await handleGetTables(req, res, runtime);
+        return true;
+    }
+    // ── POST /api/database/query ──────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/database/query") {
+        await handleQuery(req, res, runtime);
+        return true;
+    }
+    // ── Table row operations: /api/database/tables/:table/rows ────────────
+    const rowsMatch = pathname.match(/^\/api\/database\/tables\/([^/]+)\/rows$/);
+    if (rowsMatch) {
+        const tableNameDecoded = decodeURIComponent(rowsMatch[1]);
+        if (method === "GET") {
+            await handleGetRows(req, res, runtime, tableNameDecoded);
+            return true;
+        }
+        if (method === "POST") {
+            await handleInsertRow(req, res, runtime, tableNameDecoded);
+            return true;
+        }
+        if (method === "PUT") {
+            await handleUpdateRow(req, res, runtime, tableNameDecoded);
+            return true;
+        }
+        if (method === "DELETE") {
+            await handleDeleteRow(req, res, runtime, tableNameDecoded);
+            return true;
+        }
+    }
+    return false;
+}