@elyracode/db-tools 0.9.48 → 0.9.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,13 @@
1
+ # Changelog
2
+
3
+ ## [0.9.50] - 2026-10-10
4
+
5
+ ### Fixed
6
+ - `ELYRA_CLICKHOUSE_TIMEOUT_CONNECT` now works. It was passed to the ClickHouse client as `connect_timeout`, which the client does not support, so it was silently ignored and an unreachable server only failed after the query timeout. The extension now pings the server first and fails with a clear message once the connect timeout passes
7
+ - The MySQL and ClickHouse tool descriptions no longer claim that the user approves each query; there is no such step. They now state the actual rule: only SELECT queries unless `ELYRA_DB_ALLOW_WRITES=true`
8
+ - Type errors in the tool definitions (result details were inferred too narrowly, and the third `execute` argument, the abort signal, was named `ctx`). The extension is now type-checked with the rest of the repository
9
+
10
+ ## [0.9.49] - 2026-10-10
11
+
12
+ ### Changed
13
+ - The MySQL and ClickHouse drivers load on the first query instead of at extension load, which removes about 25 ms from every Elyra startup, including sessions that never touch a database
@@ -1,10 +1,69 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import { join } from "node:path";
3
- import type { ExtensionAPI } from "@elyracode/coding-agent";
4
- import { createClient } from "@clickhouse/client";
5
- import mysql2 from "mysql2/promise";
3
+ import type { AgentToolResult, ExtensionAPI } from "@elyracode/coding-agent";
4
+ import type * as ClickHouse from "@clickhouse/client";
5
+ import type * as MySql from "mysql2/promise";
6
6
  import { Type } from "typebox";
7
7
 
