{"id":15137393,"url":"https://github.com/kartava/nestjs-pgkit","last_synced_at":"2026-01-06T18:04:25.069Z","repository":{"id":257510970,"uuid":"858469770","full_name":"kartava/nestjs-pgkit","owner":"kartava","description":"Pgkit module for Nest framework (node.js) 🍉","archived":false,"fork":false,"pushed_at":"2024-09-19T15:07:51.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-16T23:01:02.259Z","etag":null,"topics":["javascript","nest","nestjs","nodejs","pgkit","sql","typescript"],"latest_commit_sha":null,"homepage":"","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/kartava.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2024-09-17T00:25:53.000Z","updated_at":"2024-09-19T15:07:55.000Z","dependencies_parsed_at":"2024-09-26T07:00:44.999Z","dependency_job_id":null,"html_url":"https://github.com/kartava/nestjs-pgkit","commit_stats":null,"previous_names":["kartava/nestjs-pgkit"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kartava%2Fnestjs-pgkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kartava%2Fnestjs-pgkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kartava%2Fnestjs-pgkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kartava%2Fnestjs-pgkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kartava","download_url":"https://codeload.github.com/kartava/nestjs-pgkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246190434,"owners_count":20738024,"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","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":["javascript","nest","nestjs","nodejs","pgkit","sql","typescript"],"created_at":"2024-09-26T07:00:39.815Z","updated_at":"2026-01-06T18:04:25.063Z","avatar_url":"https://github.com/kartava.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca name=\"nestjs-pgkit\"\u003e\u003c/a\u003e\n## Description\n\n[pgkit](https://www.pgkit.dev/packages/client/) module\nfor [Nest](https://github.com/nestjs/nest).\n\n## Contents\n* [nestjs-pgkit](#nestjs-pgkit)\n    * [Installation](#installation)\n    * [Basic import](#basic-import)\n    * [Multiple databases](#multiple-databases)\n    * [Async configuration](#async-configuration)\n    * [License](#license)\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\n### Installation\n\n###### npm\n\n```bash\nnpm i --save nestjs-pgkit @pgkit/client\n```\n\n###### yarn\n\n```bash\nyarn add nestjs-pgkit @pgkit/client\n```\n\n\u003ca name=\"basic-import\"\u003e\u003c/a\u003e\n### Basic import\n\nOnce the installation process is complete, we can import the `PgKitModule` into the root `AppModule`.\n\n\n\u003e app.module.ts\n```typescript\nimport { Module } from \"@nestjs/common\";\nimport { PgKitModule } from \"nestjs-pgkit\";\n\n@Module({\n  imports: [\n    PgKitModule.forRoot({\n      connectionUri: \"postgres://user:password@localhost:5432/test\",\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\nThe `forRoot()` method supports configuration properties described below.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd colspan='2'\u003e\u003cb\u003ePgKit options\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003econnectionUri\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href='https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING'\u003eConnection URI\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan='2'\u003e\u003cb\u003ePgKitModule options\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003ename\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eConnection client name. Used to inject different db connections (default: \u003ccode\u003edefault\u003c/code\u003e)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003etoRetry\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eFunction that determines whether the module should attempt to connect upon failure\n\u003cbr\u003e\u003ccode\u003e(err: any) =\u003e boolean\u003c/code\u003e\n\u003cbr\u003eerr parameter is error that was thrown\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003everboseRetryLog\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eIf \u003ccode\u003etrue\u003c/code\u003e, will show verbose error messages on each connection retry (default: \u003ccode\u003efalse\u003c/code\u003e)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eretryAttempts\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eNumber of attempts to connect to the database (default: \u003ccode\u003e10\u003c/code\u003e)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eretryDelay\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eDelay between connection retry attempts (ms) (default: \u003ccode\u003e3000\u003c/code\u003e)\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nOnce this is done, the pgkit client will be available to inject across the entire project (without needing to\nimport any modules), for example:\n\n\u003e app.service.ts\n```typescript\nimport { Injectable } from \"@nestjs/common\";\n\nimport { Client, sql } from \"@pgkit/client\";\nimport { InjectClient } from \"nestjs-pgkit\";\n\n@Injectable()\nexport class AppService {\n  constructor(\n    @InjectClient()\n    private readonly client: Client,\n  ) {}\n\n  getGreeting(): Promise\u003cstring\u003e {\n    return this.client.oneFirst\u003cstring\u003e(sql`SELECT 'Hello World!';`);\n  }\n}\n```\n\n\u003ca name=\"multiple-databases\"\u003e\u003c/a\u003e\n### Multiple databases\n\nSome projects require multiple database connections. This can also be achieved with this module.\nTo work with multiple clients, first create the clients. In this case, client naming becomes **mandatory**.\n\n```typescript\n@Module({\n  imports: [\n    PgKitModule.forRoot({\n      connectionUri: \"postgres://user:password@users_db_host:5432/users\",\n    }),\n    PgKitModule.forRoot({\n      name: \"ALBUMS_CLIENT\",\n      connectionUri: \"postgres://user:password@albums_db_host:5432/albums\",\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n\u003e **Notice** If you don't set the `name` for a client, its name is set to `default`. Please note that you shouldn't\n\u003e have multiple clients without a name, or with the same name, otherwise they will get overridden.\n\nNow you can inject the pgkit client for a given client name:\n\n```typescript\n@Injectable()\nexport class AlbumsService {\n  constructor(\n    @InjectClient()\n    private usersClient: Client,\n    @InjectClient(\"ALBUMS_CLIENT\")\n    private albumsClient: Client,\n  ) {}\n}\n```\n\n\u003ca name=\"async-configuration\"\u003e\u003c/a\u003e\n### Async configuration\n\nYou may want to pass your `PgKitModule` options asynchronously instead of statically.\nIn this case, use the `forRootAsync()` method, which provides several ways to deal with async configuration.\n\nOne approach is to use a factory function:\n\n```typescript\nPgKitModule.forRootAsync({\n  useFactory: () =\u003e ({\n    connectionUri: \"postgres://user:password@users_db_host:5432/users\",\n  }),\n});\n```\n\nOur factory behaves like any other [asynchronous provider](https://docs.nestjs.com/fundamentals/async-providers)\n(e.g., it can be `async` and it's able to inject dependencies through `inject`).\n\n```typescript\nPgKitModule.forRootAsync({\n  imports: [ConfigModule],\n  useFactory: (configService: ConfigService) =\u003e ({\n    connectionUri: configService.get(\"DATABASE_URL\"),\n  }),\n  inject: [ConfigService],\n});\n```\n\nAlternatively, you can use the `useClass` syntax:\n\n```typescript\nPgKitModule.forRootAsync({\n  useClass: PgKitConfigService,\n});\n```\n\nThe construction above will instantiate `PgKitConfigService` inside `PgKitModule` and use it to provide\nan options object by calling `createPgKitOptions()`. Note that this means that the `PgKitConfigService`\nhas to implement the `PgKitOptionsFactory` interface, as shown below:\n\n```typescript\n@Injectable()\nclass PgKitConfigService implements PgKitOptionsFactory {\n  createPgKitOptions(): PgKitModuleOptions {\n    return {\n      connectionUri: \"postgres://user:password@users_db_host:5432/users\",\n    };\n  }\n}\n```\n\nIn order to prevent the creation of `PgKitConfigService` inside `PgKitModule` and use a provider imported\nfrom a different module, you can use the `useExisting` syntax.\n\n```typescript\nPgKitModule.forRootAsync({\n  imports: [ConfigModule],\n  useExisting: ConfigService,\n});\n```\n\nThis construction works the same as `useClass` with one critical difference - `PgKitModule` will lookup\nimported modules to reuse an existing `ConfigService` instead of instantiating a new one.\n\n\u003e Make sure that the `name` property is defined at the same level as the `useFactory`, `useClass`, or\n\u003e `useValue` property. This will allow Nest to properly register the pool under the appropriate injection token.\n```typescript\nPgKitModule.forRootAsync({\n  name: \"ALBUMS_CLIENT\",\n  useFactory: () =\u003e ({\n    connectionUri: postgresConnectionUri,\n  }),\n})\n```\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n[MIT license](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkartava%2Fnestjs-pgkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkartava%2Fnestjs-pgkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkartava%2Fnestjs-pgkit/lists"}