{"id":22693085,"url":"https://github.com/depyronick/nestjs-clickhouse","last_synced_at":"2025-07-27T14:08:45.845Z","repository":{"id":41822484,"uuid":"427321599","full_name":"depyronick/nestjs-clickhouse","owner":"depyronick","description":"ClickHouse Client Module for Nest Framework (node.js) ","archived":false,"fork":false,"pushed_at":"2024-10-17T11:44:12.000Z","size":78,"stargazers_count":52,"open_issues_count":1,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-20T02:49:59.960Z","etag":null,"topics":["clickhouse","clickhouse-client","javascript","nestjs","nodejs","nosql","sql","typescript"],"latest_commit_sha":null,"homepage":"https://clickhouse.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/depyronick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-12T10:38:21.000Z","updated_at":"2025-07-16T13:11:51.000Z","dependencies_parsed_at":"2024-06-18T21:34:51.381Z","dependency_job_id":"c697285c-55f2-48a1-8c9b-b7aa8fc52f85","html_url":"https://github.com/depyronick/nestjs-clickhouse","commit_stats":{"total_commits":47,"total_committers":3,"mean_commits":"15.666666666666666","dds":0.04255319148936165,"last_synced_commit":"4efdef2a89bb912c1efad78052fd72dc1bab8e38"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/depyronick/nestjs-clickhouse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fnestjs-clickhouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fnestjs-clickhouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fnestjs-clickhouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fnestjs-clickhouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/depyronick","download_url":"https://codeload.github.com/depyronick/nestjs-clickhouse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fnestjs-clickhouse/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267368932,"owners_count":24076093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","clickhouse-client","javascript","nestjs","nodejs","nosql","sql","typescript"],"created_at":"2024-12-10T02:08:58.101Z","updated_at":"2025-07-27T14:08:45.824Z","avatar_url":"https://github.com/depyronick.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Description\n\n[ClickHouse®](https://clickhouse.com/) is an open-source, high performance columnar OLAP database management system for real-time analytics using SQL. ClickHouse combined with [TypeScript](https://www.typescriptlang.org/) helps you develop better type safety with your ClickHouse queries, giving you end-to-end typing.\n\n## Installation\n\nInstall the following package:\n\n```bash\n$ npm i --save @depyronick/nestjs-clickhouse\n```\n\n## Quick Start\n\n\u003e This NestJS module is a wrapper for **[@depyronick/clickhouse-client](https://github.com/depyronick/clickhouse-client '@depyronick/clickhouse-client')**. You can find latest documentation for methods there.\n\n### Importing the module\n\nOnce the installation process is complete, we can import the `ClickHouseModule` into the root `AppModule`.\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { ClickHouseModule } from '@depyronick/nestjs-clickhouse';\n\n@Module({\n  imports: [\n    ClickHouseModule.register([\n      {\n        name: 'ANALYTICS_SERVER',\n        host: '127.0.0.1',\n        password: '7h3ul71m473p4555w0rd',\n      },\n    ]),\n  ],\n})\nexport class AppModule {}\n```\n\nThe `register()` method will register a ClickHouse client with the specified connection options.\n\nSee **[ClickHouseOptions](https://github.com/depyronick/clickhouse-client/blob/main/src/client/interfaces/ClickHouseClientOptions.ts 'ClickHouseOptions')** object for more information.\n\nEach registered client should have an unique `name` definition. The default value for `name` property is `CLICKHOUSE_DEFAULT`. This property will be used as an injection token.\n\n### Interacting with ClickHouse Client\n\nTo interact with the ClickHouse server that you have just registered, inject it to your class using the injection token.\n\n```typescript\nconstructor(\n\t@Inject('ANALYTICS_SERVER')\n\tprivate analyticsServer: ClickHouseClient\n) {}\n```\n\n\u003e The `ClickHouseClient` class is imported from the `@depyronick/nestjs-clickhouse`.\n\n## Examples\n\n\u003e ⚠️ These are only a few examples, please see [@depyronick/clickhouse-client](https://github.com/depyronick/clickhouse-client) for up to date methods, like **Parametrized Query Capabilities**.\n\n#### `ClickHouseClient.query\u003cT\u003e(query: string): Observable\u003cT\u003e`\n\n```typescript\nimport { Inject, Injectable } from '@nestjs/common';\nimport { ClickHouseClient } from '@depyronick/nestjs-clickhouse';\n\ninterface VisitsTable {\n  timestamp: number;\n  ip: string;\n  userAgent: string;\n  os: string;\n  version: string;\n  // ...\n}\n\n@Injectable()\nexport class AppService {\n  constructor(\n    @Inject('ANALYTICS_SERVER')\n    private readonly analyticsServer: ClickHouseClient,\n  ) {\n    this.analyticsServer\n      .query\u003cVisitsTable\u003e('SELECT * FROM visits LIMIT 10')\n      .subscribe({\n        error: (err: any): void =\u003e {\n          // called when an error occurred during query\n        },\n        next: (row): void =\u003e {\n          // called for each row\n          // the type of row property here is VisitsTable\n        },\n        complete: (): void =\u003e {\n          // called when stream is completed\n        },\n      });\n  }\n}\n```\n\n#### `ClickHouseClient.queryPromise\u003cT\u003e(query: string): Promise\u003cT[]\u003e`\n\n```typescript\nimport { Inject, Injectable } from '@nestjs/common';\nimport { ClickHouseClient } from '@depyronick/nestjs-clickhouse';\n\ninterface VisitsTable {\n  timestamp: number;\n  ip: string;\n  userAgent: string;\n  os: string;\n  version: string;\n  // ...\n}\n\n@Injectable()\nexport class AppService {\n  constructor(\n    @Inject('ANALYTICS_SERVER')\n    private readonly analyticsServer: ClickHouseClient,\n  ) {\n    this.analyticsServer\n      .queryPromise\u003cVisitsTable\u003e('SELECT * FROM visits LIMIT 10')\n      .then((rows: VisitsTable[]) =\u003e {\n        // all retrieved rows\n      })\n      .catch((err) =\u003e {\n        // called when an error occurred during query\n      });\n\n    // or\n\n    const rows = await this.analyticsServer.queryPromise(\n      'SELECT * FROM visits LIMIT 10',\n    );\n  }\n}\n```\n\n#### `ClickHouseClient.insert\u003cT\u003e(table: string, data: T[]): Observable\u003cany\u003e`\n\nThe `insert` method accepts two inputs.\n\n- `table` is the name of the table that you'll be inserting data to.\n  - Table value could be prefixed with database like `analytics_db.visits`.\n- `data: T[]` array of JSON objects to insert.\n\n```typescript\nimport { Inject, Injectable } from '@nestjs/common';\nimport { ClickHouseClient } from '@depyronick/nestjs-clickhouse';\n\ninterface VisitsTable {\n  timestamp: number;\n  ip: string;\n  userAgent: string;\n  os: string;\n  version: string;\n  // ...\n}\n\n@Injectable()\nexport class AppService {\n  constructor(\n    @Inject('ANALYTICS_SERVER')\n    private readonly analyticsServer: ClickHouseClient,\n  ) {\n    this.analyticsServer\n      .insert\u003cVisitsTable\u003e('visits', [\n        {\n          timestamp: new Date().getTime(),\n          ip: '127.0.0.1',\n          os: 'OSX',\n          userAgent:\n            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/95.0.4638.69 Safari/537.36',\n          version: '1.0.0',\n        },\n      ])\n      .subscribe({\n        error: (err: any): void =\u003e {\n          // called when an error occurred during insert\n        },\n        next: (): void =\u003e {\n          // currently next does not emits anything for inserts\n        },\n        complete: (): void =\u003e {\n          // called when insert is completed\n        },\n      });\n  }\n}\n```\n\n## Multiple Clients\n\nYou can register multiple clients in the same application as follows:\n\n```typescript\n@Module({\n  imports: [\n    ClickHouseModule.register([\n      {\n        name: 'ANALYTICS_SERVER',\n        host: '127.0.0.1',\n        password: '7h3ul71m473p4555w0rd',\n      },\n      {\n        name: 'CHAT_SERVER',\n        host: '192.168.1.110',\n        password: 'ch5ts3rv3Rp455w0rd',\n      },\n    ]),\n  ],\n  controllers: [AppController],\n  providers: [AppService],\n})\nexport class AppModule {}\n```\n\nThen you can interact with these servers using their assigned injection tokens.\n\n```typescript\nconstructor(\n    @Inject('ANALYTICS_SERVER')\n    private analyticsServer: ClickHouseClient,\n\n    @Inject('CHAT_SERVER')\n    private chatServer: ClickHouseClient\n) { }\n```\n\n## Async Registration \u0026 Async Providers\n\nFor example, if you want to wait for the application to accept new connections until the necessary configuration settings for clickhouse are received from an asynchronous target, you can use the `registerAsync` method.\n\n```typescript\nimport { Inject, Module } from '@nestjs/common';\nimport { ClickHouseModule } from '@depyronick/nestjs-clickhouse';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\n\n@Module({\n  imports: [\n    ConfigModule.forRoot({\n      envFilePath: ['.development.env'],\n      isGlobal: true,\n    }),\n    ClickHouseModule.registerAsync({\n      useFactory: (config: ConfigService) =\u003e {\n        return {\n          host: config.get('CH_HOST'),\n          database: config.get('CH_DB'),\n          password: config.get('CH_PWD'),\n          username: config.get('CH_USERNAME'),\n        };\n      },\n      inject: [ConfigService],\n    }),\n  ],\n  controllers: [],\n  providers: [],\n})\nexport class AppModule {}\n```\n\nThen you can use the `CLICKHOUSE_ASYNC_INSTANCE_TOKEN` to inject the `ClickHouseClient` with the asynchronous configuration that you just provided.\n\n```typescript\nimport {\n  ClickHouseClient,\n  CLICKHOUSE_ASYNC_INSTANCE_TOKEN,\n} from '@depyronick/nestjs-clickhouse';\n\nexport class AppModule {\n  constructor(\n    @Inject(CLICKHOUSE_ASYNC_INSTANCE_TOKEN)\n    private readonly chWithAsyncConfig: ClickHouseClient,\n  ) {\n    this.chWithAsyncConfig\n      .query('SELECT * FROM [TABLE] LIMIT 1')\n      .subscribe((row) =\u003e console.log('row', row));\n  }\n}\n```\n\nIf you want to define more than one `ClickHouseClient` using `registerAsync` method, you will need to create different modules, and inject `CLICKHOUSE_ASYNC_INSTANCE_TOKEN` into feature modules.\n\nBut you don't have to use `registerAsync` method to create asynchronous `ClickHouseClient` instances. You can also use custom providers:\n\n```typescript\nimport { Inject, Module } from '@nestjs/common';\nimport { ClickHouseClient } from '@depyronick/nestjs-clickhouse';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\n\n@Module({\n  imports: [\n    ConfigModule.forRoot({\n      envFilePath: ['.development.env'],\n      isGlobal: true,\n    }),\n  ],\n  controllers: [],\n  providers: [\n    {\n      provide: 'CH2',\n      useFactory: (config: ConfigService) =\u003e {\n        return new ClickHouseClient({\n          host: config.get('CH2_HOST'),\n          database: config.get('CH2_DB'),\n          password: config.get('CH2_PWD'),\n          username: config.get('CH2_USERNAME'),\n        });\n      },\n      inject: [ConfigService],\n    },\n  ],\n})\nexport class AppModule {\n  constructor(\n    @Inject('CH2')\n    private readonly clickhouse: ClickHouseClient,\n  ) {\n    this.clickhouse\n      .query('SELECT * FROM [TABLE] LIMIT 1')\n      .subscribe((row) =\u003e console.log('row', row));\n  }\n}\n```\n\nWith custom providers, you can create as many as asynchronously loaded clients with the name you `provide`d.\n\n## Notes\n\n- This repository will be actively maintained and improved.\n- Planning to implement TCP protocol, if ClickHouse decides to [documentate](https://clickhouse.com/docs/en/interfaces/tcp/ 'documentate') it.\n- Planning to implement inserts with streams.\n- This library supports http response compressions such as brotli, gzip and deflate.\n\n## Support\n\nNest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).\n\n## Stay in touch\n\n- Author - [Ali Demirci](https://github.com/depyronick)\n\n## License\n\n[MIT licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepyronick%2Fnestjs-clickhouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdepyronick%2Fnestjs-clickhouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepyronick%2Fnestjs-clickhouse/lists"}