@elyracode/db-tools 0.3.1

package/README.md

@@ -0,0 +1,62 @@
+# @elyracode/db-tools
+
+Database tools for Elyra -- query MySQL and ClickHouse with schema awareness and safety guardrails.
+
+## Install
+
+```
+elyra install npm:@elyracode/db-tools
+```
+
+## Configuration
+
+Set environment variables for your database connections:
+
+### MySQL
+
+```
+export ELYRA_MYSQL_HOST=localhost
+export ELYRA_MYSQL_PORT=3306
+export ELYRA_MYSQL_USER=readonly_user
+export ELYRA_MYSQL_PASSWORD=secret
+export ELYRA_MYSQL_DATABASE=myapp
+```
+
+### ClickHouse
+```
+export ELYRA_CLICKHOUSE_HOST=localhost
+export ELYRA_CLICKHOUSE_PORT=8123
+export ELYRA_CLICKHOUSE_DATABASE=mydb
+export ELYRA_CLICKHOUSE_USERNAME=default
+export ELYRA_CLICKHOUSE_PASSWORD=secret
+export ELYRA_CLICKHOUSE_HTTPS=false
+export ELYRA_CLICKHOUSE_TIMEOUT_CONNECT=10000
+export ELYRA_CLICKHOUSE_TIMEOUT_QUERY=30000
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `query_mysql` | Execute SQL against MySQL. Results returned as JSON. |
+| `query_clickhouse` | Execute SQL against ClickHouse. Optimized for analytical queries on large datasets. |
+| `get_database_schema` | Discover tables, columns, types, and indexes. The agent calls this before writing queries. |
+
+## Security
+
+- **Read-only by default**: Only SELECT, SHOW, DESCRIBE, and EXPLAIN queries are allowed.
+- **Write access**: Set `ELYRA_DB_ALLOW_WRITES=true` to enable INSERT, UPDATE, DELETE.
+- **Recommendation**: Use a database user with minimal privileges (SELECT only).
+
+## Usage
+
+Once installed, just ask Elyra about your data:
+
+```
+> How many users registered this week?
+> Show me the top 10 products by revenue
+> What's the average response time from the logs table?
+> Describe the schema of the orders table
+```
+
+The agent will automatically use `get_database_schema` to understand your database structure, then write and execute the appropriate SQL.

package/extensions/index.ts

@@ -0,0 +1,412 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { createClient } from "@clickhouse/client";
+import mysql2 from "mysql2/promise";
+import { Type } from "typebox";
+
+export default function (elyra: ExtensionAPI) {
+	// ── Configuration ──
+	// Connection details come from environment variables.
+	// MySQL: ELYRA_MYSQL_HOST, ELYRA_MYSQL_PORT, ELYRA_MYSQL_USER, ELYRA_MYSQL_PASSWORD, ELYRA_MYSQL_DATABASE
+	// ClickHouse: ELYRA_CLICKHOUSE_HOST, ELYRA_CLICKHOUSE_PORT, ELYRA_CLICKHOUSE_DATABASE,
+	//             ELYRA_CLICKHOUSE_USERNAME, ELYRA_CLICKHOUSE_PASSWORD, ELYRA_CLICKHOUSE_HTTPS,
+	//             ELYRA_CLICKHOUSE_TIMEOUT_CONNECT, ELYRA_CLICKHOUSE_TIMEOUT_QUERY
+
+	// ── Tool: query_mysql ──
+	elyra.registerTool({
+		name: "query_mysql",
+		label: "Query MySQL",
+		description:
+			"Execute a SQL query against the configured MySQL database. Returns results as JSON. " +
+			"Use get_database_schema first to understand the database structure. " +
+			"By default, only SELECT queries are allowed. The user must approve each query before execution.",
+		parameters: Type.Object({
+			sql: Type.String({ description: "The SQL query to execute" }),
+			database: Type.Optional(
+				Type.String({ description: "Override the default database (optional)" }),
+			),
+		}),
+		execute: async (toolCallId, params, ctx) => {
+			const config = getMysqlConfig(params.database);
+			if (!config) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "MySQL not configured. Set environment variables: ELYRA_MYSQL_HOST, ELYRA_MYSQL_USER, ELYRA_MYSQL_PASSWORD, ELYRA_MYSQL_DATABASE",
+						},
+					],
+					details: {},
+				};
+			}
+
+			// Security: block non-SELECT queries unless ELYRA_DB_ALLOW_WRITES=true
+			if (!isReadOnly(params.sql) && !isWriteEnabled()) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Blocked: Only SELECT queries are allowed in read-only mode. Set ELYRA_DB_ALLOW_WRITES=true to enable writes.\n\nQuery: ${params.sql}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			try {
+				const connection = await mysql2.createConnection({
+					host: config.host,
+					port: config.port,
+					user: config.user,
+					password: config.password,
+					database: config.database,
+					connectTimeout: 10000,
+				});
+
+				try {
+					const [rows] = await connection.execute(params.sql);
+					const resultText = JSON.stringify(rows, null, 2);
+					const truncated =
+						resultText.length > 50000
+							? `${resultText.slice(0, 50000)}\n\n... (truncated, ${resultText.length} chars total)`
+							: resultText;
+
+					return {
+						content: [{ type: "text", text: truncated }],
+						details: { rowCount: Array.isArray(rows) ? rows.length : 0 },
+					};
+				} finally {
+					await connection.end();
+				}
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `MySQL error: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool: query_clickhouse ──
+	elyra.registerTool({
+		name: "query_clickhouse",
+		label: "Query ClickHouse",
+		description:
+			"Execute a SQL query against the configured ClickHouse database. Returns results as JSON. " +
+			"ClickHouse is optimized for analytical queries on large datasets. " +
+			"Use get_database_schema first to understand the database structure. The user must approve each query before execution.",
+		parameters: Type.Object({
+			sql: Type.String({ description: "The SQL query to execute" }),
+			database: Type.Optional(
+				Type.String({ description: "Override the default database (optional)" }),
+			),
+		}),
+		execute: async (toolCallId, params, ctx) => {
+			const config = getClickHouseConfig(params.database);
+			if (!config) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "ClickHouse not configured. Set environment variables: ELYRA_CLICKHOUSE_HOST, ELYRA_CLICKHOUSE_DATABASE",
+						},
+					],
+					details: {},
+				};
+			}
+
+			// Security: block non-SELECT queries unless writes enabled
+			if (!isReadOnly(params.sql) && !isWriteEnabled()) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Blocked: Only SELECT queries are allowed in read-only mode. Set ELYRA_DB_ALLOW_WRITES=true to enable writes.\n\nQuery: ${params.sql}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			try {
+				const protocol = config.https ? "https" : "http";
+				const client = createClient({
+					url: `${protocol}://${config.host}:${config.port}`,
+					username: config.user,
+					password: config.password,
+					database: config.database,
+					connect_timeout: config.timeoutConnect,
+					request_timeout: config.timeoutQuery,
+				});
+
+				try {
+					const result = await client.query({
+						query: params.sql,
+						format: "JSONEachRow",
+					});
+					const rows = await result.json();
+					const resultText = JSON.stringify(rows, null, 2);
+					const truncated =
+						resultText.length > 50000
+							? `${resultText.slice(0, 50000)}\n\n... (truncated, ${resultText.length} chars total)`
+							: resultText;
+
+					return {
+						content: [{ type: "text", text: truncated }],
+						details: { rowCount: Array.isArray(rows) ? rows.length : 0 },
+					};
+				} finally {
+					await client.close();
+				}
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `ClickHouse error: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool: get_database_schema ──
+	elyra.registerTool({
+		name: "get_database_schema",
+		label: "Get Database Schema",
+		description:
+			"Discover the database schema (tables, columns, types, indexes). " +
+			"Call this before writing queries to understand the database structure. " +
+			"Supports both MySQL and ClickHouse.",
+		parameters: Type.Object({
+			engine: Type.Union([Type.Literal("mysql"), Type.Literal("clickhouse")], {
+				description: "Which database engine to query",
+			}),
+			database: Type.Optional(
+				Type.String({ description: "Override the default database (optional)" }),
+			),
+			table: Type.Optional(
+				Type.String({
+					description:
+						"Get detailed schema for a specific table (optional, omit for overview of all tables)",
+				}),
+			),
+		}),
+		execute: async (toolCallId, params, ctx) => {
+			if (params.engine === "mysql") {
+				return getMysqlSchema(params.database, params.table);
+			}
+			return getClickHouseSchema(params.database, params.table);
+		},
+	});
+}
+
+// ── Config Helpers ──
+
+interface MysqlConfig {
+	host: string;
+	port: number;
+	user: string;
+	password: string;
+	database: string;
+}
+
+interface ClickHouseConfig {
+	host: string;
+	port: number;
+	https: boolean;
+	user: string;
+	password: string;
+	database: string;
+	timeoutConnect: number;
+	timeoutQuery: number;
+}
+
+function getMysqlConfig(databaseOverride?: string): MysqlConfig | undefined {
+	const host = process.env.ELYRA_MYSQL_HOST;
+	const user = process.env.ELYRA_MYSQL_USER;
+	const password = process.env.ELYRA_MYSQL_PASSWORD;
+	const database = databaseOverride || process.env.ELYRA_MYSQL_DATABASE;
+	if (!host || !user || !database) return undefined;
+	return {
+		host,
+		port: Number.parseInt(process.env.ELYRA_MYSQL_PORT || "3306", 10),
+		user,
+		password: password || "",
+		database,
+	};
+}
+
+function getClickHouseConfig(databaseOverride?: string): ClickHouseConfig | undefined {
+	const host = process.env.ELYRA_CLICKHOUSE_HOST;
+	const database = databaseOverride || process.env.ELYRA_CLICKHOUSE_DATABASE;
+	if (!host || !database) return undefined;
+	const port = Number.parseInt(process.env.ELYRA_CLICKHOUSE_PORT || "8123", 10);
+	const https = process.env.ELYRA_CLICKHOUSE_HTTPS === "true";
+	const timeoutConnect = Number.parseInt(process.env.ELYRA_CLICKHOUSE_TIMEOUT_CONNECT || "10000", 10);
+	const timeoutQuery = Number.parseInt(process.env.ELYRA_CLICKHOUSE_TIMEOUT_QUERY || "30000", 10);
+	return {
+		host,
+		port,
+		https,
+		user: process.env.ELYRA_CLICKHOUSE_USERNAME || "default",
+		password: process.env.ELYRA_CLICKHOUSE_PASSWORD || "",
+		database,
+		timeoutConnect,
+		timeoutQuery,
+	};
+}
+
+function isWriteEnabled(): boolean {
+	const v = process.env.ELYRA_DB_ALLOW_WRITES;
+	return v === "true" || v === "1" || v === "yes";
+}
+
+function isReadOnly(sql: string): boolean {
+	const trimmed = sql.trim().toUpperCase();
+	// Allow SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (CTEs start with WITH...SELECT)
+	return /^(SELECT|SHOW|DESCRIBE|DESC|EXPLAIN|WITH)\b/.test(trimmed);
+}
+
+// ── Schema Discovery ──
+
+async function getMysqlSchema(
+	databaseOverride?: string,
+	table?: string,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+	const config = getMysqlConfig(databaseOverride);
+	if (!config) {
+		return {
+			content: [{ type: "text", text: "MySQL not configured." }],
+			details: {},
+		};
+	}
+
+	try {
+		const connection = await mysql2.createConnection({
+			host: config.host,
+			port: config.port,
+			user: config.user,
+			password: config.password,
+			database: config.database,
+			connectTimeout: 10000,
+		});
+
+		try {
+			if (table) {
+				// Detailed schema for a specific table
+				const [columns] = await connection.execute(
+					`SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA
+					 FROM INFORMATION_SCHEMA.COLUMNS
+					 WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+					 ORDER BY ORDINAL_POSITION`,
+					[config.database, table],
+				);
+				const [indexes] = await connection.execute(`SHOW INDEX FROM \`${table}\``);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Table: ${table}\n\nColumns:\n${JSON.stringify(columns, null, 2)}\n\nIndexes:\n${JSON.stringify(indexes, null, 2)}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			// Overview: all tables with row counts
+			const [tables] = await connection.execute(
+				`SELECT TABLE_NAME, TABLE_ROWS, DATA_LENGTH, TABLE_COMMENT
+				 FROM INFORMATION_SCHEMA.TABLES
+				 WHERE TABLE_SCHEMA = ?
+				 ORDER BY TABLE_NAME`,
+				[config.database],
+			);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Database: ${config.database}\n\nTables:\n${JSON.stringify(tables, null, 2)}`,
+					},
+				],
+				details: { tableCount: Array.isArray(tables) ? tables.length : 0 },
+			};
+		} finally {
+			await connection.end();
+		}
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `MySQL schema error: ${msg}` }],
+			details: {},
+		};
+	}
+}
+
+async function getClickHouseSchema(
+	databaseOverride?: string,
+	table?: string,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+	const config = getClickHouseConfig(databaseOverride);
+	if (!config) {
+		return {
+			content: [{ type: "text", text: "ClickHouse not configured." }],
+			details: {},
+		};
+	}
+
+	try {
+		const protocol = config.https ? "https" : "http";
+		const client = createClient({
+			url: `${protocol}://${config.host}:${config.port}`,
+			username: config.user,
+			password: config.password,
+			database: config.database,
+			connect_timeout: config.timeoutConnect,
+			request_timeout: config.timeoutQuery,
+		});
+
+		try {
+			if (table) {
+				const result = await client.query({
+					query: `DESCRIBE TABLE ${table}`,
+					format: "JSONEachRow",
+				});
+				const columns = await result.json();
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Table: ${table}\n\nColumns:\n${JSON.stringify(columns, null, 2)}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			const result = await client.query({
+				query: `SELECT name, engine, total_rows, total_bytes
+				        FROM system.tables
+				        WHERE database = '${config.database}'
+				        ORDER BY name`,
+				format: "JSONEachRow",
+			});
+			const tables = await result.json();
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Database: ${config.database}\n\nTables:\n${JSON.stringify(tables, null, 2)}`,
+					},
+				],
+				details: { tableCount: Array.isArray(tables) ? tables.length : 0 },
+			};
+		} finally {
+			await client.close();
+		}
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `ClickHouse schema error: ${msg}` }],
+			details: {},
+		};
+	}
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@elyracode/db-tools",
+  "version": "0.3.1",
+    "description": "Database tools for Elyra - query MySQL and ClickHouse with schema awareness and safety guardrails",
+  "type": "module",
+  "keywords": ["elyra-package", "database", "mysql", "clickhouse", "sql"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/db-tools"
+  },
+  "elyra": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "dependencies": {
+    "mysql2": "^3.14.0",
+    "@clickhouse/client": "^1.8.0"
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}