@digitalwalletcorp/pg-pooling 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digitalwalletcorp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# PG Pooling
+
+[![NPM Version](https://img.shields.io/npm/v/%40digitalwalletcorp%2Fpg-pooling)](https://www.npmjs.com/package/@digitalwalletcorp/pg-pooling) [![License](https://img.shields.io/npm/l/%40digitalwalletcorp%2Fpg-pooling)](https://opensource.org/licenses/MIT) [![Build Status](https://img.shields.io/github/actions/workflow/status/digitalwalletcorp/pg-pooling/ci.yml?branch=main)](https://github.com/digitalwalletcorp/pg-pooling/actions) [![Test Coverage](https://img.shields.io/codecov/c/github/digitalwalletcorp/pg-pooling.svg)](https://codecov.io/gh/digitalwalletcorp/pg-pooling)
+
+A lightweight TypeScript/JavaScript library for managing PostgreSQL connections with pooling support.
+Designed for both server-side Node.js applications and cron-style background jobs, it wraps the `pg` `Pool` with safe connect/release handling, transaction helpers, slow-acquire and leak detection, and optional SQL logging.
+
+#### ✨ Features
+
+* **Connection Pooling**: Thin wrapper around the `pg` `Pool` with sensible timeout defaults.
+* **Safe Acquire/Release**: Each checked-out client gets its own error listener and a leak-detection timer, so a forgotten `release()` is surfaced instead of silently exhausting the pool.
+* **Pool Exhaustion Diagnostics**: Warns on slow acquires (`POOL ACQUIRE SLOW`), failed acquires (`POOL CONNECT FAILED`) and suspected leaks (`POOL LEAK SUSPECT`).
+* **Transaction Helpers**: `begin()` / `commit()` / `rollback()` convenience methods.
+* **Optional SQL Logging**: Emits the executed SQL and a truncated result set to `console.debug` when `debug` is enabled.
+* **DATE Type Parsing**: PostgreSQL `DATE` (OID 1082) is returned as a `YYYY-MM-DD` string instead of a timezone-dependent `Date`.
+
+#### 📦 Installation
+
+`pg` is a **peer dependency**. Install it alongside this library so the application and the pool share a single `pg` instance.
+
+```bash
+npm install @digitalwalletcorp/pg-pooling pg
+# or
+yarn add @digitalwalletcorp/pg-pooling pg
+```
+
+#### 📖 Usage
+
+Environment variables and SSL are the responsibility of the application. This library only consumes the `config` object it is given.
+
+##### Example 1: Pure NodeJS Style Instantiation
+
+This pattern is ideal for short-lived Node.js scripts, such as cron jobs, where a pool is created, used, and destroyed within a single run.
+
+```typescript
+import { PgPool } from '@digitalwalletcorp/pg-pooling';
+
+const pool = new PgPool({
+  host: 'localhost',
+  port: 5432,
+  database: 'app',
+  user: 'app',
+  password: 'secret',
+  max: 10
+});
+
+async function main() {
+  const client = await pool.connect();
+  try {
+    const res = await client.query('SELECT * FROM users WHERE id = $1', [1]);
+    console.log(res.rows);
+  } finally {
+    client.release();
+  }
+  await pool.end();
+}
+
+main().catch(console.error);
+```
+
+##### Example 2: Singleton Pool Instantiation using a Web-App
+
+For long-running web applications, a singleton pool ensures efficient reuse of connections across requests.
+The application reads its own environment variables and builds the `config` (including `application_name` and `ssl`).
+
+`@/server/singleton/connection-pooling`
+```typescript
+import { PgPool } from '@digitalwalletcorp/pg-pooling';
+
+let pool: PgPool | undefined;
+
+export function connectionPooling(): PgPool {
+  if (!pool) {
+    pool = new PgPool({
+      host: process.env.PG_HOST,
+      port: Number(process.env.PG_PORT),
+      database: process.env.PG_DATABASE,
+      user: process.env.PG_USER,
+      password: process.env.PG_PASSWORD,
+      max: Number(process.env.PG_POOL_SIZE),
+      application_name: `myapp-${process.env.APP_ENV}`,
+      ssl: process.env.APP_ENV === 'production' ? { rejectUnauthorized: false } : false
+    }, {
+      debug: process.env.NODE_ENV !== 'production'
+    });
+  }
+  return pool;
+}
+```
+
+`@/server/api/some-rest-api`
+```typescript
+import { connectionPooling } from '@/server/singleton/connection-pooling';
+
+async function handleRequest() {
+  const pool = connectionPooling();
+  const client = await pool.connect();
+  try {
+    const res = await client.query('SELECT * FROM sessions WHERE token = $1', ['abc']);
+    return res.rows;
+  } finally {
+    client.release();
+  }
+}
+```
+
+##### Example 3: Transactions
+
+```typescript
+const client = await pool.connect();
+try {
+  await client.begin();
+  await client.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, 1]);
+  await client.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 2]);
+  await client.commit();
+} catch (error) {
+  await client.rollback();
+  throw error;
+} finally {
+  client.release();
+}
+```
+
+#### 📚 API Reference
+
+##### `new PgPool(config: pg.PoolConfig, options?: PgPoolOptions)`
+
+Creates a PostgreSQL connection pool. `config` is passed through to the underlying `pg` `Pool`. The following timeout-related properties fall back to the library defaults when they are not provided in `config`.
+
+| Property                              | Type              | Default   | Description                                                                 |
+| ------------------------------------- | ----------------- | --------- | --------------------------------------------------------------------------- |
+| `connectionTimeoutMillis`             | number            | 10000     | Fail instead of waiting forever when the pool is exhausted.                 |
+| `statement_timeout`                   | number            | 30000     | Server-side statement timeout.                                              |
+| `query_timeout`                       | number            | 35000     | Client-side query timeout. Longer than the server-side one.                 |
+| `idle_in_transaction_session_timeout` | number            | 60000     | Server-side timeout for sessions left idle inside a transaction.            |
+| `keepAlive`                           | boolean           | true      | Enable TCP keep-alive.                                                      |
+| `keepAliveInitialDelayMillis`         | number            | 10000     | Initial delay before the first keep-alive probe.                           |
+
+All other `pg.PoolConfig` properties (`host`, `port`, `database`, `user`, `password`, `max`, `application_name`, `ssl`, ...) are passed through unchanged.
+
+`PgPoolOptions`:
+
+| Property | Type    | Default | Description                                                        |
+| -------- | ------- | ------- | ------------------------------------------------------------------ |
+| `debug`  | boolean | false   | When `true`, executed SQL and results are logged to `console.debug`. |
+
+##### `PgPool` Methods
+
+| Method              | Signature                       | Description                                                       |
+| ------------------- | ------------------------------- | ----------------------------------------------------------------- |
+| `connect()`         | `Promise<PgClient>`    | Acquire a client from the pool.                                   |
+| `end()`             | `Promise<void>`                 | Drain and close the pool.                                         |
+| `getOriginalPool()` | `pg.Pool`                       | Access the underlying `pg` `Pool`.                                |
+| `totalCount`        | `number`                        | Number of connections the pool is holding.                       |
+| `idleCount`         | `number`                        | Number of idle connections available to borrow.                  |
+| `waitingCount`      | `number`                        | Number of requests waiting for a connection.                     |
+
+##### `PgClient` Methods
+
+| Method                                  | Signature              | Description                                                        |
+| --------------------------------------- | ---------------------- | ------------------------------------------------------------------ |
+| `query(text, values?, options?)`        | `Promise<pg.QueryResult>` | Run a query. Pass `{ suppressLog: true }` to skip SQL logging.  |
+| `begin()` / `commit()` / `rollback()`   | `Promise<pg.QueryResult>` | Transaction control statements.                                 |
+| `release()`                             | `void`                 | Return the client to the pool.                                    |
+
+#### 💡 Notes
+
+* Always release clients back to the pool using `release()` to avoid connection leaks.
+* Use `connect()` and `release()` inside `try/finally` blocks for safe resource management.
+* Warnings (slow acquire, connect failure, leak suspect, idle/checked-out client errors) are emitted via `process.emitWarning`. To suppress them, run Node with the `--no-warnings` flag (e.g. `node --no-warnings app.js`, or `NODE_OPTIONS=--no-warnings`).
+
+#### 📜 License
+
+This project is licensed under the MIT License. See the [LICENSE](https://opensource.org/licenses/MIT) file for details.

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './pg-pooling';

package/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./pg-pooling"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B"}

package/lib/pg-pooling.d.ts

@@ -0,0 +1,38 @@
+import pg from 'pg';
+export interface PgPoolOptions {
+    debug?: boolean;
+}
+export declare class PgPool {
+    private pool;
+    private readonly debug;
+    constructor(config: pg.PoolConfig, options?: PgPoolOptions);
+    getOriginalPool(): pg.Pool;
+    connect(): Promise<PgClient>;
+    /**
+     * プールの利用状況
+     *
+     * @returns {{ total: number; idle: number; waiting: number; }}
+     */
+    private poolStats;
+    end(): Promise<void>;
+    get totalCount(): number;
+    get idleCount(): number;
+    get waitingCount(): number;
+}
+export declare class PgClient {
+    private client;
+    private readonly debug;
+    private acquiredAt;
+    private leakTimer;
+    private leakWarned;
+    private errorListener;
+    constructor(client: pg.PoolClient, debug?: boolean);
+    query<R extends pg.QueryResult = pg.QueryResult>(text: string, values?: any[], options?: {
+        suppressLog?: boolean;
+    }): Promise<R>;
+    release(): void;
+    begin(): Promise<pg.QueryResult>;
+    commit(): Promise<pg.QueryResult>;
+    rollback(): Promise<pg.QueryResult>;
+    private debugLog;
+}

package/lib/pg-pooling.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgClient = exports.PgPool = void 0;
+const pg_1 = __importDefault(require("pg"));
+const util_1 = __importDefault(require("util"));
+// PostgreSQLのDATE型をYYYY-MM-DD文字列に変換して返却する設定
+// PGドライバーのデフォルトの挙動だとprocess.env.TZに依存したJSDateオブジェクトに変換されてしまうため、DATE型なのに予期しないゾーン情報が含まれてしまうことがある
+// SQLの段階でカラムを指定してセレクトできる場合は`SELECT xx_date::TEXT`のように記述すればSQLレベルでYYYY-MM-DD文字列に変換される
+pg_1.default.types.setTypeParser(1082, (v) => v);
+const logHeader = '[PgPooling]';
+// 各種タイムアウトの既定値。configで未指定の項目にだけ適用する
+const DEFAULT_CONNECTION_TIMEOUT_MS = 10 * 1000; // プールが枯渇したときに無限待ちせず失敗させる
+const DEFAULT_STATEMENT_TIMEOUT_MS = 30 * 1000; // サーバ側でクエリを打ち切る
+const DEFAULT_QUERY_TIMEOUT_MS = 35 * 1000; // 応答が返らない(ソケットが死んでいる)場合。サーバ側より長くする
+const DEFAULT_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS = 60 * 1000; // トランザクションを開いたまま放置されたセッションをサーバ側で終了させる
+const DEFAULT_KEEP_ALIVE = true;
+const DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS = 10 * 1000;
+// 接続の取得がこの時間を超えた場合に警告する。正常時の取得は新規接続の確立を含めても数百msで収まる
+const ACQUIRE_WARN_MS = 1000;
+// 接続の保持がこの時間を超えた場合にリーク疑いとして警告する。
+// 1クエリの上限(statement_timeout/query_timeout)より長く、サーバ側が放置セッションを切断するidle_in_transaction_session_timeoutと同じ長さ
+const LEAK_WARN_MS = 60 * 1000;
+class PgPool {
+    pool;
+    debug;
+    constructor(config, options) {
+        this.debug = options?.debug ?? false;
+        // 各種タイムアウトの既定値を適用する。configで指定された項目はそのまま優先する
+        const mergedConfig = {
+            connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+            statement_timeout: DEFAULT_STATEMENT_TIMEOUT_MS,
+            query_timeout: DEFAULT_QUERY_TIMEOUT_MS,
+            idle_in_transaction_session_timeout: DEFAULT_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS,
+            keepAlive: DEFAULT_KEEP_ALIVE,
+            keepAliveInitialDelayMillis: DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS,
+            ...config
+        };
+        this.pool = new pg_1.default.Pool(mergedConfig);
+        this.pool.on('error', (error) => {
+            // アイドル接続のエラーはプールに通知する
+            // リスナーが無いとプロセスが落ちるため必ず登録する
+            process.emitWarning(`${logHeader} Idle client error. ${error.message}`);
+        });
+    }
+    getOriginalPool() {
+        return this.pool;
+    }
+    async connect() {
+        const start = Date.now();
+        try {
+            const client = await this.pool.connect();
+            const elapsedMs = Date.now() - start;
+            const stats = this.poolStats();
+            // 取得に時間がかかった、あるいは取得待ちの要求が滞留している場合はプール枯渇の前兆として警告する
+            if (ACQUIRE_WARN_MS <= elapsedMs || 0 < stats.waiting) {
+                process.emitWarning(`${logHeader} POOL ACQUIRE SLOW. ${JSON.stringify({ elapsedMs, ...stats })}`);
+            }
+            return new PgClient(client, this.debug);
+        }
+        catch (error) {
+            // connectionTimeoutMillisによる取得失敗を無言にしない
+            process.emitWarning(`${logHeader} POOL CONNECT FAILED. ${JSON.stringify({ elapsedMs: Date.now() - start, ...this.poolStats() })} ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+    }
+    /**
+     * プールの利用状況
+     *
+     * @returns {{ total: number; idle: number; waiting: number; }}
+     */
+    poolStats() {
+        return {
+            total: this.pool.totalCount, // プールが保持している接続数
+            idle: this.pool.idleCount, // うち貸出可能な接続数
+            waiting: this.pool.waitingCount // 接続を取得できずに待機している要求数
+        };
+    }
+    async end() {
+        return this.pool.end();
+    }
+    get totalCount() {
+        return this.pool.totalCount;
+    }
+    get idleCount() {
+        return this.pool.idleCount;
+    }
+    get waitingCount() {
+        return this.pool.waitingCount;
+    }
+}
+exports.PgPool = PgPool;
+class PgClient {
+    client;
+    debug;
+    acquiredAt = Date.now();
+    leakTimer;
+    leakWarned = false;
+    // 貸出中のクライアントに個別のエラーリスナーを設定
+    // これが無いとDB側の瞬断でリスナー不在のerrorイベントが発生し、プロセスが落ちる
+    errorListener = (error) => {
+        process.emitWarning(`${logHeader} Checked-out client error. ${error.message}`);
+    };
+    constructor(client, debug = false) {
+        this.client = client;
+        this.debug = debug;
+        this.client.on('error', this.errorListener);
+        // リークした接続の取得元を特定できるように、取得時点のスタックトレースを保持する
+        const acquireStack = new Error('acquired here').stack;
+        this.leakTimer = setTimeout(() => {
+            this.leakWarned = true;
+            process.emitWarning(`${logHeader} POOL LEAK SUSPECT. ${JSON.stringify({ heldMs: Date.now() - this.acquiredAt })}\n${acquireStack}`);
+        }, LEAK_WARN_MS);
+        // タイマーが残っていてもプロセスの終了を妨げないようにする
+        this.leakTimer.unref();
+    }
+    async query(text, values, options) {
+        if (!options?.suppressLog) {
+            this.debugLog(logHeader, 'SQL', text, values);
+        }
+        const result = await this.client.query(text, values);
+        if (!options?.suppressLog) {
+            this.debugLog(logHeader, 'SQL RESULT', {
+                command: result.command,
+                rowCount: result.rowCount,
+                rows: Array.isArray(result.rows)
+                    ? util_1.default.inspect(result.rows.slice(0, 3), false, null)
+                    : util_1.default.inspect(result.rows, false, null)
+            });
+        }
+        return result;
+    }
+    release() {
+        clearTimeout(this.leakTimer);
+        if (this.leakWarned) {
+            // リーク疑い警告後に返却されたことを記録する。警告後にこのログが無ければ本物のリークと判断できる
+            process.emitWarning(`${logHeader} POOL RELEASE (after leak suspect). ${JSON.stringify({ heldMs: Date.now() - this.acquiredAt })}`);
+        }
+        // 返却後はプール側のリスナー(pool.on('error'))が受け持つ
+        this.client.removeListener('error', this.errorListener);
+        this.client.release();
+    }
+    async begin() {
+        this.debugLog(logHeader, 'BEGIN');
+        return this.client.query('BEGIN');
+    }
+    async commit() {
+        this.debugLog(logHeader, 'COMMIT');
+        return this.client.query('COMMIT');
+    }
+    async rollback() {
+        this.debugLog(logHeader, 'ROLLBACK');
+        return this.client.query('ROLLBACK');
+    }
+    debugLog(...args) {
+        if (this.debug) {
+            console.debug(...args);
+        }
+    }
+}
+exports.PgClient = PgClient;
+//# sourceMappingURL=pg-pooling.js.map

package/lib/pg-pooling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-pooling.js","sourceRoot":"","sources":["../src/pg-pooling.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@digitalwalletcorp/pg-pooling",
+  "version": "0.1.0",
+  "description": "This is a library for PostgreSQL connection pooling",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "install:dev": "rm -rf lib dest && find node_modules -mindepth 1 -delete && yarn install",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "prepack": "rm -rf lib && npm run build",
+    "pack": "rm -rf dest && mkdir -p dest && npm pack --pack-destination=dest",
+    "publish:npm": "bash ../bin/publish.sh",
+    "test:unit": "NODE_OPTIONS=--max-old-space-size=2048 npx jest --runInBand --logHeapUsage --detectOpenHandles --forceExit --errorOnDeprecated --coverage --silent --unhandled-rejections=strict"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "pg",
+    "pooling"
+  ],
+  "author": "satoshi kotaki",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/digitalwalletcorp/pg-pooling.git"
+  },
+  "homepage": "https://github.com/digitalwalletcorp/pg-pooling",
+  "bugs": {
+    "url": "https://github.com/digitalwalletcorp/pg-pooling/issues"
+  },
+  "files": [
+    "lib/**/*",
+    "src/**/*"
+  ],
+  "peerDependencies": {
+    "pg": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/pg": "^8.16.0",
+    "jest": "^30.3.0",
+    "pg": "^8.16.3",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './pg-pooling';

package/src/pg-pooling.ts

@@ -0,0 +1,181 @@
+import pg from 'pg';
+import util from 'util';
+
+// PostgreSQLのDATE型をYYYY-MM-DD文字列に変換して返却する設定
+// PGドライバーのデフォルトの挙動だとprocess.env.TZに依存したJSDateオブジェクトに変換されてしまうため、DATE型なのに予期しないゾーン情報が含まれてしまうことがある
+// SQLの段階でカラムを指定してセレクトできる場合は`SELECT xx_date::TEXT`のように記述すればSQLレベルでYYYY-MM-DD文字列に変換される
+pg.types.setTypeParser(1082, (v) => v);
+
+export interface PgPoolOptions {
+  debug?: boolean;
+}
+
+const logHeader = '[PgPooling]';
+
+// 各種タイムアウトの既定値。configで未指定の項目にだけ適用する
+const DEFAULT_CONNECTION_TIMEOUT_MS = 10 * 1000; // プールが枯渇したときに無限待ちせず失敗させる
+const DEFAULT_STATEMENT_TIMEOUT_MS = 30 * 1000; // サーバ側でクエリを打ち切る
+const DEFAULT_QUERY_TIMEOUT_MS = 35 * 1000; // 応答が返らない(ソケットが死んでいる)場合。サーバ側より長くする
+const DEFAULT_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS = 60 * 1000; // トランザクションを開いたまま放置されたセッションをサーバ側で終了させる
+const DEFAULT_KEEP_ALIVE = true;
+const DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS = 10 * 1000;
+
+// 接続の取得がこの時間を超えた場合に警告する。正常時の取得は新規接続の確立を含めても数百msで収まる
+const ACQUIRE_WARN_MS = 1000;
+// 接続の保持がこの時間を超えた場合にリーク疑いとして警告する。
+// 1クエリの上限(statement_timeout/query_timeout)より長く、サーバ側が放置セッションを切断するidle_in_transaction_session_timeoutと同じ長さ
+const LEAK_WARN_MS = 60 * 1000;
+
+export class PgPool {
+  private pool: pg.Pool;
+  private readonly debug: boolean;
+
+  constructor(config: pg.PoolConfig, options?: PgPoolOptions) {
+    this.debug = options?.debug ?? false;
+    // 各種タイムアウトの既定値を適用する。configで指定された項目はそのまま優先する
+    const mergedConfig: pg.PoolConfig = {
+      connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+      statement_timeout: DEFAULT_STATEMENT_TIMEOUT_MS,
+      query_timeout: DEFAULT_QUERY_TIMEOUT_MS,
+      idle_in_transaction_session_timeout: DEFAULT_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS,
+      keepAlive: DEFAULT_KEEP_ALIVE,
+      keepAliveInitialDelayMillis: DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS,
+      ...config
+    };
+    this.pool = new pg.Pool(mergedConfig);
+    this.pool.on('error', (error: Error) => {
+      // アイドル接続のエラーはプールに通知する
+      // リスナーが無いとプロセスが落ちるため必ず登録する
+      process.emitWarning(`${logHeader} Idle client error. ${error.message}`);
+    });
+  }
+
+  public getOriginalPool(): pg.Pool {
+    return this.pool;
+  }
+
+  public async connect(): Promise<PgClient> {
+    const start = Date.now();
+    try {
+      const client = await this.pool.connect();
+      const elapsedMs = Date.now() - start;
+      const stats = this.poolStats();
+      // 取得に時間がかかった、あるいは取得待ちの要求が滞留している場合はプール枯渇の前兆として警告する
+      if (ACQUIRE_WARN_MS <= elapsedMs || 0 < stats.waiting) {
+        process.emitWarning(`${logHeader} POOL ACQUIRE SLOW. ${JSON.stringify({ elapsedMs, ...stats })}`);
+      }
+      return new PgClient(client, this.debug);
+    } catch (error) {
+      // connectionTimeoutMillisによる取得失敗を無言にしない
+      process.emitWarning(`${logHeader} POOL CONNECT FAILED. ${JSON.stringify({ elapsedMs: Date.now() - start, ...this.poolStats() })} ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+
+  /**
+   * プールの利用状況
+   *
+   * @returns {{ total: number; idle: number; waiting: number; }}
+   */
+  private poolStats(): { total: number; idle: number; waiting: number; } {
+    return {
+      total: this.pool.totalCount, // プールが保持している接続数
+      idle: this.pool.idleCount, // うち貸出可能な接続数
+      waiting: this.pool.waitingCount // 接続を取得できずに待機している要求数
+    };
+  }
+
+  public async end(): Promise<void> {
+    return this.pool.end();
+  }
+
+  public get totalCount(): number {
+    return this.pool.totalCount;
+  }
+
+  public get idleCount(): number {
+    return this.pool.idleCount;
+  }
+
+  public get waitingCount(): number {
+    return this.pool.waitingCount;
+  }
+}
+
+export class PgClient {
+  private client: pg.PoolClient;
+  private readonly debug: boolean;
+  private acquiredAt = Date.now();
+  private leakTimer: ReturnType<typeof setTimeout>;
+  private leakWarned = false;
+  // 貸出中のクライアントに個別のエラーリスナーを設定
+  // これが無いとDB側の瞬断でリスナー不在のerrorイベントが発生し、プロセスが落ちる
+  private errorListener = (error: Error) => {
+    process.emitWarning(`${logHeader} Checked-out client error. ${error.message}`);
+  };
+
+  constructor(client: pg.PoolClient, debug = false) {
+    this.client = client;
+    this.debug = debug;
+    this.client.on('error', this.errorListener);
+    // リークした接続の取得元を特定できるように、取得時点のスタックトレースを保持する
+    const acquireStack = new Error('acquired here').stack;
+    this.leakTimer = setTimeout(() => {
+      this.leakWarned = true;
+      process.emitWarning(`${logHeader} POOL LEAK SUSPECT. ${JSON.stringify({ heldMs: Date.now() - this.acquiredAt })}\n${acquireStack}`);
+    }, LEAK_WARN_MS);
+    // タイマーが残っていてもプロセスの終了を妨げないようにする
+    this.leakTimer.unref();
+  }
+
+  public async query<R extends pg.QueryResult = pg.QueryResult>(text: string, values?: any[], options?: {
+    suppressLog?: boolean
+  }): Promise<R> {
+    if (!options?.suppressLog) {
+      this.debugLog(logHeader, 'SQL', text, values);
+    }
+    const result = await this.client.query(text, values);
+    if (!options?.suppressLog) {
+      this.debugLog(logHeader, 'SQL RESULT', {
+        command: result.command,
+        rowCount: result.rowCount,
+        rows: Array.isArray(result.rows)
+          ? util.inspect(result.rows.slice(0, 3), false, null)
+          : util.inspect(result.rows, false, null)
+      });
+    }
+    return result as unknown as R;
+  }
+
+  public release(): void {
+    clearTimeout(this.leakTimer);
+    if (this.leakWarned) {
+      // リーク疑い警告後に返却されたことを記録する。警告後にこのログが無ければ本物のリークと判断できる
+      process.emitWarning(`${logHeader} POOL RELEASE (after leak suspect). ${JSON.stringify({ heldMs: Date.now() - this.acquiredAt })}`);
+    }
+    // 返却後はプール側のリスナー(pool.on('error'))が受け持つ
+    this.client.removeListener('error', this.errorListener);
+    this.client.release();
+  }
+
+  public async begin(): Promise<pg.QueryResult> {
+    this.debugLog(logHeader, 'BEGIN');
+    return this.client.query('BEGIN');
+  }
+
+  public async commit(): Promise<pg.QueryResult> {
+    this.debugLog(logHeader, 'COMMIT');
+    return this.client.query('COMMIT');
+  }
+
+  public async rollback(): Promise<pg.QueryResult> {
+    this.debugLog(logHeader, 'ROLLBACK');
+    return this.client.query('ROLLBACK');
+  }
+
+  private debugLog(...args: any[]): void {
+    if (this.debug) {
+      console.debug(...args);
+    }
+  }
+}