@clickhouse/client 1.22.0 → 1.23.0-head.b25cda1.1

package/dist/common/client.js

@@ -0,0 +1,414 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickHouseClient = void 0;
+const parse_1 = require("./parse");
+const logger_1 = require("./logger");
+const config_1 = require("./config");
+const tracing_1 = require("./tracing");
+class ClickHouseClient {
+    clientClickHouseSettings;
+    connectionParams;
+    connection;
+    makeResultSet;
+    valuesEncoder;
+    sessionId;
+    role;
+    jsonHandling;
+    tracer;
+    constructor(config) {
+        const logger = config?.log?.LoggerClass
+            ? new config.log.LoggerClass()
+            : new logger_1.DefaultLogger();
+        const configWithURL = (0, config_1.prepareConfigWithURL)(config, logger, config.impl.handle_specific_url_params ?? null);
+        this.connectionParams = (0, config_1.getConnectionParams)(configWithURL, logger);
+        this.clientClickHouseSettings = this.connectionParams.clickhouse_settings;
+        this.sessionId = config.session_id;
+        this.role = config.role;
+        this.connection = config.impl.make_connection(configWithURL, this.connectionParams);
+        // Using the connection params log level as it does the parsing.
+        // TODO: it would be better to parse the log level in the client itself.
+        this.makeResultSet = config.impl.make_result_set;
+        this.jsonHandling = {
+            ...parse_1.defaultJSONHandling,
+            ...config.json,
+        };
+        this.valuesEncoder = config.impl.values_encoder(this.jsonHandling);
+        // Assigned once at client creation: when no tracer is configured, the
+        // shared no-op tracer keeps the hot path branch-free.
+        this.tracer = config.tracer ?? tracing_1.NoopClickHouseTracer;
+    }
+    /**
+     * Used for most statements that can have a response, such as `SELECT`.
+     * Returns an implementation of {@link BaseResultSet}.
+     *
+     * The `FORMAT` clause should be specified separately via {@link QueryParams.format} (default is `JSON`);
+     * this method will always append `FORMAT <format>` to the end of {@link QueryParams.query}.
+     * If the query already contains a `FORMAT` clause, ClickHouse will return a syntax error due to a duplicate `FORMAT`.
+     * This is intended behavior.
+     * Use {@link ClickHouseClient.insert} for data insertion, {@link ClickHouseClient.command} for DDLs,
+     * or {@link ClickHouseClient.exec} for queries where you need to provide the full SQL (including `FORMAT`) yourself or where the `FORMAT` suffix is not supported.
+     *
+     * @note For `SHOW [ROW] POLICIES`, use the full syntax `SHOW POLICIES ON *`,
+     * as the short version does not support appending `FORMAT` at the server SQL parser level.
+     * See https://github.com/ClickHouse/ClickHouse/issues/105899
+     *
+     * See {@link DataFormat} for the formats supported by the client.
+     */
+    async query(params) {
+        const format = params.format ?? "JSON";
+        const query = formatQuery(params.query, format);
+        const queryParams = this.withClientQueryParams(params);
+        const { log_writer, log_level } = this.connectionParams;
+        return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.query, {
+            kind: tracing_1.ClickHouseSpanKind.CLIENT,
+            attributes: this.withBaseSpanAttributes({
+                "clickhouse.response.format": format,
+                "clickhouse.request.query_id": queryParams.query_id,
+                "clickhouse.request.session_id": queryParams.session_id,
+            }),
+        }, async (span) => {
+            let queryResult;
+            try {
+                queryResult = await this.connection.query({
+                    query,
+                    ...queryParams,
+                });
+            }
+            catch (err) {
+                (0, tracing_1.recordSpanError)(span, err);
+                span.end();
+                throw err;
+            }
+            const { stream, query_id, response_headers, http_status_code } = queryResult;
+            // The query_id may have been generated by the connection layer.
+            span.setAttributes({ "clickhouse.request.query_id": query_id });
+            setResponseSpanAttributes(span, { http_status_code });
+            // The clickhouse.query span covers the HTTP request lifetime only:
+            // it ends here, once response headers are received.  A separate
+            // clickhouse.query.stream child span is started and handed to the
+            // ResultSet to track the response stream consumption (decoded bytes,
+            // returned rows, streaming errors).  Separating the two spans makes
+            // it easy to distinguish the original request duration from a stream
+            // that may never end (e.g. tailing a live table).
+            span.end();
+            return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.query_stream, { kind: tracing_1.ClickHouseSpanKind.CLIENT }, (streamSpan) => {
+                try {
+                    return this.makeResultSet(stream, format, query_id, (err) => {
+                        if (log_level <= logger_1.ClickHouseLogLevel.ERROR) {
+                            log_writer.error({
+                                err,
+                                module: "Client",
+                                message: "Error while processing the ResultSet.",
+                                args: {
+                                    session_id: queryParams.session_id,
+                                    role: queryParams.role,
+                                    query_id,
+                                },
+                            });
+                        }
+                    }, response_headers, this.jsonHandling, streamSpan);
+                }
+                catch (err) {
+                    (0, tracing_1.recordSpanError)(streamSpan, err);
+                    streamSpan.end();
+                    throw err;
+                }
+                // streamSpan is NOT ended here - the ResultSet owns its lifetime.
+            });
+        });
+    }
+    /**
+     * It should be used for statements that do not have any output,
+     * when the format clause is not applicable, or when you are not interested in the response at all.
+     * The response stream is destroyed immediately as we do not expect useful information there.
+     * Examples of such statements are DDLs or custom inserts.
+     *
+     * @note if you have a custom query that does not work with {@link ClickHouseClient.query},
+     * and you are interested in the response data, consider using {@link ClickHouseClient.exec}.
+     */
+    async command(params) {
+        const query = removeTrailingSemi(params.query.trim());
+        const ignore_error_response = params.ignore_error_response ?? false;
+        const queryParams = this.withClientQueryParams(params);
+        return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.command, {
+            kind: tracing_1.ClickHouseSpanKind.CLIENT,
+            attributes: this.withBaseSpanAttributes({
+                "clickhouse.request.query_id": queryParams.query_id,
+                "clickhouse.request.session_id": queryParams.session_id,
+            }),
+        }, async (span) => {
+            try {
+                const result = await this.connection.command({
+                    query,
+                    ignore_error_response,
+                    ...queryParams,
+                });
+                span.setAttributes({
+                    "clickhouse.request.query_id": result.query_id,
+                });
+                setResponseSpanAttributes(span, result);
+                return result;
+            }
+            catch (err) {
+                (0, tracing_1.recordSpanError)(span, err);
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Similar to {@link ClickHouseClient.command}, but for the cases where the output _is expected_,
+     * but format clause is not applicable. The caller of this method _must_ consume the stream,
+     * as the underlying socket will not be released until then, and the request will eventually be timed out.
+     *
+     * @note it is not intended to use this method to execute the DDLs, such as `CREATE TABLE` or similar;
+     * use {@link ClickHouseClient.command} instead.
+     */
+    async exec(params) {
+        const query = removeTrailingSemi(params.query.trim());
+        const values = "values" in params ? params.values : undefined;
+        const decompress_response_stream = params.decompress_response_stream ?? true;
+        const ignore_error_response = params.ignore_error_response ?? false;
+        const queryParams = this.withClientQueryParams(params);
+        return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.exec, {
+            kind: tracing_1.ClickHouseSpanKind.CLIENT,
+            attributes: this.withBaseSpanAttributes({
+                "clickhouse.request.query_id": queryParams.query_id,
+                "clickhouse.request.session_id": queryParams.session_id,
+            }),
+        }, async (span) => {
+            try {
+                const result = await this.connection.exec({
+                    query,
+                    values,
+                    decompress_response_stream,
+                    ignore_error_response,
+                    ...queryParams,
+                });
+                span.setAttributes({
+                    "clickhouse.request.query_id": result.query_id,
+                });
+                setResponseSpanAttributes(span, result);
+                return result;
+            }
+            catch (err) {
+                (0, tracing_1.recordSpanError)(span, err);
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * The primary method for data insertion. It is recommended to avoid arrays in case of large inserts
+     * to reduce application memory consumption and consider streaming for most of such use cases.
+     * As the insert operation does not provide any output, the response stream is immediately destroyed.
+     *
+     * @note in case of a custom insert operation (e.g., `INSERT FROM SELECT`),
+     * consider using {@link ClickHouseClient.command}, passing the entire raw query there
+     * (including the `FORMAT` clause).
+     */
+    async insert(params) {
+        if (Array.isArray(params.values) && params.values.length === 0) {
+            return { executed: false, query_id: "", response_headers: {} };
+        }
+        const format = params.format || "JSONCompactEachRow";
+        this.valuesEncoder.validateInsertValues(params.values, format);
+        const query = getInsertQuery(params, format);
+        const queryParams = this.withClientQueryParams(params);
+        return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.insert, {
+            kind: tracing_1.ClickHouseSpanKind.CLIENT,
+            attributes: this.withBaseSpanAttributes({
+                "db.operation.name": "INSERT",
+                "db.collection.name": params.table,
+                "clickhouse.request.format": format,
+                "clickhouse.request.query_id": queryParams.query_id,
+                "clickhouse.request.session_id": queryParams.session_id,
+                // Only known up front for array-based inserts; for streamed
+                // inserts, the row count is not observable by the client.
+                "clickhouse.request.sent_rows": Array.isArray(params.values)
+                    ? params.values.length
+                    : undefined,
+            }),
+        }, async (span) => {
+            try {
+                const values = this.valuesEncoder.encodeValues(params.values, format);
+                // TODO: record `clickhouse.request.encoded_bytes` (the
+                // pre-compression request body size) here. This is a
+                // post-common-deprecation feature: once `client-common` is
+                // deprecated and the Node.js / Web clients are fully independent,
+                // each client can measure the encoded payload using its own
+                // platform-native byte-length primitive (e.g. `Buffer.byteLength`)
+                // instead of a hand-rolled common implementation.
+                const result = await this.connection.insert({
+                    query,
+                    values,
+                    ...queryParams,
+                });
+                span.setAttributes({
+                    "clickhouse.request.query_id": result.query_id,
+                });
+                setResponseSpanAttributes(span, result);
+                return { ...result, executed: true };
+            }
+            catch (err) {
+                (0, tracing_1.recordSpanError)(span, err);
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * A health-check request. It does not throw if an error occurs - the error is returned inside the result object.
+     *
+     * By default, Node.js version uses the built-in `/ping` endpoint, which does not verify credentials.
+     * Optionally, it can be switched to a `SELECT` query (see {@link PingParamsWithSelectQuery}).
+     * In that case, the server will verify the credentials.
+     *
+     * **NOTE**: Since the `/ping` endpoint does not support CORS, the Web version always uses a `SELECT` query.
+     */
+    async ping(params) {
+        const select = params?.select ?? false;
+        return this.tracer.startActiveSpan(tracing_1.ClickHouseSpanNames.ping, {
+            kind: tracing_1.ClickHouseSpanKind.CLIENT,
+            attributes: this.withBaseSpanAttributes({
+                "clickhouse.ping.select": select,
+            }),
+        }, async (span) => {
+            try {
+                return await this.connection.ping(params ?? { select: false });
+            }
+            catch (err) {
+                (0, tracing_1.recordSpanError)(span, err);
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Shuts down the underlying connection.
+     * This method should ideally be called only once per application lifecycle,
+     * for example, during the graceful shutdown phase.
+     */
+    async close() {
+        return await this.connection.close();
+    }
+    /**
+     * Closes the client connection.
+     *
+     * Automatically called when using `using` statement in supported environments.
+     * @see {@link ClickHouseClient.close}
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    withBaseSpanAttributes(extra) {
+        const url = this.connectionParams.url;
+        const attrs = {
+            "db.system.name": "clickhouse",
+            "server.address": url.hostname,
+            "server.port": getServerPort(url),
+            "db.namespace": this.connectionParams.database,
+        };
+        if (this.connectionParams.application_id !== undefined) {
+            attrs["clickhouse.application"] = this.connectionParams.application_id;
+        }
+        for (const [k, v] of Object.entries(extra)) {
+            if (v !== undefined)
+                attrs[k] = v;
+        }
+        return attrs;
+    }
+    withClientQueryParams(params) {
+        return {
+            clickhouse_settings: {
+                ...this.clientClickHouseSettings,
+                ...params.clickhouse_settings,
+            },
+            query_params: params.query_params,
+            abort_signal: params.abort_signal,
+            query_id: params.query_id,
+            session_id: params.session_id ?? this.sessionId,
+            role: params.role ?? this.role,
+            auth: params.auth,
+            http_headers: params.http_headers,
+            use_multipart_params: params.use_multipart_params,
+            use_multipart_params_auto: params.use_multipart_params_auto,
+        };
+    }
+}
+exports.ClickHouseClient = ClickHouseClient;
+function getServerPort(url) {
+    if (url.port !== "") {
+        return Number(url.port);
+    }
+    return url.protocol === "https:" ? 443 : 80;
+}
+/** Records HTTP status and `X-ClickHouse-Summary` counters on the span once
+ *  the response (headers) arrived. The summary values are complete only when
+ *  the query was executed with `wait_end_of_query=1`; see
+ *  {@link ClickHouseSummary}. */
+function setResponseSpanAttributes(span, result) {
+    const attributes = {};
+    if (result.http_status_code !== undefined) {
+        attributes["db.response.status_code"] = result.http_status_code;
+    }
+    const summary = result.summary;
+    if (summary !== undefined) {
+        attributes["clickhouse.summary.read_rows"] = summary.read_rows;
+        attributes["clickhouse.summary.read_bytes"] = summary.read_bytes;
+        attributes["clickhouse.summary.written_rows"] = summary.written_rows;
+        attributes["clickhouse.summary.written_bytes"] = summary.written_bytes;
+        attributes["clickhouse.summary.result_rows"] = summary.result_rows;
+        attributes["clickhouse.summary.result_bytes"] = summary.result_bytes;
+        attributes["clickhouse.summary.elapsed_ns"] = summary.elapsed_ns;
+    }
+    span.setAttributes(attributes);
+}
+function formatQuery(query, format) {
+    query = query.trim();
+    query = removeTrailingSemi(query);
+    return query + " \nFORMAT " + format;
+}
+function removeTrailingSemi(query) {
+    let lastNonSemiIdx = query.length;
+    for (let i = lastNonSemiIdx; i > 0; i--) {
+        if (query[i - 1] !== ";") {
+            lastNonSemiIdx = i;
+            break;
+        }
+    }
+    if (lastNonSemiIdx !== query.length) {
+        return query.slice(0, lastNonSemiIdx);
+    }
+    return query;
+}
+function isInsertColumnsExcept(obj) {
+    return (obj !== undefined &&
+        obj !== null &&
+        typeof obj === "object" &&
+        // Avoiding ESLint no-prototype-builtins error
+        Object.prototype.hasOwnProperty.call(obj, "except"));
+}
+function getInsertQuery(params, format) {
+    let columnsPart = "";
+    if (params.columns !== undefined) {
+        if (Array.isArray(params.columns) && params.columns.length > 0) {
+            columnsPart = ` (${params.columns.join(", ")})`;
+        }
+        else if (isInsertColumnsExcept(params.columns) &&
+            params.columns.except.length > 0) {
+            columnsPart = ` (* EXCEPT (${params.columns.except.join(", ")}))`;
+        }
+    }
+    return `INSERT INTO ${params.table.trim()}${columnsPart} FORMAT ${format}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/common/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/common/client.ts"],"names":[],"mappings":";;;AAYA,mCAA8C;AAC9C,qCAA6D;AAO7D,qCAAqE;AASrE,uCAKmB;AAuKnB,MAAa,gBAAgB;IACV,wBAAwB,CAAqB;IAC7C,gBAAgB,CAAmB;IACnC,UAAU,CAAqB;IAC/B,aAAa,CAAwB;IACrC,aAAa,CAAwB;IACrC,SAAS,CAAU;IACnB,IAAI,CAA0B;IAC9B,YAAY,CAAe;IAC3B,MAAM,CAAmB;IAE1C,YACE,MAAyE;QAEzE,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,WAAW;YACrC,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE;YAC9B,CAAC,CAAC,IAAI,sBAAa,EAAE,CAAC;QACxB,MAAM,aAAa,GAAG,IAAA,6BAAoB,EACxC,MAAM,EACN,MAAM,EACN,MAAM,CAAC,IAAI,CAAC,0BAA0B,IAAI,IAAI,CAC/C,CAAC;QACF,IAAI,CAAC,gBAAgB,GAAG,IAAA,4BAAmB,EAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QACnE,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC,gBAAgB,CAAC,mBAAmB,CAAC;QAC1E,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAC3C,aAAa,EACb,IAAI,CAAC,gBAAgB,CACtB,CAAC;QACF,gEAAgE;QAChE,wEAAwE;QACxE,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG;YAClB,GAAG,2BAAmB;YACtB,GAAG,MAAM,CAAC,IAAI;SACf,CAAC;QAEF,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACnE,sEAAsE;QACtE,sDAAsD;QACtD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,8BAAoB,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,KAAK,CACT,MAAqC;QAErC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,WAAW,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,KAAK,EACzB;YACE,IAAI,EAAE,4BAAkB,CAAC,MAAM;YAC/B,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC;gBACtC,4BAA4B,EAAE,MAAM;gBACpC,6BAA6B,EAAE,WAAW,CAAC,QAAQ;gBACnD,+BAA+B,EAAE,WAAW,CAAC,UAAU;aACxD,CAAC;SACH,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,WAAW,CAAC;YAChB,IAAI,CAAC;gBACH,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;oBACxC,KAAK;oBACL,GAAG,WAAW;iBACf,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,yBAAe,EAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACX,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAC5D,WAAW,CAAC;YACd,gEAAgE;YAChE,IAAI,CAAC,aAAa,CAAC,EAAE,6BAA6B,EAAE,QAAQ,EAAE,CAAC,CAAC;YAChE,yBAAyB,CAAC,IAAI,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;YACtD,mEAAmE;YACnE,gEAAgE;YAChE,kEAAkE;YAClE,qEAAqE;YACrE,oEAAoE;YACpE,qEAAqE;YACrE,kDAAkD;YAClD,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,YAAY,EAChC,EAAE,IAAI,EAAE,4BAAkB,CAAC,MAAM,EAAE,EACnC,CAAC,UAAU,EAAE,EAAE;gBACb,IAAI,CAAC;oBACH,OAAO,IAAI,CAAC,aAAa,CACvB,MAAM,EACN,MAAM,EACN,QAAQ,EACR,CAAC,GAAG,EAAE,EAAE;wBACN,IAAI,SAAS,IAAI,2BAAkB,CAAC,KAAK,EAAE,CAAC;4BAC1C,UAAU,CAAC,KAAK,CAAC;gCACf,GAAG;gCACH,MAAM,EAAE,QAAQ;gCAChB,OAAO,EAAE,uCAAuC;gCAChD,IAAI,EAAE;oCACJ,UAAU,EAAE,WAAW,CAAC,UAAU;oCAClC,IAAI,EAAE,WAAW,CAAC,IAAI;oCACtB,QAAQ;iCACT;6BACF,CAAC,CAAC;wBACL,CAAC;oBACH,CAAC,EACD,gBAAgB,EAChB,IAAI,CAAC,YAAY,EACjB,UAAU,CACX,CAAC;gBACJ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAA,yBAAe,EAAC,UAAU,EAAE,GAAG,CAAC,CAAC;oBACjC,UAAU,CAAC,GAAG,EAAE,CAAC;oBACjB,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,kEAAkE;YACpE,CAAC,CACF,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CAAC,MAAqB;QACjC,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,qBAAqB,GAAG,MAAM,CAAC,qBAAqB,IAAI,KAAK,CAAC;QACpE,MAAM,WAAW,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,OAAO,EAC3B;YACE,IAAI,EAAE,4BAAkB,CAAC,MAAM;YAC/B,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC;gBACtC,6BAA6B,EAAE,WAAW,CAAC,QAAQ;gBACnD,+BAA+B,EAAE,WAAW,CAAC,UAAU;aACxD,CAAC;SACH,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;oBAC3C,KAAK;oBACL,qBAAqB;oBACrB,GAAG,WAAW;iBACf,CAAC,CAAC;gBACH,IAAI,CAAC,aAAa,CAAC;oBACjB,6BAA6B,EAAE,MAAM,CAAC,QAAQ;iBAC/C,CAAC,CAAC;gBACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACxC,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,yBAAe,EAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC3B,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CACR,MAAiD;QAEjD,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9D,MAAM,0BAA0B,GAC9B,MAAM,CAAC,0BAA0B,IAAI,IAAI,CAAC;QAC5C,MAAM,qBAAqB,GAAG,MAAM,CAAC,qBAAqB,IAAI,KAAK,CAAC;QACpE,MAAM,WAAW,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,IAAI,EACxB;YACE,IAAI,EAAE,4BAAkB,CAAC,MAAM;YAC/B,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC;gBACtC,6BAA6B,EAAE,WAAW,CAAC,QAAQ;gBACnD,+BAA+B,EAAE,WAAW,CAAC,UAAU;aACxD,CAAC;SACH,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;oBACxC,KAAK;oBACL,MAAM;oBACN,0BAA0B;oBAC1B,qBAAqB;oBACrB,GAAG,WAAW;iBACf,CAAC,CAAC;gBACH,IAAI,CAAC,aAAa,CAAC;oBACjB,6BAA6B,EAAE,MAAM,CAAC,QAAQ;iBAC/C,CAAC,CAAC;gBACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACxC,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,yBAAe,EAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC3B,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAI,MAA+B;QAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC;QACjE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,oBAAoB,CAAC;QACrD,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAE/D,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,MAAM,EAC1B;YACE,IAAI,EAAE,4BAAkB,CAAC,MAAM;YAC/B,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC;gBACtC,mBAAmB,EAAE,QAAQ;gBAC7B,oBAAoB,EAAE,MAAM,CAAC,KAAK;gBAClC,2BAA2B,EAAE,MAAM;gBACnC,6BAA6B,EAAE,WAAW,CAAC,QAAQ;gBACnD,+BAA+B,EAAE,WAAW,CAAC,UAAU;gBACvD,4DAA4D;gBAC5D,0DAA0D;gBAC1D,8BAA8B,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;oBAC1D,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM;oBACtB,CAAC,CAAC,SAAS;aACd,CAAC;SACH,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACtE,uDAAuD;gBACvD,qDAAqD;gBACrD,2DAA2D;gBAC3D,kEAAkE;gBAClE,4DAA4D;gBAC5D,mEAAmE;gBACnE,kDAAkD;gBAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;oBAC1C,KAAK;oBACL,MAAM;oBACN,GAAG,WAAW;iBACf,CAAC,CAAC;gBACH,IAAI,CAAC,aAAa,CAAC;oBACjB,6BAA6B,EAAE,MAAM,CAAC,QAAQ;iBAC/C,CAAC,CAAC;gBACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACxC,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACvC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,yBAAe,EAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC3B,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,MAAmB;QAC5B,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,KAAK,CAAC;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAChC,6BAAmB,CAAC,IAAI,EACxB;YACE,IAAI,EAAE,4BAAkB,CAAC,MAAM;YAC/B,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC;gBACtC,wBAAwB,EAAE,MAAM;aACjC,CAAC;SACH,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAC/B,MAAM,IAAI,EAAE,MAAM,EAAE,KAAc,EAAE,CACrC,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,yBAAe,EAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC3B,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAEO,sBAAsB,CAC5B,KAA+B;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC;QACtC,MAAM,KAAK,GAA6B;YACtC,gBAAgB,EAAE,YAAY;YAC9B,gBAAgB,EAAE,GAAG,CAAC,QAAQ;YAC9B,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC;YACjC,cAAc,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ;SAC/C,CAAC;QACF,IAAI,IAAI,CAAC,gBAAgB,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACvD,KAAK,CAAC,wBAAwB,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,cAAc,CAAC;QACzE,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,SAAS;gBAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,qBAAqB,CAAC,MAAuB;QACnD,OAAO;YACL,mBAAmB,EAAE;gBACnB,GAAG,IAAI,CAAC,wBAAwB;gBAChC,GAAG,MAAM,CAAC,mBAAmB;aAC9B;YACD,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,SAAS;YAC/C,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;YAC9B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;YACjD,yBAAyB,EAAE,MAAM,CAAC,yBAAyB;SAC5D,CAAC;IACJ,CAAC;CACF;AAxYD,4CAwYC;AAED,SAAS,aAAa,CAAC,GAAQ;IAC7B,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;iCAGiC;AACjC,SAAS,yBAAyB,CAChC,IAAoB,EACpB,MAAkD;IAElD,MAAM,UAAU,GAA6B,EAAE,CAAC;IAChD,IAAI,MAAM,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QAC1C,UAAU,CAAC,yBAAyB,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAClE,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,UAAU,CAAC,8BAA8B,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;QAC/D,UAAU,CAAC,+BAA+B,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;QACjE,UAAU,CAAC,iCAAiC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;QACrE,UAAU,CAAC,kCAAkC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;QACvE,UAAU,CAAC,gCAAgC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;QACnE,UAAU,CAAC,iCAAiC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;QACrE,UAAU,CAAC,+BAA+B,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,MAAkB;IACpD,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACrB,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;AACvC,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,IAAI,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,cAAc,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,cAAc,GAAG,CAAC,CAAC;YACnB,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,cAAc,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAY;IACzC,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,8CAA8C;QAC9C,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CACpD,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,MAAuB,EACvB,MAAkB;IAElB,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/D,WAAW,GAAG,KAAK,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAClD,CAAC;aAAM,IACL,qBAAqB,CAAC,MAAM,CAAC,OAAO,CAAC;YACrC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAChC,CAAC;YACD,WAAW,GAAG,eAAe,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QACpE,CAAC;IACH,CAAC;IACD,OAAO,eAAe,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,WAAW,WAAW,MAAM,EAAE,CAAC;AAC7E,CAAC"}

package/dist/common/config.d.ts

@@ -0,0 +1,234 @@
+import type { InsertValues, ResponseHeaders } from "./clickhouse_types";
+import type { CompressionMethod, Connection, ConnectionParams, RequestCompression } from "./connection";
+import type { DataFormat } from "./data_formatter";
+import type { Logger } from "./logger";
+import { ClickHouseLogLevel } from "./logger";
+import { type JSONHandling } from "./parse/json_handling";
+import type { BaseResultSet } from "./result";
+import type { ClickHouseSettings } from "./settings";
+import type { ClickHouseSpan, ClickHouseTracer } from "./tracing";
+export interface BaseClickHouseClientConfigOptions {
+    /** @deprecated since version 1.0.0. Use {@link url} instead. <br/>
+     *  A ClickHouse instance URL.
+     *  @default http://localhost:8123 */
+    host?: string;
+    /** A ClickHouse instance URL.
+     *  @default http://localhost:8123 */
+    url?: string | URL;
+    /** An optional pathname to add to the ClickHouse URL after it is parsed by the client.
+     *  For example, if you use a proxy, and your ClickHouse instance can be accessed as http://proxy:8123/clickhouse_server,
+     *  specify `clickhouse_server` here (with or without a leading slash);
+     *  otherwise, if provided directly in the {@link url}, it will be considered as the `database` option.<br/>
+     *  Multiple segments are supported, e.g. `/my_proxy/db`.
+     *  @default empty string */
+    pathname?: string;
+    /** The request timeout in milliseconds.
+     *  @default 30_000 */
+    request_timeout?: number;
+    /** Maximum number of sockets to allow per host.
+     *  @default 10 */
+    max_open_connections?: number;
+    /** Request and response compression settings. */
+    compression?: {
+        /** Instructs the ClickHouse server to respond with a compressed response body.
+         *  `true` requests `gzip`; pass `{ codec }` to select the codec explicitly,
+         *  e.g. `{ codec: "zstd" }` or `{ codec: "br" }`. This adds the matching
+         *  `Accept-Encoding` header and the `enable_http_compression=1` ClickHouse HTTP
+         *  setting. Decompression takes no codec options (the server chose them).
+         *  `"zstd"` requires Node.js >= 22.15.0; `"br"` works on any supported Node.js.
+         *  On `@clickhouse/client-web`, `zstd` is rejected at client creation; `gzip`
+         *  and `br` responses are decompressed by the browser.
+         *  <p><b>Warning</b>: Response compression can't be enabled for a user with readonly=1, as ClickHouse will not allow settings modifications for such user.</p>
+         *  @default false */
+        response?: boolean | {
+            codec: CompressionMethod;
+        };
+        /** Enables compression of the outgoing request (insert) body.
+         *  `true` uses `gzip` with defaults; pass a per-codec object to select the
+         *  codec and tune it: `{ codec: "gzip", level }`, `{ codec: "zstd", level }`,
+         *  or `{ codec: "br", quality }`. Each codec exposes its own option (a `level`
+         *  for gzip/zstd, a `quality` for Brotli); when omitted, a sensible default is
+         *  used (gzip/zstd use zlib's defaults, `br` defaults to quality 4 since
+         *  zlib's brotli default of 11 is far too slow for a streaming insert body).
+         *  `"zstd"` requires Node.js >= 22.15.0; `"br"` works on any supported Node.js.
+         *  Request-body compression is performed only by `@clickhouse/client` (Node.js);
+         *  `@clickhouse/client-web` sends request bodies uncompressed.
+         *  @default false */
+        request?: boolean | RequestCompression;
+    };
+    /** The name of the user on whose behalf requests are made.
+     *  Should not be set if {@link access_token} is provided.
+     *  @default default */
+    username?: string;
+    /** The user password.
+     *  Should not be set if {@link access_token} is provided.
+     *  @default empty string */
+    password?: string;
+    /** A JWT access token to authenticate with ClickHouse.
+     *  JWT token authentication is supported in ClickHouse Cloud only.
+     *  Should not be set if {@link username} or {@link password} are provided.
+     *  @default empty */
+    access_token?: string;
+    /** The name of the application using the JS client.
+     *  @default empty string */
+    application?: string;
+    /** Database name to use.
+     * @default default */
+    database?: string;
+    /** ClickHouse settings to apply to all requests.
+     *  @default empty object */
+    clickhouse_settings?: ClickHouseSettings;
+    log?: {
+        /** A class to instantiate a custom logger implementation.
+         *  @default see {@link DefaultLogger} */
+        LoggerClass?: new () => Logger;
+        /** @default set to {@link ClickHouseLogLevel.WARN} */
+        level?: ClickHouseLogLevel;
+    };
+    /** ClickHouse Session id to attach to the outgoing requests.
+     *  @default empty string (no session) */
+    session_id?: string;
+    /** ClickHouse role name(s) to attach to the outgoing requests.
+     *  @default undefined string (no roles) */
+    role?: string | Array<string>;
+    /** @deprecated since version 1.0.0. Use {@link http_headers} instead. <br/>
+     *  Additional HTTP headers to attach to the outgoing requests.
+     *  @default empty object */
+    additional_headers?: Record<string, string>;
+    /** Additional HTTP headers to attach to the outgoing requests.
+     *  @default empty object */
+    http_headers?: Record<string, string>;
+    /** HTTP Keep-Alive related settings. */
+    keep_alive?: {
+        /** Enable or disable HTTP Keep-Alive mechanism.
+         *  @default true */
+        enabled?: boolean;
+    };
+    /**
+     * Custom parsing when handling with JSON objects
+     *
+     * Defaults to using standard `JSON.parse` and `JSON.stringify`
+     */
+    json?: Partial<JSONHandling>;
+    /**
+     * Optional tracer called by the client around key lifecycle operations
+     * (`query` / `command` / `exec` / `insert` / `ping`). The interface is a
+     * structural subset of the OpenTelemetry `Tracer`/`Span` APIs, so a raw
+     * OTEL tracer (`trace.getTracer(...)`) can be passed here as-is - but the
+     * client itself depends on no tracing library.
+     *
+     * Each operation runs inside `tracer.startActiveSpan(name, options, fn)`.
+     * For OpenTelemetry, active-span context propagation across the operation's
+     * `await` points requires the `AsyncLocalStorageContextManager` (from
+     * `@opentelemetry/context-async-hooks`) to be registered; this is the
+     * default context manager in the OpenTelemetry Node.js SDK.
+     *
+     * Tracer calls are inlined into the client's hot path with no defensive
+     * wrapper: exceptions thrown by the tracer or its spans propagate to the
+     * caller. Make sure your tracer doesn't throw.
+     *
+     * @see {@link ClickHouseTracer}
+     * @default undefined (no spans are emitted; the client uses a shared no-op tracer/span to keep call sites monomorphic,
+     * at the cost of a small fixed per-operation overhead)
+     */
+    tracer?: ClickHouseTracer;
+    /** When true, query() sends query_params as multipart/form-data parts
+     *  instead of URL query string entries. This avoids HTTP URL length limits
+     *  when query parameters contain large arrays (25K+ values).
+     *  The SQL query is also moved into a multipart part named "query".
+     *  All other URL search params (database, query_id, settings, etc.) remain in the URL.
+     *  @default false */
+    use_multipart_params?: boolean;
+    /** When true, query() automatically sends query_params as multipart/form-data
+     *  parts (see {@link use_multipart_params}) once their URL-encoded length
+     *  exceeds a threshold (4096 characters), avoiding HTTP 414/400 errors from
+     *  over-long URLs. Smaller parameter payloads remain in the URL query string.
+     *  Has no effect when {@link use_multipart_params} is enabled, as that always
+     *  sends the parameters as multipart/form-data parts.
+     *  @default false */
+    use_multipart_params_auto?: boolean;
+}
+export type MakeConnection<Stream, Config = BaseClickHouseClientConfigOptionsWithURL> = (config: Config, params: ConnectionParams) => Connection<Stream>;
+export type MakeResultSet<Stream> = <Format extends DataFormat, ResultSet extends BaseResultSet<Stream, Format>>(stream: Stream, format: Format, query_id: string, log_error: (err: Error) => void, response_headers: ResponseHeaders, jsonHandling: JSONHandling, 
+/** When the client was configured with a {@link ClickHouseTracer}, a
+ *  `clickhouse.query.stream` child span is created and passed here.  The
+ *  result set tracks its own streaming progress (decoded bytes/rows) and
+ *  must record the final response metrics on the span and end it when the
+ *  stream is fully consumed, closed, or fails. */
+span?: ClickHouseSpan) => ResultSet;
+export type MakeValuesEncoder<Stream> = (jsonHandling: JSONHandling) => ValuesEncoder<Stream>;
+export interface ValuesEncoder<Stream> {
+    validateInsertValues<T = unknown>(values: InsertValues<Stream, T>, format: DataFormat): void;
+    /**
+     * A function encodes an array or a stream of JSON objects to a format compatible with ClickHouse.
+     * If values are provided as an array of JSON objects, the function encodes it in place.
+     * If values are provided as a stream of JSON objects, the function sets up the encoding of each chunk.
+     * If values are provided as a raw non-object stream, the function does nothing.
+     *
+     * @param values a set of values to send to ClickHouse.
+     * @param format a format to encode value to.
+     */
+    encodeValues<T = unknown>(values: InsertValues<Stream, T>, format: DataFormat): string | Stream;
+}
+/**
+ * An implementation might have extra config parameters that we can parse from the connection URL.
+ * These are supposed to be processed after we finish parsing the base configuration.
+ * URL params handled in the common package will be deleted from the URL object.
+ * This way we ensure that only implementation-specific params are passed there,
+ * so we can indicate which URL parameters are unknown by both common and implementation packages.
+ */
+export type HandleImplSpecificURLParams = (config: BaseClickHouseClientConfigOptions, url: URL) => {
+    config: BaseClickHouseClientConfigOptions;
+    handled_params: Set<string>;
+    unknown_params: Set<string>;
+};
+/** Things that may vary between Web/Node.js/etc client implementations. */
+export interface ImplementationDetails<Stream> {
+    impl: {
+        make_connection: MakeConnection<Stream>;
+        make_result_set: MakeResultSet<Stream>;
+        values_encoder: MakeValuesEncoder<Stream>;
+        handle_specific_url_params?: HandleImplSpecificURLParams;
+    };
+}
+export type BaseClickHouseClientConfigOptionsWithURL = Omit<BaseClickHouseClientConfigOptions, "url"> & {
+    url: URL;
+};
+/**
+ * Validates and normalizes the provided "base" config.
+ * Warns about deprecated configuration parameters usage.
+ * Parses the common URL parameters into the configuration parameters (these are the same for all implementations).
+ * Parses implementation-specific URL parameters using the handler provided by that implementation.
+ * Merges these parameters with the base config and implementation-specific defaults.
+ * Enforces certain defaults in case of deprecated keys or readonly mode.
+ */
+export declare function prepareConfigWithURL(baseConfigOptions: BaseClickHouseClientConfigOptions, logger: Logger, handleImplURLParams: HandleImplSpecificURLParams | null): BaseClickHouseClientConfigOptionsWithURL;
+export declare function getConnectionParams(config: BaseClickHouseClientConfigOptionsWithURL, logger: Logger): ConnectionParams;
+/**
+ * Merge two versions of the config: base (hardcoded) from the instance creation and the URL parsed one.
+ * URL config takes priority and overrides the base config parameters.
+ * If a value is overridden, then a warning will be logged (even if the log level is OFF).
+ */
+export declare function mergeConfigs(baseConfig: BaseClickHouseClientConfigOptions, configFromURL: BaseClickHouseClientConfigOptions, logger: Logger): BaseClickHouseClientConfigOptions;
+export declare function createUrl(configURL: string | URL | undefined): URL;
+/**
+ * @param url potentially contains auth, database and URL params to parse the configuration from
+ * @param handleExtraURLParams some platform-specific URL params might be unknown by the common package;
+ * use this function defined in the implementation to handle them. Logs warnings in case of hardcode overrides.
+ */
+export declare function loadConfigOptionsFromURL(url: URL, handleExtraURLParams: HandleImplSpecificURLParams | null): [URL, BaseClickHouseClientConfigOptions];
+export declare function booleanConfigURLValue({ key, value, }: {
+    key: string;
+    value: string;
+}): boolean;
+export declare function numberConfigURLValue({ key, value, min, max, }: {
+    key: string;
+    value: string;
+    min?: number;
+    max?: number;
+}): number;
+export declare function enumConfigURLValue<Enum, Key extends string>({ key, value, enumObject, }: {
+    key: string;
+    value: string;
+    enumObject: Record<Key, Enum>;
+}): Enum;