8
+ /**
9
+ * Database drivers load on the first query. Importing mysql2 and the ClickHouse client at
10
+ * extension load added about 20 ms to every Elyra startup, including sessions that never
11
+ * touch a database (measured 2026-10-10).
12
+ */
13
+ let mysqlDriver: Promise<typeof MySql> | undefined;
14
+ let clickhouseDriver: Promise<typeof ClickHouse> | undefined;
15
+ const loadMysql = (): Promise<typeof MySql> => (mysqlDriver ??= import("mysql2/promise"));
16
+ const loadClickHouse = (): Promise<typeof ClickHouse> => (clickhouseDriver ??= import("@clickhouse/client"));
17
+
18
+ /** Details reported by the query tools. */
19
+ interface QueryDetails {
20
+ rowCount?: number;
21
+ }
22
+
23
+ /**
24
+ * Create a ClickHouse client and make sure the server answers within `timeoutConnect`.
25
+ * The client has no connect-timeout option of its own (only `request_timeout` for the whole
26
+ * request), so ELYRA_CLICKHOUSE_TIMEOUT_CONNECT is enforced with a ping before the query.
27
+ */
28
+ async function openClickHouse(config: ClickHouseConfig): Promise<ClickHouse.ClickHouseClient> {
29
+ const protocol = config.https ? "https" : "http";
30
+ const client = (await loadClickHouse()).createClient({
31
+ url: `${protocol}://${config.host}:${config.port}`,
32
+ username: config.user,
33
+ password: config.password,
34
+ database: config.database,
35
+ request_timeout: config.timeoutQuery,
36
+ });
37
+ let timer: ReturnType<typeof setTimeout> | undefined;
38
+ const ping = client.ping();
39
+ ping.catch(() => {});
40
+ try {
41
+ const result = await Promise.race([
42
+ ping,
43
+ new Promise<never>((_, reject) => {
44
+ timer = setTimeout(
45
+ () =>
46
+ reject(
47
+ new Error(
48
+ `could not reach ClickHouse at ${config.host}:${config.port} within ${config.timeoutConnect} ms (ELYRA_CLICKHOUSE_TIMEOUT_CONNECT)`,
49
+ ),
50
+ ),
51
+ config.timeoutConnect,
52
+ );
53
+ }),
54
+ ]);
55
+ if (!result.success) {
56
+ throw result.error instanceof Error ? result.error : new Error("ClickHouse ping failed");
57
+ }
58
+ return client;
59
+ } catch (error) {
60
+ await client.close().catch(() => {});
61
+ throw error;
62
+ } finally {
63
+ clearTimeout(timer);
64
+ }
65
+ }
66
+
8
67
  export default function (elyra: ExtensionAPI) {
9
68
  // ── Load .env ──
10
69
  // Reads the project's .env file (if it exists) and maps common Laravel/Docker
@@ -25,14 +84,14 @@ export default function (elyra: ExtensionAPI) {
25
84
  description:
26
85
  "Execute a SQL query against the configured MySQL database. Returns results as JSON. " +
27
86
  "Use get_database_schema first to understand the database structure. " +
28
- "By default, only SELECT queries are allowed. The user must approve each query before execution.",
87
+ "By default, only SELECT queries are allowed (set ELYRA_DB_ALLOW_WRITES=true to allow writes).",
29
88
  parameters: Type.Object({
30
89
  sql: Type.String({ description: "The SQL query to execute" }),
31
90
  database: Type.Optional(
32
91
  Type.String({ description: "Override the default database (optional)" }),
33
92
  ),
34
93
  }),
35
- execute: async (toolCallId, params, ctx) => {
94
+ execute: async (_toolCallId, params): Promise<AgentToolResult<QueryDetails>> => {
36
95
  const config = getMysqlConfig(params.database);
37
96
  if (!config) {
38
97
  return {
@@ -60,7 +119,7 @@ export default function (elyra: ExtensionAPI) {
60
119
  }
61
120
 
62
121
  try {
63
- const connection = await mysql2.createConnection({
122
+ const connection = await (await loadMysql()).createConnection({
64
123
  host: config.host,
65
124
  port: config.port,
66
125
  user: config.user,
@@ -101,14 +160,14 @@ export default function (elyra: ExtensionAPI) {
101
160
  description:
102
161
  "Execute a SQL query against the configured ClickHouse database. Returns results as JSON. " +
103
162
  "ClickHouse is optimized for analytical queries on large datasets. " +
104
- "Use get_database_schema first to understand the database structure. The user must approve each query before execution.",
163
+ "Use get_database_schema first to understand the database structure. By default, only SELECT queries are allowed.",
105
164
  parameters: Type.Object({
106
165
  sql: Type.String({ description: "The SQL query to execute" }),
107
166
  database: Type.Optional(
108
167
  Type.String({ description: "Override the default database (optional)" }),
109
168
  ),
110
169
  }),
111
- execute: async (toolCallId, params, ctx) => {
170
+ execute: async (_toolCallId, params): Promise<AgentToolResult<QueryDetails>> => {
112
171
  const config = getClickHouseConfig(params.database);
113
172
  if (!config) {
114
173
  return {
@@ -136,15 +195,7 @@ export default function (elyra: ExtensionAPI) {
136
195
  }
137
196
 
138
197
  try {
139
- const protocol = config.https ? "https" : "http";
140
- const client = createClient({
141
- url: `${protocol}://${config.host}:${config.port}`,
142
- username: config.user,
143
- password: config.password,
144
- database: config.database,
145
- connect_timeout: config.timeoutConnect,
146
- request_timeout: config.timeoutQuery,
147
- });
198
+ const client = await openClickHouse(config);
148
199
 
149
200
  try {
150
201
  const result = await client.query({
@@ -190,7 +241,7 @@ export default function (elyra: ExtensionAPI) {
190
241
  Type.String({ description: "Path to the SQLite database file (default: auto-detect from .env or database/database.sqlite)" }),
191
242
  ),
192
243
  }),
193
- execute: async (_toolCallId, params) => {
244
+ execute: async (_toolCallId, params): Promise<AgentToolResult<QueryDetails>> => {
194
245
  const dbPath = resolveSqlitePath(params.db_path);
195
246
  if (!dbPath) {
196
247
  return {
@@ -424,7 +475,7 @@ async function getMysqlSchema(
424
475
  }
425
476
 
426
477
  try {
427
- const connection = await mysql2.createConnection({
478
+ const connection = await (await loadMysql()).createConnection({
428
479
  host: config.host,
429
480
  port: config.port,
430
481
  user: config.user,
@@ -497,15 +548,7 @@ async function getClickHouseSchema(
497
548
  }
498
549
 
499
550
  try {
500
- const protocol = config.https ? "https" : "http";
501
- const client = createClient({
502
- url: `${protocol}://${config.host}:${config.port}`,
503
- username: config.user,
504
- password: config.password,
505
- database: config.database,
506
- connect_timeout: config.timeoutConnect,
507
- request_timeout: config.timeoutQuery,
508
- });
551
+ const client = await openClickHouse(config);
509
552
 
510
553
  try {
511
554
  if (table) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elyracode/db-tools",
3
- "version": "0.9.48",
3
+ "version": "0.9.50",
4
4
  "description": "Database tools for Elyra - query MySQL and ClickHouse with schema awareness and safety guardrails",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -0,0 +1,48 @@
1
+ import type { AddressInfo } from "node:net";
2
+ import { createServer, type Server, type Socket } from "node:net";
3
+ import { afterEach, describe, expect, it } from "vitest";
4
+ import dbTools from "../extensions/index.js";
5
+
6
+ type Tool = { name: string; execute: (...args: unknown[]) => Promise<{ content: Array<{ text?: string }> }> };
7
+
8
+ function loadTools(): Map<string, Tool> {
9
+ const tools = new Map<string, Tool>();
10
+ const api = new Proxy(
11
+ { registerTool: (tool: Tool) => tools.set(tool.name, tool) },
12
+ { get: (target, prop) => (prop in target ? target[prop as keyof typeof target] : () => {}) },
13
+ );
14
+ dbTools(api as never);
15
+ return tools;
16
+ }
17
+
18
+ describe("ClickHouse connect timeout", () => {
19
+ let server: Server | undefined;
20
+ const sockets: Socket[] = [];
21
+ const saved = { ...process.env };
22
+
23
+ afterEach(() => {
24
+ for (const s of sockets.splice(0)) s.destroy();
25
+ server?.close();
26
+ process.env = { ...saved };
27
+ });
28
+
29
+ it("fails fast with a clear error when the server accepts but never answers", async () => {
30
+ // Accept connections and never respond, like a firewall or a hung server.
31
+ server = createServer((socket) => sockets.push(socket));
32
+ await new Promise<void>((resolve) => server!.listen(0, "127.0.0.1", resolve));
33
+ const port = (server.address() as AddressInfo).port;
34
+ process.env.ELYRA_CLICKHOUSE_HOST = "127.0.0.1";
35
+ process.env.ELYRA_CLICKHOUSE_PORT = String(port);
36
+ process.env.ELYRA_CLICKHOUSE_DATABASE = "default";
37
+ process.env.ELYRA_CLICKHOUSE_TIMEOUT_CONNECT = "300";
38
+ process.env.ELYRA_CLICKHOUSE_TIMEOUT_QUERY = "30000";
39
+
40
+ const tool = loadTools().get("query_clickhouse");
41
+ expect(tool).toBeDefined();
42
+ const started = Date.now();
43
+ const result = await tool!.execute("call-1", { sql: "SELECT 1" });
44
+ const elapsed = Date.now() - started;
45
+ expect(result.content[0].text).toContain("within 300 ms");
46
+ expect(elapsed).toBeLessThan(3000);
47
+ });
48
+ });