#### Node.js 전용 구성 매개변수
| 설정 | 설명 | 기본값 | 관련 항목 | |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **max\_open\_connections**?: number | 호스트별로 허용되는 연결 소켓의 최대 개수입니다. | `10` | - | |
| **tls**?: `{ **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer }` | TLS 인증서를 구성합니다. | - | [TLS 문서](/docs/ko/integrations/language-clients/js/index#tls-certificates-nodejs-only) | |
| **keep\_alive**?: `{ **enabled**?: boolean, **idle_socket_ttl**?: number }` | - | - | [Keep Alive 문서](/docs/ko/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only) | |
| **http\_agent**?: http.Agent | https.Agent
### URL 구성
### 연결
#### 연결 정보를 준비하십시오
HTTP(S)로 ClickHouse에 연결하려면 다음 정보가 필요합니다.
| 매개변수 | 설명 |
| ------------------------- | ---------------------------------------------------------- |
| `HOST` and `PORT` | 일반적으로 TLS를 사용하는 경우 포트는 8443, TLS를 사용하지 않는 경우 8123입니다. |
| `DATABASE NAME` | 기본적으로 `default`라는 이름의 데이터베이스가 제공되며, 연결할 데이터베이스 이름을 사용하십시오. |
| `USERNAME` and `PASSWORD` | 기본 사용자 이름은 `default`입니다. 사용 사례에 맞는 사용자 이름을 사용하십시오. |
ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다.
서비스를 선택한 다음 **Connect**를 클릭하십시오.
#### 연결 개요
이 클라이언트는 HTTP 또는 HTTPS 프로토콜을 통한 연결을 지원합니다. RowBinary 지원도 예정대로 진행 중입니다. 자세한 내용은 [관련 issue](https://github.com/ClickHouse/clickhouse-js/issues/216)를 참조하십시오.
다음 예시는 ClickHouse Cloud에 연결을 설정하는 방법을 보여줍니다. `url`(프로토콜 및 포트 포함)과 `password` 값은 환경 변수로 지정되어 있으며, `default` 사용자를 사용한다고 가정합니다.
**예시:** 구성에 환경 변수를 사용하여 Node.js Client 인스턴스를 생성합니다.
```ts theme={null}
import { createClient } from '@clickhouse/client'
const client = createClient({
url: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
username: process.env.CLICKHOUSE_USER ?? 'default',
password: process.env.CLICKHOUSE_PASSWORD ?? '',
})
```
클라이언트 리포지토리에는 환경 변수를 사용하는 여러 예시가 포함되어 있으며, 예를 들어 [ClickHouse Cloud에서 테이블을 생성하는 예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/schema-and-deployments/create_table_cloud.ts), [async 삽입을 사용하는 예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/async_insert.ts), 그 밖에도 많은 예시가 있습니다.
#### 연결 풀 (Node.js 전용)
모든 요청마다 연결을 설정하는 오버헤드를 피하기 위해 클라이언트는 Keep-Alive 메커니즘을 활용하여 재사용 가능한 ClickHouse 연결 풀을 생성합니다. 기본적으로 Keep-Alive는 활성화되어 있으며 연결 풀 크기는 `10`으로 설정되어 있지만, `max_open_connections` [구성 옵션](/docs/ko/integrations/language-clients/js/index#configuration)으로 변경할 수 있습니다.
사용자가 `max_open_connections: 1`을 설정하지 않는 한, 풀에 있는 동일한 연결이 이후 쿼리에도 사용된다고 보장할 수는 없습니다. 이런 설정이 필요한 경우는 드물지만, 임시 테이블을 사용하는 경우에는 필요할 수 있습니다.
관련 항목: [Keep-Alive 구성](/docs/ko/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only).
### 쿼리 ID
쿼리 또는 SQL 문(`command`, `exec`, `insert`, `select`)을 전송하는 모든 메서드는 결과에 `query_id`를 제공합니다. 이 고유 식별자는 클라이언트가 각 쿼리마다 할당하며, [서버 구성](/docs/ko/reference/settings/server-settings/settings)에서 활성화되어 있다면 `system.query_log`에서 데이터를 조회하거나,
장시간 실행되는 쿼리를 취소하는 데 유용할 수 있습니다([예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/troubleshooting/cancel_query.ts) 참조). 필요한 경우 사용자가 `command`/`query`/`exec`/`insert` 메서드의 파라미터에서 `query_id`를 재정의할 수 있습니다.
### 모든 클라이언트 메서드의 기본 매개변수
모든 클라이언트 메서드([query](/docs/ko/integrations/language-clients/js/index#query-method)/[command](/docs/ko/integrations/language-clients/js/index#command-method)/[insert](/docs/ko/integrations/language-clients/js/index#insert-method)/[exec](/docs/ko/integrations/language-clients/js/index#exec-method))에 공통으로 적용할 수 있는 매개변수가 몇 가지 있습니다.
```ts theme={null}
interface BaseQueryParams {
// ClickHouse settings that can be applied on query level.
clickhouse_settings?: ClickHouseSettings
// Parameters for query binding.
query_params?: Record
### 쿌리 메서드
응답이 있는 대부분의 SQL 문(예: `SELECT`)에 사용하며, `CREATE TABLE`과 같은 DDL을 전송할 때도 사용합니다. 이 메서드는 await해야 하며, 반환된 결과 집합는 애플리케이션에서 소비하는 것을 전제로 합니다.
#### 결과 집합 및 행 추상화
`ResultSet`은 애플리케이션에서 데이터를 처리할 때 사용할 수 있는 여러 편의 메서드를 제공합니다.
Node.js `ResultSet` 구현은 내부적으로 `Stream.Readable`을 사용하며, 웹 버전은 Web API `ReadableStream`을 사용합니다.
`ResultSet`에서 `text` 또는 `json` 메서드를 호출해 `ResultSet`을 소비하고, 쿼리가 반환한 전체 행 집합을 메모리에 로드할 수 있습니다.
`ResultSet`은 응답 스트림을 열린 상태로 유지하므로 그동안 기본 연결이 계속 사용 중 상태로 남습니다. 따라서 가능한 한 빨리 `ResultSet` 소비를 시작해야 합니다. 클라이언트는 애플리케이션의 과도한 메모리 사용량을 방지하기 위해 들어오는 데이터를 버퍼링하지 않습니다.
또는 한 번에 메모리에 담기 어려울 정도로 크다면 `stream` 메서드를 호출해 스트리밍 모드로 데이터를 처리할 수 있습니다. 이 경우 각 응답 청크는 상대적으로 작은 행 배열로 변환되며(이 배열의 크기는 클라이언트가 server로부터 받는 특정 청크의 크기와 개별 행의 크기에 따라 달라질 수 있습니다), 청크별로 하나씩 처리됩니다.
환경에 따라 스트리밍에 가장 적합한 포맷을 결정하려면 [지원되는 데이터 포맷](/docs/ko/integrations/language-clients/js/index#supported-data-formats) 목록을 참조하십시오. 예를 들어 JSON 객체를 스트리밍하려는 경우 [JSONEachRow](/docs/ko/reference/formats/JSON/JSONEachRow)를 선택하면 각 행이 JS 객체로 파싱됩니다. 또는 더 압축된 [JSONCompactColumns](/docs/ko/reference/formats/JSON/JSONCompactColumns) 포맷을 선택하면 각 행이 값의 간결한 배열이 됩니다. 관련 항목: [스트리밍 파일](/docs/ko/integrations/language-clients/js/index#streaming-files-nodejs-only).
### 삽입 메서드
데이터를 삽입할 때 사용하는 주요 메서드입니다.
```ts theme={null}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise
#### Node.js에서의 삽입 메서드와 스트리밍
`insert` 메서드에 지정한 [data format](/docs/ko/integrations/language-clients/js/index#supported-data-formats)에 따라 `Stream.Readable` 또는 일반 `Array
#### 웹 버전 제한 사항
현재 `@clickhouse/client-web`에서 삽입은 `Array
### command 메서드
출력이 없는 SQL 문, 포맷 절을 적용할 수 없는 경우, 또는 응답 자체가 필요하지 않은 경우에 사용할 수 있습니다. 이러한 SQL 문의 예시로는 `CREATE TABLE` 또는 `ALTER TABLE`이 있습니다.
반드시 await해야 합니다.
응답 스트림은 즉시 폐기되며, 이에 따라 내부 소켓이 해제됩니다.
```ts theme={null}
interface CommandParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface CommandResult {
query_id: string
}
interface ClickHouseClient {
command(params: CommandParams): Promise
### Exec 메서드
`query`/`insert`에 맞지 않는 사용자 정의 쿼리가 있고
결과를 받아야 한다면 `command` 대신 `exec`를 사용할 수 있습니다.
`exec`는 애플리케이션 측에서 반드시 소비하거나 폐기해야 하는 readable stream을 반환합니다.
```ts theme={null}
interface ExecParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface ClickHouseClient {
exec(params: ExecParams): Promise
### Ping
연결 상태를 확인하는 데 사용되는 `ping` 메서드는 서버에 연결할 수 있으면 `true`를 반환합니다.
서버에 연결할 수 없는 경우 결과에는 원인이 된 오류도 함께 포함됩니다.
```ts theme={null}
type PingResult =
| { success: true }
| { success: false; error: Error }
/** Parameters for the health-check request - using the built-in `/ping` endpoint.
* This is the default behavior for the Node.js version. */
export type PingParamsWithEndpoint = {
select: false
/** AbortSignal instance to cancel a request in progress. */
abort_signal?: AbortSignal
/** Additional HTTP headers to attach to this particular request. */
http_headers?: Record
### 닫기 (Node.js 전용)
열려 있는 모든 연결을 닫고 리소스를 해제합니다. 웹 버전에서는 no-op입니다.
```ts theme={null}
await client.close()
```
## 파일 스트리밍 (Node.js 전용)
클라이언트 리포지토리에는 널리 사용되는 데이터 포맷(NDJSON, CSV, Parquet)에 대한 여러 파일 스트리밍 예시가 있습니다.
* [NDJSON 파일에서 스트리밍](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_ndjson.ts)
* [CSV 파일에서 스트리밍](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_csv.ts)
* [Parquet 파일에서 스트리밍](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_parquet.ts)
* [Parquet 파일로 스트리밍](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts)
다른 포맷의 파일로 스트리밍하는 방법도 Parquet와 비슷합니다.
차이점은 `query` 호출에 사용하는 포맷(`JSONEachRow`, `CSV` 등)과 출력 파일 이름뿐입니다.
## 지원되는 데이터 포맷
클라이언트는 JSON 또는 텍스트 데이터 포맷을 처리합니다.
`format`을 JSON 계열 포맷(`JSONEachRow`, `JSONCompactEachRow` 등) 중 하나로 지정하면, 클라이언트는 wire를 통한 통신 중 데이터를 serialize 및 deserialize합니다.
"raw" 텍스트 포맷(`CSV`, `TabSeparated`, `CustomSeparated` 계열)으로 제공된 데이터는 추가 변환 없이 wire를 통해 전송됩니다.
## 지원되는 ClickHouse 데이터 타입
### Date/Date32 타입 관련 주의사항
클라이언트가 값을 삽입할 때 추가적인 타입 변환을 수행하지 않으므로, `Date`/`Date32` 타입 컬럼에는 문자열만 삽입할 수 있습니다.
**예시:** `Date` 타입 값을 삽입하는 예시입니다.
[소스 코드](https://github.com/ClickHouse/clickhouse-js/blob/ba387d7f4ce375a60982ac2d99cb47391cf76cec/__tests__/integration/date_time.test.ts)
```ts theme={null}
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
```
하지만 `DateTime` 또는 `DateTime64` 컬럼을 사용하는 경우에는 문자열과 JS Date 객체를 모두 사용할 수 있습니다. JS Date 객체는 `date_time_input_format`을 `best_effort`로 설정하면 `insert`에 그대로 전달할 수 있습니다. 자세한 내용은 이 [예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_js_dates.ts)를 참조하십시오.
### Decimal\* 타입 유의사항
`JSON*` 계열 포맷을 사용해 Decimal을 삽입할 수 있습니다. 다음과 같이 정의된 테이블이 있다고 가정합니다.
```sql theme={null}
CREATE TABLE my_table
(
id UInt32,
dec32 Decimal(9, 2),
dec64 Decimal(18, 3),
dec128 Decimal(38, 10),
dec256 Decimal(76, 20)
)
ENGINE MergeTree()
ORDER BY (id)
```
문자열 형식으로 정밀도 손실 없이 값을 삽입할 수 있습니다:
```ts theme={null}
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
```
하지만 `JSON*` 포맷으로 데이터를 쿼리할 때 ClickHouse는 기본적으로 Decimal을 *숫자*로 반환하므로 정밀도가 손실될 수 있습니다. 이를 방지하려면 쿼리에서 Decimal을 문자열로 CAST할 수 있습니다:
```ts theme={null}
await client.query({
query: `
SELECT toString(dec32) AS decimal32,
toString(dec64) AS decimal64,
toString(dec128) AS decimal128,
toString(dec256) AS decimal256
FROM my_table
`,
format: 'JSONEachRow',
})
```
자세한 내용은 [이 예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_decimals.ts)를 확인하십시오.
### 정수 타입: Int64, Int128, Int256, UInt64, UInt128, UInt256
server는 이를 숫자로 받을 수 있지만, 이러한 타입의 최댓값이 `Number.MAX_SAFE_INTEGER`보다 크기 때문에 정수 오버플로우를 방지하기 위해 `JSON*` 계열 출력 형식에서는 문자열로 반환됩니다.
하지만 이 동작은
[`output_format_json_quote_64bit_integers` 설정](/docs/ko/reference/settings/formats#output_format_json_quote_64bit_integers)
으로 변경할 수 있습니다.
**예시:** 64비트 숫자에 대한 JSON 출력 형식을 조정합니다.
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
})
expect(await resultSet.json()).toEqual([ { number: '0' } ])
```
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
})
expect(await resultSet.json()).toEqual([ { number: 0 } ])
```
## ClickHouse 설정
클라이언트는 [settings](/docs/ko/reference/settings/session-settings)
메커니즘을 통해 ClickHouse의 동작을 조정할 수
있습니다.
설정은 클라이언트 인스턴스 수준에서 지정할 수 있으며, 이렇게 하면
ClickHouse로 전송되는 모든 요청에 적용됩니다:
```ts theme={null}
const client = createClient({
clickhouse_settings: {}
})
```
또는 설정을 요청 수준에서 구성할 수 있습니다:
```ts theme={null}
client.query({
clickhouse_settings: {}
})
```
지원되는 모든 ClickHouse 설정이 포함된 타입 선언 파일은
[여기](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/settings.ts)에서 확인할 수 있습니다.
## 심화 주제
### 매개변수가 있는 쿼리
매개변수가 있는 쿼리를 만들고 클라이언트 애플리케이션에서 해당 매개변수에 값을 전달할 수 있습니다. 이렇게 하면 클라이언트 측에서
특정 동적 값으로 쿼리를 포맷할 필요가 없습니다.
평소처럼 쿼리를 작성한 다음, 앱 매개변수에서 쿼리로 전달할 값을 중괄호로 묶어
다음 형식으로 넣습니다:
```text theme={null}
{
### 압축
참고: 요청 압축은 현재 Web 버전에서 사용할 수 없습니다. 응답 압축은 정상적으로 작동합니다. Node.js 버전에서는 둘 다 지원합니다.
wire를 통해 대규모 데이터셋을 처리하는 데이터 애플리케이션은 압축을 활성화하면 이점을 얻을 수 있습니다. 현재는 [zlib](https://nodejs.org/docs/latest-v14.x/api/zlib.html)을 사용하는 `GZIP`만 지원됩니다.
```typescript theme={null}
createClient({
compression: {
response: true,
request: true
}
})
```
구성 매개변수는 다음과 같습니다.
* `response: true`는 ClickHouse 서버가 압축된 응답 본문을 반환하도록 합니다. 기본값: `response: false`
* `request: true`는 클라이언트 요청 본문의 압축을 활성화합니다. 기본값: `request: false`
### 로깅 (Node.js 전용)
### TLS 인증서 (Node.js 전용)
Node.js 클라이언트는 선택적으로 basic(인증 기관(Certificate Authority)만 사용하는)
및 mutual(인증 기관(Certificate Authority)과 클라이언트 인증서를 사용하는) TLS를 모두 지원합니다.
인증서가 `certs` 폴더에 있고
CA 파일 이름이 `CA.pem`이라고 가정할 때의 basic TLS 구성 예시는 다음과 같습니다:
```ts theme={null}
const client = createClient({
url: 'https://
### Keep-alive 설정 (Node.js 전용)
클라이언트는 기본적으로 하위 `HTTP agent`에서 Keep-Alive를 활성화합니다. 즉, 연결된 소켓은 이후 request에 재사용되며 `Connection: keep-alive` header가 전송됩니다. 유휴 상태인 소켓은 기본적으로 2500밀리초 동안 연결 풀에 유지됩니다([이 옵션 조정에 관한 참고 사항](/docs/ko/integrations/language-clients/js/index#adjusting-idle_socket_ttl) 참조).
`keep_alive.idle_socket_ttl` 값은 server/LB 구성보다 상당히 낮게 설정해야 합니다. 주된 이유는 HTTP/1.1에서는 server가 클라이언트에 알리지 않고 소켓을 닫을 수 있으므로, server 또는 load balancer가 클라이언트보다 *먼저* 연결을 닫으면 클라이언트가 닫힌 소켓을 재사용하려고 시도할 수 있고, 그 결과 `socket hang up` 오류가 발생할 수 있기 때문입니다.
`keep_alive.idle_socket_ttl`을 수정하는 경우, 이 값은 server/LB의 Keep-Alive 구성과 항상 맞춰 두어야 하며, server가 열린 연결을 먼저 닫지 않도록 반드시 그보다 **항상 낮아야 합니다**.
#### `idle_socket_ttl` 조정
클라이언트는 `keep_alive.idle_socket_ttl`을 2500밀리초로 설정합니다. 이는 가장 안전한 기본값으로 볼 수 있기 때문입니다. 서버 측 `keep_alive_timeout`은 `config.xml`을 수정하지 않아도 [ClickHouse 23.11 이전 버전에서는 3초까지 낮게 설정될 수 있습니다](https://github.com/ClickHouse/ClickHouse/commit/1685cdcb89fe110b45497c7ff27ce73cc03e82d1).
#### 문제 해결
최신 버전의 클라이언트를 사용 중인데도 `socket hang up` 오류가 발생한다면, 다음 방법으로 문제를 해결할 수 있습니다.
* 최소 `WARN` 로그 레벨(기본값)로 로그를 활성화하십시오. 그러면 application code에 소비되지 않았거나 처리되지 않은 채 남아 있는 스트림이 있는지 확인할 수 있습니다. 이러한 경우 전송 계층에서 WARN 수준으로 로그를 남기며, 이 상태가 서버에서 소켓을 닫는 원인이 될 수 있습니다. 로깅은 다음과 같이 클라이언트 구성에서 활성화할 수 있습니다.
```ts theme={null}
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
```
* 원하는 구성이 올바른 클라이언트 인스턴스에 적용되었는지 확인하십시오. 애플리케이션에 클라이언트 인스턴스가 여러 개 있다면, 쿼리에 사용하는 인스턴스에 올바른 `keep_alive.idle_socket_ttl` 값이 설정되어 있는지 다시 확인하십시오.
* 클라이언트 구성에서 `keep_alive.idle_socket_ttl` 설정값을 500밀리초 줄이십시오. 특정 상황에서는, 예를 들어 클라이언트와 서버 사이의 네트워크 지연 시간이 높은 경우, 서버가 곧 닫으려는 소켓을 송신 요청이 할당받는 상황을 피하는 데 도움이 될 수 있습니다.
* 이 오류가 데이터 입출력이 없는 장시간 실행 쿼리 중 발생한다면(예: 장시간 실행되는 `INSERT FROM SELECT`), 로드 밸런서(load balancer) 또는 다른 네트워크 구성 요소가 장시간 유지되는 연결이나 오래 실행되는 요청을 닫고 있기 때문일 수 있습니다. 다음 ClickHouse 설정을 조합해 사용하면, 장시간 실행 쿼리 중에도 일부 데이터가 들어오도록 강제해 볼 수 있습니다.
```ts theme={null}
const client = createClient({
// 여기서는 실행 시간이 5분을 넘는 쿼리가 일부 있다고 가정합니다
request_timeout: 400_000,
/** 이 설정들을 함께 사용하면, 데이터 입출력이 없는 장시간 실행 쿼리의 경우
* `INSERT FROM SELECT` 및 이와 유사한 쿼리에서 LB 타임아웃 문제를 피할 수 있습니다.
* 연결이 LB에 의해 유휴 상태로 표시되어 갑자기 닫힐 수 있기 때문입니다.
* 여기서는 LB의 유휴 연결 타임아웃이 120초라고 가정하므로, "안전한" 값으로 110초를 설정합니다. */
clickhouse_settings: {
send_progress_in_http_headers: 1,
http_headers_progress_interval_ms: '110000', // UInt64이므로 문자열로 전달해야 합니다
},
})
```
다만 최근 Node.js 버전에서는 수신한 헤더의 총 크기가 16KB로 제한된다는 점을 유의하십시오. 일정 수 이상의 progress 헤더를 받으면(테스트에서는 약 70\~80개), 예외가 발생합니다.
전송 중 대기 시간을 완전히 피하는 전혀 다른 접근 방식도 사용할 수 있습니다. 연결이 끊겨도 mutation이 취소되지 않는 HTTP 인터페이스 "기능"을 활용하는 방식입니다. 자세한 내용은 [이 예시(2부)](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/long_running_queries_timeouts.ts)를 참조하십시오.
* Keep-Alive 기능은 완전히 비활성화할 수도 있습니다. 이 경우 클라이언트는 모든 요청에 `Connection: close` 헤더도 추가하며, 기반 HTTP 에이전트는 연결을 재사용하지 않습니다. 유휴 소켓이 없으므로 `keep_alive.idle_socket_ttl` 설정은 무시됩니다. 이 방식은 모든 요청마다 새 연결을 설정하므로 추가 오버헤드가 발생합니다.
```ts theme={null}
const client = createClient({
keep_alive: {
enabled: false,
},
})
```
* `curl`을 사용한 간단한 명령줄 테스트를 동일한 ClickHouse 인스턴스와 동일한 네트워크 경로(즉, 같은 머신 또는 네트워크 세그먼트, 예: Kubernetes pod)에서 실행하여, Node.js 자체를 포함한 나머지 네트워크 스택의 잠재적 문제를 배제해 보십시오.
```sh theme={null}
curl -is --user '
### 읽기 전용 사용자
[readonly=1 사용자](/docs/ko/concepts/features/configuration/settings/permissions-for-queries#readonly)와 함께 클라이언트를 사용하는 경우, `enable_http_compression` 설정이 필요하므로 응답 압축을 활성화할 수 없습니다. 다음 구성은 오류를 발생시킵니다:
```ts theme={null}
const client = createClient({
compression: {
response: true, // won't work with a readonly=1 user
},
})
```
readonly=1 사용자의 제한 사항을 더 자세히 보여 주는 [예시](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/security/read_only_user.ts)를 참조하십시오.
### 경로명이 포함된 프록시
ClickHouse instance가 프록시 뒤에 있고 URL에 경로명이 포함되어 있는 경우(예: [http://proxy:8123/clickhouse\_server)에는](http://proxy:8123/clickhouse\_server\)에는) `pathname` 구성 옵션에 `clickhouse_server`를 지정하십시오(앞에 슬래시가 있어도 되고 없어도 됩니다). 그렇지 않고 이를 `url`에 직접 지정하면 `database` 옵션으로 간주됩니다. 여러 세그먼트도 지원합니다. 예: `/my_proxy/db`.
```ts theme={null}
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
```
### 인증이 적용된 리버스 프록시
ClickHouse 배포 앞단에 인증이 적용된 리버스 프록시가 있는 경우, 해당 리버스 프록시에 필요한 헤더를 전달하도록 `http_headers` 설정을 사용할 수 있습니다:
```ts theme={null}
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
```
### 사용자 지정 HTTP/HTTPS 에이전트(실험적, Node.js 전용)
#### 사용자 지정 Agent 사용 예시
인증서 없이 사용자 지정 HTTP 또는 HTTPS Agent를 사용하는 예시:
```ts theme={null}
const agent = new http.Agent({ // or https.Agent
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
})
const client = createClient({
http_agent: agent,
})
```
basic TLS와 CA certificate를 사용하는 custom HTTPS Agent:
```ts theme={null}
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
```
mutual TLS와 함께 사용자 지정 HTTPS Agent 사용:
```ts theme={null}
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
'X-ClickHouse-SSL-Certificate-Auth': 'on',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
```
인증서 *및* 사용자 지정 *HTTPS* Agent를 사용하는 경우, TLS 헤더와 충돌할 수 있으므로 `set_basic_auth_header` 설정(1.2.0에 도입됨)으로 기본 Authorization 헤더를 비활성화해야 할 가능성이 높습니다. 모든 TLS 헤더는 수동으로 지정해야 합니다.
## 알려진 제한 사항 (Node.js/web)
* 결과 집합에 대한 데이터 매퍼가 없으므로 언어 기본 타입만 사용됩니다. 일부 데이터 타입 매퍼는 [RowBinary 포맷 지원](https://github.com/ClickHouse/clickhouse-js/issues/216)과 함께 추가될 예정입니다.
* 일부 [Decimal\* 및 Date\* / DateTime\* 데이터 타입 관련 유의 사항](/docs/ko/integrations/language-clients/js/index#datedate32-types-caveats)이 있습니다.
* JSON\* 계열 포맷을 사용할 때 Int32보다 큰 숫자는 문자열로 표현됩니다. Int64+ 타입의 최댓값이 `Number.MAX_SAFE_INTEGER`보다 크기 때문입니다. 자세한 내용은 [Integral types](/docs/ko/integrations/language-clients/js/index#integral-types-int64-int128-int256-uint64-uint128-uint256) 섹션을 참조하십시오.
## 알려진 제한 사항 (web)
* `select` 쿼리의 스트리밍은 작동하지만, 삽입에는 사용할 수 없습니다(타입 수준에서도 마찬가지입니다).
* 요청 압축은 비활성화되어 있고 구성은 무시됩니다. 응답 압축은 작동합니다.
* 아직 로깅을 지원하지 않습니다.
## 성능 최적화를 위한 팁
* 애플리케이션 메모리 사용량을 줄이려면, 해당되는 경우 대용량 삽입(예: 파일에서)과 select 쿼리에 스트림을 사용하는 방안을 고려하십시오. 이벤트 listener 및 이와 유사한 사용 사례에서는 [async inserts](/docs/ko/concepts/features/operations/insert/asyncinserts)도 좋은 선택지가 될 수 있으며, 클라이언트 측 배칭을 최소화하거나 완전히 없앨 수도 있습니다. Async insert 예시는 [client 리포지토리](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node)에서 확인할 수 있으며, 파일 이름 prefix는 `async_insert_`입니다.
* 클라이언트는 기본적으로 request 또는 response 압축(Compression)을 활성화하지 않습니다. 하지만 대용량 데이터셋을 select하거나 삽입할 때는 `ClickHouseClientConfigOptions.compression`을 통해 이를 활성화하는 것을 고려할 수 있습니다(`request` 또는 `response`만, 혹은 둘 다 설정 가능).
* 압축(Compression)에는 상당한 성능 비용이 따릅니다. 이를 `request` 또는 `response`에 활성화하면 각각 삽입 또는 select 속도에 부정적인 영향을 주지만, 애플리케이션이 전송하는 네트워크 트래픽 양은 줄일 수 있습니다.
## 문의하기
질문이 있거나 도움이 필요하면 [Community Slack](https://clickhouse.com/slack)의 (`#clickhouse-js` 채널) 또는 [GitHub issues](https://github.com/ClickHouse/clickhouse-js/issues)를 통해 편하게 문의하세요.