n8n-nodes-clickhouse-db 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name or Org]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# n8n-nodes-clickhouse
+
+[![npm version](https://img.shields.io/npm/v/n8n-nodes-clickhouse.svg)](https://www.npmjs.com/package/n8n-nodes-clickhouse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+n8n community node for [ClickHouse](https://clickhouse.com/) — query, insert, and manage your ClickHouse databases directly from n8n workflows and AI agents.
+
+## Why This Node
+
+While n8n's built-in HTTP Request node can communicate with ClickHouse's HTTP interface, it requires manual URL construction, auth headers, response parsing, and error handling for every request. This node wraps all of that into a clean, purpose-built interface with parameterized queries, batch inserts, and full ClickHouse Cloud support — so you can focus on your data, not boilerplate.
+
+## Installation
+
+### Self-hosted n8n
+
+Go to **Settings → Community Nodes → Install** and enter:
+
+```
+n8n-nodes-clickhouse
+```
+
+### n8n Cloud
+
+Search for **ClickHouse** in the nodes panel. As a verified node, no manual installation is needed.
+
+### Manual
+
+```bash
+npm install n8n-nodes-clickhouse
+```
+
+## Operations
+
+| Operation | Description |
+|-----------|-------------|
+| **Execute Query** | Run a SELECT query with optional parameterized values and return rows as n8n items |
+| **Insert** | Insert n8n input items into a ClickHouse table using JSONEachRow format with configurable batch size |
+| **Execute Raw** | Execute DDL/DML statements — CREATE TABLE, ALTER, DROP, TRUNCATE, OPTIMIZE, etc. |
+
+## Credentials Setup
+
+Create a new **ClickHouse API** credential with the following fields:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| Host | `localhost` | ClickHouse server hostname (no protocol or port) |
+| Port | `8123` | HTTP port (`8123` for HTTP, `8443` for HTTPS / ClickHouse Cloud) |
+| Database | `default` | Default database |
+| Username | `default` | ClickHouse username |
+| Password | *(empty)* | ClickHouse password |
+| Protocol | `http` | `http` or `https` (use `https` for ClickHouse Cloud) |
+
+The credential includes a built-in connectivity test that runs `SELECT 1` to verify the connection.
+
+## Usage Examples
+
+### Parameterized SELECT
+
+Use `{name:Type}` placeholders in your SQL for safe, parameterized queries:
+
+**Query:**
+```sql
+SELECT * FROM events WHERE user_id = {user_id:UInt64} AND event_date >= {start_date:Date}
+```
+
+**Query Parameters:**
+- `user_id` → `12345`
+- `start_date` → `2026-01-01`
+
+Parameters are passed as URL query params (`param_user_id=12345`), which ClickHouse handles natively — no string concatenation, no SQL injection risk.
+
+### Insert from Webhook
+
+1. Add a **Webhook** trigger node
+2. Connect it to the **ClickHouse** node
+3. Set operation to **Insert**
+4. Set the table name (e.g., `webhook_events`)
+
+All fields from the incoming webhook JSON body are inserted as columns. The node sends data in batches (default: 1000 rows per request).
+
+### CREATE TABLE with Execute Raw
+
+Set operation to **Execute Raw** and enter:
+
+```sql
+CREATE TABLE IF NOT EXISTS events (
+    event_id UInt64,
+    user_id UInt64,
+    event_type String,
+    event_date Date,
+    payload String
+) ENGINE = MergeTree()
+ORDER BY (event_date, event_id)
+```
+
+## AI Agent Tool Usage
+
+This node has `usableAsTool: true`, which means it can be wired as a tool in n8n's **AI Agent** node. This allows LLMs to query ClickHouse dynamically:
+
+1. Add an **AI Agent** node to your workflow
+2. In the Agent's **Tools** section, add the **ClickHouse** node
+3. Configure the ClickHouse credentials
+4. The AI agent can now generate and execute ClickHouse queries based on natural language prompts
+
+This is useful for building conversational analytics interfaces where users can ask questions about their data in plain English.
+
+## ClickHouse Cloud
+
+For ClickHouse Cloud instances:
+
+- Set **Protocol** to `https`
+- Set **Port** to `8443`
+- Set **Host** to your Cloud hostname (from the ClickHouse Cloud console)
+- Compatible with ClickHouse 26.x and the Cloud service
+
+## ClickHouse Settings
+
+You can pass [ClickHouse settings](https://clickhouse.com/docs/en/operations/settings/settings) as a JSON string in the **Query Settings** option field:
+
+```json
+{"max_execution_time": 30, "max_rows_to_read": 1000000}
+```
+
+These are appended as URL query parameters to the ClickHouse HTTP request.
+
+## Compatibility
+
+- **n8n**: >= 1.94.0 (verified node support)
+- **Node.js**: >= 20
+- **ClickHouse**: >= 22.x (tested up to 26.1)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup, PR guidelines, and the zero-runtime-dependencies requirement.
+
+## License
+
+[MIT](LICENSE)

package/dist/credentials/ClickHouseApi.credentials.d.ts

@@ -0,0 +1,9 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class ClickHouseApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/ClickHouseApi.credentials.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickHouseApi = void 0;
+class ClickHouseApi {
+    constructor() {
+        this.name = 'clickHouseApi';
+        this.displayName = 'ClickHouse API';
+        this.documentationUrl = 'https://clickhouse.com/docs/en/interfaces/http';
+        this.properties = [
+            {
+                displayName: 'Host',
+                name: 'host',
+                type: 'string',
+                default: 'localhost',
+                placeholder: 'localhost',
+                description: 'Hostname of the ClickHouse server (no protocol or port)',
+            },
+            {
+                displayName: 'Port',
+                name: 'port',
+                type: 'number',
+                default: 8123,
+                description: 'HTTP port of the ClickHouse server (8123 for HTTP, 8443 for HTTPS)',
+            },
+            {
+                displayName: 'Database',
+                name: 'database',
+                type: 'string',
+                default: 'default',
+                description: 'Default database to use',
+            },
+            {
+                displayName: 'Username',
+                name: 'username',
+                type: 'string',
+                default: 'default',
+            },
+            {
+                displayName: 'Password',
+                name: 'password',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+            },
+            {
+                displayName: 'Protocol',
+                name: 'protocol',
+                type: 'options',
+                options: [
+                    {
+                        name: 'HTTP',
+                        value: 'http',
+                        description: 'Unencrypted — credentials are sent in plaintext. Use only for local/trusted networks.',
+                    },
+                    {
+                        name: 'HTTPS (Recommended)',
+                        value: 'https',
+                        description: 'Encrypted connection. Required for ClickHouse Cloud (port 8443).',
+                    },
+                ],
+                default: 'http',
+                description: 'HTTPS is strongly recommended. HTTP transmits credentials in plaintext.',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Basic {{Buffer.from($credentials.username + ":" + $credentials.password).toString("base64")}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.protocol}}://{{$credentials.host}}:{{$credentials.port}}',
+                url: '/',
+                method: 'POST',
+                qs: {
+                    database: '={{$credentials.database}}',
+                },
+                body: 'SELECT 1',
+                headers: {
+                    'Content-Type': 'text/plain',
+                },
+            },
+        };
+    }
+}
+exports.ClickHouseApi = ClickHouseApi;

package/dist/nodes/ClickHouse/ClickHouse.helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure utility functions for ClickHouse HTTP interface communication.
+ * Uses ONLY Node.js built-ins — no npm imports.
+ */
+export interface ClickHouseCredentials {
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+    protocol: string;
+}
+export interface QueryParam {
+    name: string;
+    value: string;
+}
+/**
+ * Validates a ClickHouse identifier (database name, table name).
+ * Throws if the identifier contains invalid characters that could enable injection.
+ */
+export declare function validateIdentifier(value: string, label: string): void;
+/**
+ * Validates that a port number is within the valid TCP range.
+ */
+export declare function validatePort(port: number): void;
+export declare function buildBaseUrl(credentials: ClickHouseCredentials): string;
+export declare function buildAuthHeader(credentials: ClickHouseCredentials): string;
+export declare function buildUrlParams(database: string, settings?: string, queryParams?: QueryParam[]): string;
+export declare function chunkArray<T>(arr: T[], size: number): T[][];
+export declare function parseClickHouseResponse(body: string): Record<string, unknown>[];
+/**
+ * Extracts a user-safe error message from a ClickHouse HTTP error response.
+ * Strips potential credential/connection details and keeps only the
+ * ClickHouse error code and message.
+ */
+export declare function extractClickHouseError(error: unknown): string;

package/dist/nodes/ClickHouse/ClickHouse.helpers.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Pure utility functions for ClickHouse HTTP interface communication.
+ * Uses ONLY Node.js built-ins — no npm imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateIdentifier = validateIdentifier;
+exports.validatePort = validatePort;
+exports.buildBaseUrl = buildBaseUrl;
+exports.buildAuthHeader = buildAuthHeader;
+exports.buildUrlParams = buildUrlParams;
+exports.chunkArray = chunkArray;
+exports.parseClickHouseResponse = parseClickHouseResponse;
+exports.extractClickHouseError = extractClickHouseError;
+/** Pattern for valid ClickHouse identifiers (database names, table names). */
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+/** Pattern for valid query parameter names. */
+const VALID_PARAM_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** Allowlist of ClickHouse settings that can be passed as URL parameters. */
+const ALLOWED_SETTINGS = new Set([
+    'max_execution_time',
+    'max_rows_to_read',
+    'max_result_rows',
+    'max_result_bytes',
+    'max_memory_usage',
+    'max_bytes_before_external_sort',
+    'max_bytes_before_external_group_by',
+    'max_threads',
+    'max_block_size',
+    'max_insert_block_size',
+    'read_overflow_mode',
+    'result_overflow_mode',
+    'timeout_overflow_mode',
+    'connect_timeout',
+    'receive_timeout',
+    'send_timeout',
+    'output_format_json_quote_64bit_integers',
+    'output_format_json_quote_denormals',
+    'enable_http_compression',
+    'use_client_time_zone',
+    'session_id',
+    'session_timeout',
+    'session_check',
+    'extremes',
+    'replace_running_query',
+    'insert_quorum',
+    'insert_quorum_timeout',
+    'select_sequential_consistency',
+    'date_time_input_format',
+    'date_time_output_format',
+    'input_format_allow_errors_num',
+    'input_format_allow_errors_ratio',
+    'join_use_nulls',
+    'any_join_distinct_right_table_keys',
+    'max_partitions_per_insert_block',
+    'allow_experimental_lightweight_delete',
+    'mutations_sync',
+    'async_insert',
+    'wait_for_async_insert',
+]);
+/**
+ * Validates a ClickHouse identifier (database name, table name).
+ * Throws if the identifier contains invalid characters that could enable injection.
+ */
+function validateIdentifier(value, label) {
+    if (!value || !VALID_IDENTIFIER.test(value)) {
+        throw new Error(`Invalid ${label}: "${value}". Only letters, digits, underscores, and dots are allowed.`);
+    }
+}
+/**
+ * Validates a query parameter name.
+ * Throws if the name contains invalid characters.
+ */
+function validateParamName(name) {
+    if (!name || !VALID_PARAM_NAME.test(name)) {
+        throw new Error(`Invalid query parameter name: "${name}". Only letters, digits, and underscores are allowed.`);
+    }
+}
+/**
+ * Validates that a port number is within the valid TCP range.
+ */
+function validatePort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port: ${port}. Must be an integer between 1 and 65535.`);
+    }
+}
+function buildBaseUrl(credentials) {
+    validatePort(credentials.port);
+    const protocol = credentials.protocol === 'https' ? 'https' : 'http';
+    return `${protocol}://${credentials.host}:${credentials.port}`;
+}
+function buildAuthHeader(credentials) {
+    const token = Buffer.from(`${credentials.username}:${credentials.password}`).toString('base64');
+    return `Basic ${token}`;
+}
+function buildUrlParams(database, settings, queryParams) {
+    validateIdentifier(database, 'database name');
+    const params = [`database=${encodeURIComponent(database)}`];
+    if (queryParams && queryParams.length > 0) {
+        for (const param of queryParams) {
+            validateParamName(param.name);
+            params.push(`param_${encodeURIComponent(param.name)}=${encodeURIComponent(param.value)}`);
+        }
+    }
+    if (settings) {
+        try {
+            const parsed = JSON.parse(settings);
+            for (const [key, value] of Object.entries(parsed)) {
+                if (!ALLOWED_SETTINGS.has(key)) {
+                    throw new Error(`ClickHouse setting "${key}" is not in the allowlist. ` +
+                        'See the node documentation for supported settings.');
+                }
+                params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error('Query settings must be a valid JSON object (e.g. {"max_execution_time": 30}).');
+            }
+            throw error;
+        }
+    }
+    return params.join('&');
+}
+function chunkArray(arr, size) {
+    const safeSize = Math.max(1, Math.min(Math.floor(size), 100_000));
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += safeSize) {
+        chunks.push(arr.slice(i, i + safeSize));
+    }
+    return chunks;
+}
+function parseClickHouseResponse(body) {
+    if (!body || !body.trim()) {
+        return [];
+    }
+    return body
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Extracts a user-safe error message from a ClickHouse HTTP error response.
+ * Strips potential credential/connection details and keeps only the
+ * ClickHouse error code and message.
+ */
+function extractClickHouseError(error) {
+    let raw = '';
+    if (error && typeof error === 'object') {
+        const err = error;
+        if (err.response && typeof err.response === 'object') {
+            const response = err.response;
+            if (typeof response.body === 'string') {
+                raw = response.body;
+            }
+        }
+        if (!raw && err.cause && typeof err.cause === 'object') {
+            const cause = err.cause;
+            if (typeof cause.body === 'string') {
+                raw = cause.body;
+            }
+        }
+        if (!raw && typeof err.message === 'string') {
+            raw = err.message;
+        }
+    }
+    if (!raw) {
+        raw = String(error);
+    }
+    return sanitizeErrorMessage(raw);
+}
+/**
+ * Removes potentially sensitive data (hostnames, IPs, ports, file paths)
+ * from ClickHouse error messages while preserving the error code and
+ * the human-readable portion.
+ */
+function sanitizeErrorMessage(message) {
+    // Keep the first 2000 characters to prevent huge error payloads
+    let sanitized = message.slice(0, 2000);
+    // Strip stack traces (lines starting with "at ")
+    sanitized = sanitized.replace(/\n\s+at .+/g, '');
+    // Strip absolute file paths
+    sanitized = sanitized.replace(/\/[^\s:]+\.(cpp|h|cc|c):\d+/g, '[internal]');
+    return sanitized.trim();
+}

package/dist/nodes/ClickHouse/ClickHouse.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class ClickHouse implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/ClickHouse/ClickHouse.node.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickHouse = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const query_description_1 = require("./descriptions/query.description");
+const insert_description_1 = require("./descriptions/insert.description");
+const raw_description_1 = require("./descriptions/raw.description");
+const ClickHouse_helpers_1 = require("./ClickHouse.helpers");
+class ClickHouse {
+    constructor() {
+        this.description = {
+            displayName: 'ClickHouse',
+            name: 'clickHouse',
+            icon: 'file:clickhouse.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{ $parameter["operation"] }}',
+            description: 'Query and insert data using ClickHouse',
+            defaults: {
+                name: 'ClickHouse',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'clickHouseApi',
+                    required: true,
+                },
+            ],
+            usableAsTool: true,
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: 'Execute Query',
+                            value: 'executeQuery',
+                            description: 'Run a SELECT query and return the results',
+                            action: 'Execute a query',
+                        },
+                        {
+                            name: 'Insert',
+                            value: 'insert',
+                            description: 'Insert input items into a ClickHouse table',
+                            action: 'Insert rows into a table',
+                        },
+                        {
+                            name: 'Execute Raw',
+                            value: 'executeRaw',
+                            description: 'Execute DDL or DML statements (CREATE, ALTER, DROP, TRUNCATE, OPTIMIZE)',
+                            action: 'Execute a raw DDL or DML statement',
+                        },
+                    ],
+                    default: 'executeQuery',
+                },
+                ...query_description_1.queryFields,
+                ...insert_description_1.insertFields,
+                ...raw_description_1.rawFields,
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const operation = this.getNodeParameter('operation', 0);
+        const credentials = (await this.getCredentials('clickHouseApi'));
+        const baseUrl = (0, ClickHouse_helpers_1.buildBaseUrl)(credentials);
+        const authHeader = (0, ClickHouse_helpers_1.buildAuthHeader)(credentials);
+        if (operation === 'executeQuery') {
+            for (let i = 0; i < items.length; i++) {
+                try {
+                    let query = this.getNodeParameter('query', i);
+                    const options = this.getNodeParameter('options', i, {});
+                    // Build query parameters
+                    const queryParametersData = this.getNodeParameter('queryParameters', i, {});
+                    const queryParams = queryParametersData.params || [];
+                    // Append LIMIT if not already present — use safe integer coercion
+                    const limit = Math.max(0, Math.floor(options.limit ?? 100));
+                    if (limit > 0 && !/\blimit\b/i.test(query)) {
+                        query = `${query.replace(/;\s*$/, '')} LIMIT ${limit}`;
+                    }
+                    // Add FORMAT JSONEachRow
+                    query = `${query.replace(/;\s*$/, '')} FORMAT JSONEachRow`;
+                    const urlParams = (0, ClickHouse_helpers_1.buildUrlParams)(credentials.database, options.querySettings, queryParams);
+                    const response = (await this.helpers.httpRequest({
+                        method: 'POST',
+                        url: `${baseUrl}/?${urlParams}`,
+                        headers: {
+                            Authorization: authHeader,
+                            'Content-Type': 'text/plain',
+                        },
+                        body: query,
+                        returnFullResponse: false,
+                    }));
+                    const rows = (0, ClickHouse_helpers_1.parseClickHouseResponse)(response);
+                    for (const row of rows) {
+                        returnData.push({
+                            json: row,
+                            pairedItem: { item: i },
+                        });
+                    }
+                }
+                catch (error) {
+                    const chError = (0, ClickHouse_helpers_1.extractClickHouseError)(error);
+                    if (this.continueOnFail()) {
+                        returnData.push({
+                            json: { error: chError },
+                            pairedItem: { item: i },
+                        });
+                        continue;
+                    }
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), chError, { itemIndex: i });
+                }
+            }
+        }
+        else if (operation === 'insert') {
+            const table = this.getNodeParameter('table', 0);
+            const options = this.getNodeParameter('options', 0, {});
+            // Validate table name to prevent SQL injection
+            (0, ClickHouse_helpers_1.validateIdentifier)(table, 'table name');
+            const chunkSize = Math.max(1, Math.min(Math.floor(options.chunkSize ?? 1000), 100_000));
+            const database = options.database || credentials.database;
+            // Collect all items' JSON data
+            const allRows = items.map((item) => item.json);
+            const chunks = (0, ClickHouse_helpers_1.chunkArray)(allRows, chunkSize);
+            for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+                try {
+                    const chunk = chunks[chunkIndex];
+                    const ndjson = chunk.map((row) => JSON.stringify(row)).join('\n') + '\n';
+                    const urlParams = (0, ClickHouse_helpers_1.buildUrlParams)(database);
+                    const insertQuery = `INSERT INTO ${table} FORMAT JSONEachRow`;
+                    await this.helpers.httpRequest({
+                        method: 'POST',
+                        url: `${baseUrl}/?${urlParams}&query=${encodeURIComponent(insertQuery)}`,
+                        headers: {
+                            Authorization: authHeader,
+                            'Content-Type': 'application/x-ndjson',
+                        },
+                        body: ndjson,
+                        returnFullResponse: false,
+                    });
+                }
+                catch (error) {
+                    const chError = (0, ClickHouse_helpers_1.extractClickHouseError)(error);
+                    if (this.continueOnFail()) {
+                        returnData.push({
+                            json: { error: chError, chunk: chunkIndex },
+                            pairedItem: { item: 0 },
+                        });
+                        continue;
+                    }
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), chError, { itemIndex: 0 });
+                }
+            }
+            // Return summary on success
+            if (returnData.length === 0) {
+                returnData.push({
+                    json: {
+                        success: true,
+                        insertedRows: allRows.length,
+                    },
+                    pairedItem: { item: 0 },
+                });
+            }
+        }
+        else if (operation === 'executeRaw') {
+            for (let i = 0; i < items.length; i++) {
+                try {
+                    const query = this.getNodeParameter('query', i);
+                    const options = this.getNodeParameter('options', i, {});
+                    const urlParams = (0, ClickHouse_helpers_1.buildUrlParams)(credentials.database, options.querySettings);
+                    const response = (await this.helpers.httpRequest({
+                        method: 'POST',
+                        url: `${baseUrl}/?${urlParams}`,
+                        headers: {
+                            Authorization: authHeader,
+                            'Content-Type': 'text/plain',
+                        },
+                        body: query,
+                        returnFullResponse: false,
+                    }));
+                    returnData.push({
+                        json: {
+                            success: true,
+                            response: response || 'OK',
+                        },
+                        pairedItem: { item: i },
+                    });
+                }
+                catch (error) {
+                    const chError = (0, ClickHouse_helpers_1.extractClickHouseError)(error);
+                    if (this.continueOnFail()) {
+                        returnData.push({
+                            json: { error: chError },
+                            pairedItem: { item: i },
+                        });
+                        continue;
+                    }
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), chError, { itemIndex: i });
+                }
+            }
+        }
+        return [returnData];
+    }
+}
+exports.ClickHouse = ClickHouse;

package/dist/nodes/ClickHouse/clickhouse.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60" width="60" height="60">
+  <rect x="6" y="8" width="10" height="44" rx="2" fill="#FBCD2C"/>
+  <rect x="20" y="16" width="10" height="36" rx="2" fill="#F5D76E"/>
+  <rect x="34" y="26" width="10" height="26" rx="2" fill="#FBE89B"/>
+</svg>

package/dist/nodes/ClickHouse/descriptions/insert.description.d.ts

@@ -0,0 +1,2 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const insertFields: INodeProperties[];

package/dist/nodes/ClickHouse/descriptions/insert.description.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertFields = void 0;
+exports.insertFields = [
+    {
+        displayName: 'Table',
+        name: 'table',
+        type: 'string',
+        required: true,
+        default: '',
+        placeholder: 'my_table',
+        description: 'The name of the table to insert data into',
+        displayOptions: {
+            show: {
+                operation: ['insert'],
+            },
+        },
+    },
+    {
+        displayName: 'Options',
+        name: 'options',
+        type: 'collection',
+        placeholder: 'Add Option',
+        default: {},
+        displayOptions: {
+            show: {
+                operation: ['insert'],
+            },
+        },
+        options: [
+            {
+                displayName: 'Chunk Size',
+                name: 'chunkSize',
+                type: 'number',
+                default: 1000,
+                description: 'Number of rows to insert per HTTP request',
+                typeOptions: {
+                    minValue: 1,
+                },
+            },
+            {
+                displayName: 'Database',
+                name: 'database',
+                type: 'string',
+                default: '',
+                placeholder: 'my_database',
+                description: 'Override the database from credentials for this insert',
+            },
+        ],
+    },
+];

