Socket
Socket
Sign inDemoInstall

@clickhouse/client

Package Overview
Dependencies
Maintainers
3
Versions
44
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@clickhouse/client - npm Package Compare versions

Comparing version 0.0.8 to 0.0.9

1

dist/client.d.ts

@@ -41,2 +41,3 @@ /// <reference types="node" />

tls?: BasicTLSOptions | MutualTLSOptions;
session_id?: string;
}

@@ -43,0 +44,0 @@ interface BasicTLSOptions {

2

dist/client.js

@@ -63,2 +63,3 @@ "use strict";

},
session_id: config.session_id,
};

@@ -101,2 +102,3 @@ }

abort_signal: params.abort_signal,
session_id: this.config.session_id,
};

@@ -103,0 +105,0 @@ }

3

dist/connection/adapter/base_http_adapter.js

@@ -202,2 +202,3 @@ "use strict";

query_params: params.query_params,
session_id: params.session_id,
});

@@ -217,2 +218,3 @@ return await this.request({

query_params: params.query_params,
session_id: params.session_id,
});

@@ -232,2 +234,3 @@ return await this.request({

query: params.query,
session_id: params.session_id,
});

@@ -234,0 +237,0 @@ await this.request({

3

dist/connection/adapter/http_search_params.d.ts

@@ -7,4 +7,5 @@ import type { ClickHouseSettings } from '../../settings';

query?: string;
session_id?: string;
};
export declare function toSearchParams({ database, query, query_params, clickhouse_settings, }: ToSearchParamsOptions): URLSearchParams | undefined;
export declare function toSearchParams({ database, query, query_params, clickhouse_settings, session_id, }: ToSearchParamsOptions): URLSearchParams | undefined;
export {};

5

dist/connection/adapter/http_search_params.js

@@ -7,3 +7,3 @@ "use strict";

// https://stackoverflow.com/questions/812925/what-is-the-maximum-possible-length-of-a-query-string
function toSearchParams({ database, query, query_params, clickhouse_settings, }) {
function toSearchParams({ database, query, query_params, clickhouse_settings, session_id, }) {
if (clickhouse_settings === undefined &&

@@ -34,2 +34,5 @@ query_params === undefined &&

}
if (session_id) {
params.set('session_id', session_id);
}
return params;

@@ -36,0 +39,0 @@ }

1

dist/connection/connection.d.ts

@@ -34,2 +34,3 @@ /// <reference types="node" />

abort_signal?: AbortSignal;
session_id?: string;
}

@@ -36,0 +37,0 @@ export interface InsertParams extends BaseParams {

2

package.json
{
"name": "@clickhouse/client",
"version": "0.0.8",
"version": "0.0.9",
"description": "Official JS client for ClickHouse DB",

@@ -5,0 +5,0 @@ "license": "Apache-2.0",

382

README.md

@@ -15,3 +15,3 @@ <p align="center">

## Introduction
## About

@@ -22,365 +22,6 @@ Official Node.js client for [ClickHouse](https://clickhouse.com/), written purely in TypeScript, thoroughly tested with actual ClickHouse versions.

## Compatibility
## Documentation
The client is tested with the following ClickHouse and Node.js versions:
See the [ClickHouse website](https://clickhouse.com/docs/en/integrations/language-clients/nodejs) for the full documentation entry.
| Node.js | ClickHouse | Status |
| ------- | ---------- | ------ |
| 14.x | 22.8 | ✔ |
| 16.x | 22.8 | ✔ |
| 18.x | 22.8 | ✔ |
| 14.x | 22.9 | ✔ |
| 16.x | 22.9 | ✔ |
| 18.x | 22.9 | ✔ |
## Installation
```bash
npm i @clickhouse/client
```
## Connection
Currently, only HTTP(s) protocol is supported.
A very basic connection to a single local ClickHouse instance with default settings (for example, if it is running as a Docker container as described in the [contribution guide](./CONTRIBUTING.md)):
```ts
import { createClient } from '@clickhouse/client'
const client = createClient()
```
Basic HTTPS connection:
```ts
import { createClient } from '@clickhouse/client'
const client = createClient({
host: `https://<YOUR_CLICKHOUSE_HOST>:8443`,
password: '<YOUR_CLICKHOUSE_PASSWORD>',
database: '<YOUR_CLICKHOUSE_DATABASE>',
})
```
Using custom ClickHouse settings and forced HTTP compression (GZIP) for both request and response:
```ts
import { createClient } from '@clickhouse/client'
const client = createClient({
host: `https://<YOUR_CLICKHOUSE_HOST>:8443`,
password: '<YOUR_CLICKHOUSE_PASSWORD>',
database: '<YOUR_CLICKHOUSE_DATABASE>',
compression: {
request: true,
response: true,
},
clickhouse_settings: {
insert_quorum: '2',
},
})
```
Closing the connection:
```ts
await client.close()
```
### Connection settings overview
See [ClickHouseClientConfigOptions](https://github.com/ClickHouse/clickhouse-js/blob/60c484a3492420baed4b4c6c33cc0845262285e7/src/client.ts#L13-L35)
```ts
export interface ClickHouseClientConfigOptions {
// a valid URL, for example, https://myclickhouseserver.org:8123
// if unset, defaults to http://localhost:8123
host?: string
// milliseconds, default 10_000
connect_timeout?: number
// milliseconds, default 300_000
request_timeout?: number
// For HTTP protocol, the connection pool has infinite size by default
// it can be overriden with this setting
max_open_connections?: number
// HTTP compression settings. Uses GZIP.
// For more details, see https://clickhouse.com/docs/en/interfaces/http/#compression
compression?: {
// enabled by default - the server will compress the data it sends to you in the response
response?: boolean
// disabled by default - the server will decompress the data which you pass in the request
request?: boolean
}
// if not set, 'default' is used
username?: string
// if not set, an empty password is used
password?: string
// used to identify the connection on the server side, if not set, uses 'clickhouse-js'
application?: string
// if not set, 'default' is used
database?: string
// additional settings to send with every query, such as `date_time_input_format` or `insert_quorum`
// see https://clickhouse.com/docs/en/operations/settings/settings/
// typings should support most of the options listed there
clickhouse_settings?: ClickHouseSettings
// logger settings
log?: {
// disabled by default, can be enabled using this setting
enable?: boolean
// use it to override default clickhouse-js logger with your own implementation
LoggerClass?: new (enabled: boolean) => Logger
}
// TLS settings
tls?:
| {
// Basic TLS without client certificates
ca_cert: Buffer
}
| {
// Mutual TLS with client certificates
ca_cert: Buffer
cert: Buffer
key: Buffer
}
}
```
See also:
- [ClickHouseSettings](https://github.com/ClickHouse/clickhouse-js/blob/730b1b2516e2d47dc9a32b1d8d0b8ba8ceb95ead/src/settings.ts#L10-L1201)
- [Logger](https://github.com/ClickHouse/clickhouse-js/blob/ebdcab7a5d00d53bbbe46cce45c14bbcfda93f0c/src/logger.ts)
## Supported formats
| Format | Input (array) | Input (stream) | Input (object) | Output (JSON) | Output (text) |
| ------------------------------------------ | ------------- | -------------- | -------------- | ------------- | ------------- |
| JSON | ❌ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONObjectEachRow | ❌ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONEachRow | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONStringsEachRow | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactEachRow | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactStringsEachRow | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNames | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNamesAndTypes | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNames | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNamesAndTypes | ✔️ | ✔️ | ❌️ | ✔️ | ✔️ |
| CSV | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| CSVWithNames | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| CSVWithNamesAndTypes | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| TabSeparated | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| TabSeparatedRaw | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| TabSeparatedWithNames | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| TabSeparatedWithNamesAndTypes | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| CustomSeparated | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| CustomSeparatedWithNames | ❌ | ✔️ | ❌ | ❌ | ✔️ |
| CustomSeparatedWithNamesAndTypes | ❌ | ✔️ | ❌ | ❌ | ✔️ |
The entire list of ClickHouse input and output formats is available [here](https://clickhouse.com/docs/en/interfaces/formats).
## Supported ClickHouse data types
| Type | Status | JS type |
| -------------- | --------------- | ------------------------------------- |
| UInt8/16/32 | ✔️ | number |
| UInt64/128/256 | ✔️❗- see below | string |
| Int8/16/32 | ✔️ | number |
| Int64/128/256 | ✔️❗- see below | string |
| Float32/64 | ✔️ | number |
| Decimal | ✔️❗- see below | number |
| Boolean | ✔️ | boolean |
| String | ✔️ | string |
| FixedString | ✔️ | string |
| UUID | ✔️ | string |
| Date32/64 | ✔️❗- see below | string |
| DateTime32/64 | ✔️❗- see below | string |
| Enum | ✔️ | string |
| LowCardinality | ✔️ | string |
| Array(T) | ✔️ | Array\<JS type for T> |
| JSON | ✔️ | object |
| Nested | ❌ | - |
| Tuple | ✔️ | Tuple |
| Nullable(T) | ✔️ | JS type for T or null |
| IPv4 | ✔️ | string |
| IPv6 | ✔️ | string |
| Point | ✔️ | [ number, number ] |
| Ring | ✔️ | Array\<Point> |
| Polygon | ✔️ | Array\<Ring> |
| MultiPolygon | ✔️ | Array\<Polygon> |
| Map(K, V) | ✔️ | Record\<JS type for K, JS type for V> |
The entire list of supported ClickHouse formats is available [here](https://clickhouse.com/docs/en/sql-reference/data-types/).
### Date* / DateTime* types caveats:
Since we use data streaming for inserts without the `VALUES` clause (which does additional type conversion), Date\* type columns can be only inserted as strings and not as Unix time epoch. It can be possibly changed with the future ClickHouse database releases. Please refer to the corresponding [integration tests](https://github.com/ClickHouse/clickhouse-js/blob/ba387d7f4ce375a60982ac2d99cb47391cf76cec/__tests__/integration/date_time.test.ts) for more examples.
### Decimal\* types caveats:
Since we do not use `VALUES` clause and there is no additional type conversion, it is not possible to insert Decimal* type columns as strings, only as numbers. This is a suboptimal approach as it might end in float precision loss. Thus, it is recommended to avoid JSON* formats when using Decimals as of now. Consider TabSeparated* / CSV* / CustomSeparated\* formats families for that kind of workflows. Please refer to the [data types tests](https://github.com/ClickHouse/clickhouse-js/blob/c1b70c82f525c39edb3ca1ee05cb5e6b43dba5b3/__tests__/integration/data_types.test.ts#L98-L131) for more concrete examples on how to avoid precision loss.
### NB: Int64, Int128, Int256, UInt64, UInt128, UInt256
Though the server can accept it as a number, it is by default returned as a string in JSON\* family output formats to avoid integer overflow as max values for these types are bigger than `Number.MAX_SAFE_INTEGER`.
This behavior, however, can be modified with [`output_format_json_quote_64bit_integers` setting](https://clickhouse.com/docs/en/operations/settings/settings/#output_format_json_quote_64bit_integers).
## ClickHouse client API overview
### Query
Used for most statements that can have a response, such as `SELECT`, or for sending DDLs such as `CREATE TABLE`. For data insertion, please consider using the dedicated method `insert` which is described next.
```ts
interface QueryParams {
// Query to execute that might return some data
// IMPORTANT: do not specify the FORMAT clause here
// use `format` param instead.
query: string
// Desired OUTPUT data format to be appended the query as ` FORMAT $format`
// It is extracted to the separate param
// as we may need to apply some additional request logic
// based on the desired format
format?: DataFormat
// ClickHouse settings that can be applied on query level, such as `date_time_input_format`
clickhouse_settings?: ClickHouseSettings
// See https://clickhouse.com/docs/en/interfaces/http/#cli-queries-with-parameters for more details
// IMPORTANT: that you should not prefix it with `param_` here, client will do that for you
query_params?: Record<string, unknown>
// A query can be aborted using this standard AbortSignal instance
// Please refer to the usage examples for more details
abort_signal?: AbortSignal
}
class ClickHouseClient {
query(params: QueryParams): Promise<Rows> {}
// ...
}
```
#### ResultSet response abstraction
Provides several convenience methods for data processing of select results in your application.
```ts
class ResultSet {
// Consume the entire stream and get the contents as a string
// Can be used with any DataFormat
// Should be called only once
text(): Promise<string> {}
// Consume the entire stream and get the contents as a JS object
// Can be used only with JSON formats
// Should be called only once
json<T>(): Promise<T> {}
// Returns a readable stream for responses that can be streamed (i.e. all except JSON)
// Every iteration provides an array of `Row` instances
// Should be called only once
// NB: if called for the second time, the second stream will be just empty
stream(): Stream.Readable {}
}
interface Row {
// Get the content of an individual row as a plain string
text(): string
// Get the content of an individual row as a JS object
json<T>(): T
}
```
### Insert
Primary method for data insertion. It can work with both `Stream.Readable` (all formats except `JSON`) and plain `Array<T>` (`JSON*` family formats only). It is recommended to avoid arrays in case of large inserts to reduce application memory consumption, and consider streaming for most of the use cases.
Should be awaited, but it does not return anything.
```ts
interface InsertParams<T> {
// Table name to insert the data into
table: string
// Stream.Readable will work for all formats except JSON
// Array will work only for JSON* formats
values: ReadonlyArray<T> | Stream.Readable
// Desired INPUT data format to be appended the statement as ` FORMAT $format`
// It is extracted to the separate param
// as we may need to apply some additional request logic
// based on the desired format
format?: DataFormat
// ClickHouse settings that can be applied on statement level, such as `insert_quorum`
clickhouse_settings?: ClickHouseSettings
// See https://clickhouse.com/docs/en/interfaces/http/#cli-queries-with-parameters for more details
// IMPORTANT: that you should not prefix it with `param_` here, client will do that for you
query_params?: Record<string, unknown>
// A query can be aborted using this standard AbortSignal instance
// Please refer to the usage examples for more details
abort_signal?: AbortSignal
}
class ClickHouseClient {
insert(params: InsertParams): Promise<void> {}
// ...
}
```
### Exec
Can be used for statements that do not have any output, when format clause is not applicable, or when you are not interested in the response at all. An example of such statement can be `CREATE TABLE` or `ALTER TABLE`.
Should be awaited.
Optionally, it returns a readable stream that can be consumed on the application side if you need it for some reason. But in that case you might consider using `query` instead.
```ts
interface ExecParams {
// Statement to execute
query: string
// ClickHouse settings that can be applied on query level, such as `date_time_input_format`
clickhouse_settings?: ClickHouseSettings
// See https://clickhouse.com/docs/en/interfaces/http/#cli-queries-with-parameters for more details
// IMPORTANT: that you should not prefix it with `param_` here, client will do that for you
query_params?: Record<string, unknown>
// A query can be aborted using this standard AbortSignal instance
// Please refer to the usage examples for more details
abort_signal?: AbortSignal
}
class ClickHouseClient {
exec(params: ExecParams): Promise<Stream.Readable> {}
// ...
}
```
### Ping
Might be useful to check the connectivity to the ClickHouse server. Returns `true` if server can be reached. Can throw a standard Node.js Error such as `ECONNREFUSED`.
```ts
class ClickHouseClient {
ping(): Promise<boolean> {}
// ...
}
```
### Close
Use it in your application graceful shutdown handler, as it properly closes all the open connections.
```ts
class ClickHouseClient {
close(): Promise<void> {}
// ...
}
```
## Usage examples

@@ -390,21 +31,4 @@

See also:
- [Memory leaks test using Brown University benchmarks files](https://github.com/ClickHouse/clickhouse-js/blob/60c484a3492420baed4b4c6c33cc0845262285e7/benchmarks/leaks/memory_leak_brown.ts#L72-L80)
## Known limitations
- Browser usage is not supported.
- There are no data mappers for the result sets, so only language primitives are used.
- There are some [Decimal* and Date* / DateTime\* data types caveats](#date--datetime-types-caveats).
- Nested data type is currently not officially supported.
## Tips for performance optimizations
- To reduce application memory consumption, consider using streams for large inserts when applicable.
- Node.js HTTP(s) Agent has infinite max open sockets by default. In some cases, you might want to limit that by using `ClickHouseClientConfigOptions.max_open_connections` setting.
- We have response (for example, select queries) compression enabled by default, but insert compression is disabled. When using large inserts, you might want to enable request compression as well. You can use `ClickHouseClientConfigOptions.compression.request` for that.
## Contributing
Check out our [contributing guide](./CONTRIBUTING.md).
dist/client.js.map

Sorry, the diff of this file is not supported yet

dist/connection/adapter/base_http_adapter.js.map

Sorry, the diff of this file is not supported yet

dist/connection/adapter/http_search_params.js.map

Sorry, the diff of this file is not supported yet

dist/connection/connection.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc