miladyai 2.0.0-alpha.27

package/dist/api/database.js

@@ -0,0 +1,735 @@
+import { loadMiladyConfig, saveMiladyConfig } from "../config/config.js";
+import { isLoopbackHost, normalizeHostLike, normalizeIpForPolicy } from "../security/network-policy.js";
+import { readJsonBody as readJsonBody$1, sendJson, sendJsonError } from "./http-helpers.js";
+import { logger } from "@elizaos/core";
+import net from "node:net";
+import { promisify } from "node:util";
+import dns from "node:dns";
+
+//#region src/api/database.ts
+/**
+* Database management API handlers for the Milady 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.
+*/
+async function readJsonBody(req, res) {
+	return readJsonBody$1(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";
+	return `postgresql://${password ? `${user}:${password}` : user}@${host}:${port}/${database}${creds.ssl ? "?sslmode=require" : ""}`;
+}
+/**
+* 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;
+		parsed.searchParams.set("host", normalizedPinned);
+		parsed.searchParams.set("hostaddr", normalizedPinned);
+		next.connectionString = parsed.toString();
+	} catch {
+		delete next.connectionString;
+	}
+	return next;
+}
+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\./,
+	/^0\./,
+	/^fe[89ab][0-9a-f]:/i
+];
+/**
+* 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\./,
+	/^10\./,
+	/^172\.(1[6-9]|2\d|3[01])\./,
+	/^192\.168\./,
+	/^::1$/,
+	/^f[cd][0-9a-f]{2}:/i
+];
+/**
+* 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.MILADY_API_BIND ?? "127.0.0.1").trim().toLowerCase();
+	if (!bind) bind = "127.0.0.1";
+	if (bind.startsWith("http://") || bind.startsWith("https://")) try {
+		bind = new URL(bind).hostname.toLowerCase();
+	} catch {}
+	const bracketedIpv6 = /^\[([^\]]+)\](?::\d+)?$/.exec(bind);
+	if (bracketedIpv6?.[1]) bind = bracketedIpv6[1];
+	else {
+		const singleColonHostPort = /^([^:]+):(\d+)$/.exec(bind);
+		if (singleColonHostPort?.[1]) bind = singleColonHostPort[1];
+	}
+	bind = bind.replace(/^\[|\]$/g, "");
+	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 = [];
+		const hostParam = url.searchParams.get("host");
+		if (hostParam) hosts.push(...hostParam.split(",").map((h) => normalizeHostLike(h)).filter(Boolean));
+		const hostAddrParam = url.searchParams.get("hostaddr");
+		if (hostAddrParam) hosts.push(...hostAddrParam.split(",").map((h) => normalizeHostLike(h)).filter(Boolean));
+		if (url.hostname) hosts.push(normalizeHostLike(url.hostname));
+		return [...new Set(hosts)];
+	} catch {
+		return [];
+	}
+	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);
+		if (isBlockedIp(literalNormalized)) return {
+			error: `Connection to "${host}" is blocked: link-local and metadata addresses are not allowed.`,
+			pinnedHost: null
+		};
+		if (net.isIP(literalNormalized)) {
+			if (!pinnedHost) pinnedHost = literalNormalized;
+			continue;
+		}
+		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 {
+			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 === void 0) 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 === void 0) 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 === void 0) return `${quoteIdent(col)} IS NULL`;
+	return `${quoteIdent(col)} = ${sqlLiteral(val)}`;
+}
+let _sqlHelper = null;
+async function getDrizzleSql() {
+	if (!_sqlHelper) _sqlHelper = (await import("drizzle-orm")).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 { rows } = await executeRawSql(runtime, `SELECT 1 FROM information_schema.tables
+     WHERE table_name = '${tableName.replace(/'/g, "''")}'
+       AND table_schema NOT IN ('pg_catalog', 'information_schema')
+       AND table_type = 'BASE TABLE'
+     LIMIT 1`);
+	return rows.length > 0;
+}
+/**
+* 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'`);
+	sendJson(res, {
+		provider,
+		connected: true,
+		serverVersion,
+		tableCount: tableResult.rows.length > 0 ? Number(tableResult.rows[0].cnt ?? 0) : 0,
+		pgliteDataDir: provider === "pglite" ? process.env.PGLITE_DATA_DIR ?? null : null,
+		postgresHost: provider === "postgres" ? process.env.POSTGRES_URL?.replace(/^postgresql:\/\/[^@]*@/, "").replace(/\/.*$/, "") ?? null : null
+	});
+}
+/**
+* GET /api/database/config
+* Returns the persisted database configuration from milady.json.
+*/
+function handleGetConfig(_req, res) {
+	const dbConfig = loadMiladyConfig().database ?? { provider: "pglite" };
+	const sanitized = { ...dbConfig };
+	if (sanitized.postgres?.password) sanitized.postgres = {
+		...sanitized.postgres,
+		password: "••••••••"
+	};
+	if (sanitized.postgres?.connectionString) sanitized.postgres = {
+		...sanitized.postgres,
+		connectionString: sanitized.postgres.connectionString.replace(/:([^@]+)@/, ":••••••••@")
+	};
+	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;
+	if (body.provider && body.provider !== "pglite" && body.provider !== "postgres") {
+		sendJsonError(res, `Invalid provider: ${String(body.provider)}. Must be "pglite" or "postgres".`);
+		return;
+	}
+	const config = loadMiladyConfig();
+	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;
+	}
+	const merged = {
+		...existingDb,
+		...body
+	};
+	if (merged.provider === "postgres" && body.postgres) merged.postgres = {
+		...existingDb.postgres,
+		...validatedPostgres ?? body.postgres
+	};
+	if (merged.provider === "pglite" && body.pglite) merged.pglite = {
+		...existingDb.pglite,
+		...body.pglite
+	};
+	config.database = merged;
+	saveMiladyConfig(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 connectionString = buildConnectionString(validation.pinnedHost ? withPinnedHost(body, validation.pinnedHost) : body);
+	const start = Date.now();
+	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: 1e4,
+		idleTimeoutMillis: 5e3
+	});
+	let client = null;
+	try {
+		client = await pool.connect();
+		const versionResult = await client.query("SELECT version()");
+		sendJson(res, {
+			success: true,
+			serverVersion: String(versionResult.rows[0]?.version ?? ""),
+			error: null,
+			durationMs: Date.now() - start
+		});
+	} catch (err) {
+		const durationMs = Date.now() - start;
+		sendJson(res, {
+			success: false,
+			serverVersion: null,
+			error: err instanceof Error ? err.message : String(err),
+			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) {
+	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`);
+	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`);
+	const columnsByTable = /* @__PURE__ */ 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);
+	}
+	sendJson(res, { 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) ?? []
+		};
+	}) });
+}
+/**
+* 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;
+	}
+	const colResult = await executeRawSql(runtime, `SELECT column_name, data_type
+     FROM information_schema.columns
+     WHERE table_name = '${tableName.replace(/'/g, "''")}'
+       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)]));
+	const validSort = sortCol && columnNames.includes(sortCol) ? sortCol : "";
+	let whereClause = "";
+	if (search.trim()) {
+		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) whereClause = `WHERE (${textColumns.map((col) => `${quoteIdent(col)}::text ILIKE '%${escapedSearch}%' ESCAPE '\\'`).join(" OR ")})`;
+	}
+	const countResult = await executeRawSql(runtime, `SELECT count(*) AS total FROM ${quoteIdent(tableName)} ${whereClause}`);
+	const total = Number(countResult.rows[0]?.total ?? 0);
+	const orderClause = validSort ? `ORDER BY ${quoteIdent(validSort)} ${sortOrder}` : "";
+	const result = await executeRawSql(runtime, `SELECT * FROM ${quoteIdent(tableName)} ${whereClause} ${orderClause} LIMIT ${limit} OFFSET ${offset}`);
+	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(", ");
+	sendJson(res, {
+		inserted: true,
+		row: (await executeRawSql(runtime, `INSERT INTO ${quoteIdent(tableName)} (${colList}) VALUES (${valList}) RETURNING *`)).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 (body.readOnly !== false) {
+		const stripped = sqlText.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--.*$/gm, "").trim();
+		const noLiterals = stripped.replace(/\$([A-Za-z0-9_]*)\$[\s\S]*?\$\1\$/g, " ").replace(/'(?:[^']|'')*'/g, " ");
+		const noStrings = noLiterals.replace(/"(?:[^"]|"")*"/g, " ");
+		const match = new RegExp(`\\b(${[
+			"INSERT",
+			"UPDATE",
+			"DELETE",
+			"INTO",
+			"DROP",
+			"ALTER",
+			"TRUNCATE",
+			"CREATE",
+			"COPY",
+			"MERGE",
+			"CALL",
+			"DO",
+			"REFRESH",
+			"REINDEX",
+			"VACUUM",
+			"GRANT",
+			"REVOKE"
+		].join("|")})\\b`, "i").exec(noStrings);
+		if (match) {
+			sendJsonError(res, `Query rejected: "${match[1].toUpperCase()}" is a mutation keyword. Set readOnly: false to execute mutations.`);
+			return;
+		}
+		const mutatingFunctionMatch = /(?:^|[^\w$])"?((?:nextval|setval))"?\s*\(/i.exec(noLiterals);
+		if (mutatingFunctionMatch) {
+			sendJsonError(res, `Query rejected: "${mutatingFunctionMatch[1].toUpperCase()}" is a mutating function. Set readOnly: false to execute mutations.`);
+			return;
+		}
+		if (stripped.replace(/;\s*$/, "").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;
+	sendJson(res, {
+		columns: result.columns,
+		rows: result.rows,
+		rowCount: result.rows.length,
+		durationMs
+	});
+}
+/**
+* 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
+*/
+async function handleDatabaseRoute(req, res, runtime, pathname) {
+	const method = req.method ?? "GET";
+	if (method === "GET" && pathname === "/api/database/status") {
+		await handleGetStatus(req, res, runtime);
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/database/config") {
+		handleGetConfig(req, res);
+		return true;
+	}
+	if (method === "PUT" && pathname === "/api/database/config") {
+		await handlePutConfig(req, res);
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/database/test") {
+		await handleTestConnection(req, res);
+		return true;
+	}
+	if (!runtime?.adapter) {
+		sendJsonError(res, "Database not available. The agent may not be running or the database adapter is not initialized.", 503);
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/database/tables") {
+		await handleGetTables(req, res, runtime);
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/database/query") {
+		await handleQuery(req, res, runtime);
+		return true;
+	}
+	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;
+}
+
+//#endregion
+export { handleDatabaseRoute };