package/dist/nodes/ClickHouse/descriptions/query.description.d.ts

@@ -0,0 +1,2 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const queryFields: INodeProperties[];

package/dist/nodes/ClickHouse/descriptions/query.description.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryFields = void 0;
+exports.queryFields = [
+    {
+        displayName: 'Query',
+        name: 'query',
+        type: 'string',
+        required: true,
+        default: '',
+        placeholder: 'SELECT * FROM my_table WHERE id = {id:UInt64}',
+        description: 'The SELECT SQL query to execute. Use {name:Type} syntax for parameterized queries.',
+        typeOptions: {
+            rows: 5,
+            alwaysOpenEditWindow: true,
+        },
+        displayOptions: {
+            show: {
+                operation: ['executeQuery'],
+            },
+        },
+    },
+    {
+        displayName: 'Query Parameters',
+        name: 'queryParameters',
+        type: 'fixedCollection',
+        default: {},
+        placeholder: 'Add Parameter',
+        description: 'Parameters for the query. Use {name:Type} placeholders in SQL and define values here.',
+        typeOptions: {
+            multipleValues: true,
+        },
+        displayOptions: {
+            show: {
+                operation: ['executeQuery'],
+            },
+        },
+        options: [
+            {
+                name: 'params',
+                displayName: 'Parameter',
+                values: [
+                    {
+                        displayName: 'Name',
+                        name: 'name',
+                        type: 'string',
+                        default: '',
+                        placeholder: 'id',
+                        description: 'Parameter name (must match the {name:Type} placeholder in the query)',
+                    },
+                    {
+                        displayName: 'Value',
+                        name: 'value',
+                        type: 'string',
+                        default: '',
+                        placeholder: '42',
+                        description: 'Parameter value',
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        displayName: 'Options',
+        name: 'options',
+        type: 'collection',
+        placeholder: 'Add Option',
+        default: {},
+        displayOptions: {
+            show: {
+                operation: ['executeQuery'],
+            },
+        },
+        options: [
+            {
+                displayName: 'Limit',
+                name: 'limit',
+                type: 'number',
+                default: 100,
+                description: 'Maximum number of rows to return. Appended as LIMIT unless the query already contains one.',
+                typeOptions: {
+                    minValue: 0,
+                },
+            },
+            {
+                displayName: 'Query Settings',
+                name: 'querySettings',
+                type: 'string',
+                default: '',
+                placeholder: '{"max_execution_time": 30}',
+                description: 'JSON string of ClickHouse settings to pass as URL parameters (e.g. max_execution_time, max_rows_to_read)',
+            },
+        ],
+    },
+];

package/dist/nodes/ClickHouse/descriptions/raw.description.d.ts

@@ -0,0 +1,2 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const rawFields: INodeProperties[];

package/dist/nodes/ClickHouse/descriptions/raw.description.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawFields = void 0;
+exports.rawFields = [
+    {
+        displayName: 'Query',
+        name: 'query',
+        type: 'string',
+        required: true,
+        default: '',
+        placeholder: 'CREATE TABLE IF NOT EXISTS my_table (id UInt64, name String) ENGINE = MergeTree() ORDER BY id',
+        description: 'The DDL or DML statement to execute (CREATE, ALTER, DROP, TRUNCATE, OPTIMIZE, etc.)',
+        typeOptions: {
+            rows: 5,
+            alwaysOpenEditWindow: true,
+        },
+        displayOptions: {
+            show: {
+                operation: ['executeRaw'],
+            },
+        },
+    },
+    {
+        displayName: 'Options',
+        name: 'options',
+        type: 'collection',
+        placeholder: 'Add Option',
+        default: {},
+        displayOptions: {
+            show: {
+                operation: ['executeRaw'],
+            },
+        },
+        options: [
+            {
+                displayName: 'Query Settings',
+                name: 'querySettings',
+                type: 'string',
+                default: '',
+                placeholder: '{"max_execution_time": 60}',
+                description: 'JSON string of ClickHouse settings to pass as URL parameters',
+            },
+        ],
+    },
+];

package/index.js

@@ -0,0 +1 @@
+// n8n entry point — nothing to export; n8n loads nodes and credentials via package.json "n8n" key

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "n8n-nodes-clickhouse-db",
+  "version": "1.0.0",
+  "description": "n8n community node for ClickHouse — query, insert, and manage ClickHouse from n8n workflows and AI agents",
+  "keywords": [
+    "n8n-community-node-package",
+    "clickhouse",
+    "database",
+    "analytics",
+    "olap",
+    "columnar"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && gulp build:icons",
+    "dev": "tsc --watch",
+    "format": "prettier nodes credentials --write",
+    "lint": "eslint nodes credentials --ext .ts",
+    "lintfix": "eslint nodes credentials --ext .ts --fix",
+    "prepublishOnly": "npm run build && npm run lint"
+  },
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/ClickHouseApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/ClickHouse/ClickHouse.node.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "eslint": "^8.50.0",
+    "eslint-plugin-n8n-nodes-base": "^1.16.0",
+    "gulp": "^5.0.1",
+    "n8n-workflow": "*",
+    "prettier": "^3.0.0",
+    "typescript": "^5.1.3"
+  }
+}