@juit/pgproxy-client-psql 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# PostgreSQL Proxy Client (LibPQ Implementation)
+
+This package provides a `PGClient` implementation _directly connecting_ to
+PostgreSQL servers, and not requiring a PGProxy Server to run.
+
+This is useful (mostly? only?) when running tests with a PostgreSQL instance
+running on a developer's machine, or in CI environments.
+
+* [Usage with PGClient](#usage-with-pgclient)
+* [Direct Usage](#direct-usage)
+* [Environment Variables](#environment-variables)
+* [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
+* [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+* [License](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+
+### Usage with PGClient
+
+Simply register the client by importing it, and ensure that the `PGURL`
+environment variable is set to the `psql` url of the PostgreSQL server (or
+specify the URL in the constructor):
+
+```ts
+import '@juit/pgproxy-client-psql'
+import { PGClient } from '@juit/pgproxy-client'
+
+const client = new PGClient('psql://username:password@locahost:5432/my-database')
+```
+
+### Direct usage
+
+The PSQL client can be used directly by simply importing the `PSQLClient`
+class:
+
+```ts
+import { PSQLClient } from '@juit/pgproxy-client-psql'
+
+const client = new PSQLClient('psql://username:password@locahost:5432/my-database')
+```
+
+### Environment Variables
+
+The `PSQLClient` implementation does not _require_ a connection URL, and all
+connection parameters can be specified via `libpq` environment variables.
+
+The special (empty) URL `psql:///` can be used with `PGClient` in order to
+trigger this behaviour or `PSQLClient` instances can be constructed without
+an URL parameter.
+
+For a description of the environment variables supported by `libpq` simply look
+at the [official documentation](https://www.postgresql.org/docs/current/libpq-envars.html).

package/dist/index.cjs

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var src_exports = {};
+__export(src_exports, {
+  PSQLClient: () => PSQLClient,
+  PSQLProvider: () => PSQLProvider
+});
+module.exports = __toCommonJS(src_exports);
+var import_pgproxy_client = require("@juit/pgproxy-client");
+var import_pgproxy_pool = require("@juit/pgproxy-pool");
+function setupPoolOption(url, options, option) {
+  if (url.searchParams.has(option)) {
+    options[option] = Number(url.searchParams.get(option));
+  }
+}
+function setupPoolOptions(url, options) {
+  setupPoolOption(url, options, "minimumPoolSize");
+  setupPoolOption(url, options, "maximumPoolSize");
+  setupPoolOption(url, options, "maximumIdleConnections");
+  setupPoolOption(url, options, "acquireTimeout");
+  setupPoolOption(url, options, "borrowTimeout");
+  setupPoolOption(url, options, "retryInterval");
+}
+var PSQLProvider = class extends import_pgproxy_client.AbstractPGProvider {
+  _pool;
+  constructor(url) {
+    super();
+    if (!url) {
+      this._pool = new import_pgproxy_pool.ConnectionPool(PSQLClient.logger);
+    } else {
+      if (typeof url === "string")
+        url = new URL(url);
+      (0, import_pgproxy_client.assert)(url.protocol === "psql:", `Unsupported protocol "${url.protocol}"`);
+      const options = {};
+      if (url.username)
+        options.user = decodeURIComponent(url.username);
+      if (url.password)
+        options.password = decodeURIComponent(url.password);
+      if (url.hostname)
+        options.host = url.hostname;
+      if (url.port)
+        options.port = Number(url.port);
+      if (url.pathname !== "/")
+        options.database = url.pathname.substring(1);
+      setupPoolOptions(url, options);
+      this._pool = new import_pgproxy_pool.ConnectionPool(PSQLClient.logger, options);
+    }
+  }
+  async acquire() {
+    if (!this._pool.running)
+      await this._pool.start();
+    return this._pool.acquire();
+  }
+  async release(connection) {
+    await this._pool.release(connection);
+  }
+  async destroy() {
+    await this._pool.stop();
+  }
+};
+var PSQLClient = class extends import_pgproxy_client.PGClient {
+  constructor(url) {
+    super(new PSQLProvider(url));
+  }
+  /* coverage ignore next */
+  static logger = {
+    debug: () => void 0,
+    info: () => void 0,
+    warn: () => void 0,
+    error: () => void 0
+  };
+};
+(0, import_pgproxy_client.registerProvider)("psql", PSQLProvider);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PSQLClient,
+  PSQLProvider
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAAuE;AACvE,0BAA+B;AAI/B,SAAS,gBACL,KACA,SACA,QAOI;AACN,MAAI,IAAI,aAAa,IAAI,MAAM,GAAG;AAChC,YAAQ,MAAM,IAAI,OAAO,IAAI,aAAa,IAAI,MAAM,CAAC;AAAA,EACvD;AACF;AAEA,SAAS,iBAAiB,KAAU,SAAsC;AACxE,kBAAgB,KAAK,SAAS,iBAAiB;AAC/C,kBAAgB,KAAK,SAAS,iBAAiB;AAC/C,kBAAgB,KAAK,SAAS,wBAAwB;AACtD,kBAAgB,KAAK,SAAS,gBAAgB;AAC9C,kBAAgB,KAAK,SAAS,eAAe;AAC7C,kBAAgB,KAAK,SAAS,eAAe;AAC/C;AAEO,IAAM,eAAN,cAA2B,yCAA+B;AAAA,EACvD;AAAA,EAER,YAAY,KAAoB;AAC9B,UAAM;AAEN,QAAI,CAAE,KAAK;AACT,WAAK,QAAQ,IAAI,mCAAe,WAAW,MAAM;AAAA,IACnD,OAAO;AACL,UAAI,OAAO,QAAQ;AAAU,cAAM,IAAI,IAAI,GAAG;AAC9C,wCAAO,IAAI,aAAa,SAAS,yBAAyB,IAAI,QAAQ,GAAG;AAEzE,YAAM,UAAiC,CAAC;AACxC,UAAI,IAAI;AAAU,gBAAQ,OAAO,mBAAmB,IAAI,QAAQ;AAChE,UAAI,IAAI;AAAU,gBAAQ,WAAW,mBAAmB,IAAI,QAAQ;AACpE,UAAI,IAAI;AAAU,gBAAQ,OAAO,IAAI;AACrC,UAAI,IAAI;AAAM,gBAAQ,OAAO,OAAO,IAAI,IAAI;AAC5C,UAAI,IAAI,aAAa;AAAK,gBAAQ,WAAW,IAAI,SAAS,UAAU,CAAC;AAErE,uBAAiB,KAAK,OAAO;AAC7B,WAAK,QAAQ,IAAI,mCAAe,WAAW,QAAQ,OAAO;AAAA,IAC5D;AAAA,EACF;AAAA,EAEA,MAAM,UAA+B;AACnC,QAAI,CAAE,KAAK,MAAM;AAAS,YAAM,KAAK,MAAM,MAAM;AACjD,WAAO,KAAK,MAAM,QAAQ;AAAA,EAC5B;AAAA,EAEA,MAAM,QAAQ,YAAuC;AACnD,UAAM,KAAK,MAAM,QAAQ,UAAU;AAAA,EACrC;AAAA,EAEA,MAAM,UAAyB;AAC7B,UAAM,KAAK,MAAM,KAAK;AAAA,EACxB;AACF;AAEO,IAAM,aAAN,cAAyB,+BAAS;AAAA,EACvC,YAAY,KAAoB;AAC9B,UAAM,IAAI,aAAa,GAAG,CAAC;AAAA,EAC7B;AAAA;AAAA,EAGA,OAAO,SAAiB;AAAA,IACtB,OAAO,MAAM;AAAA,IACb,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,OAAO,MAAM;AAAA,EACf;AACF;AAAA,IAEA,wCAAiB,QAAQ,YAAY;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import { AbstractPGProvider, PGClient } from '@juit/pgproxy-client';
+import type { Connection, Logger } from '@juit/pgproxy-pool';
+export declare class PSQLProvider extends AbstractPGProvider<Connection> {
+    private _pool;
+    constructor(url?: URL | string);
+    acquire(): Promise<Connection>;
+    release(connection: Connection): Promise<void>;
+    destroy(): Promise<void>;
+}
+export declare class PSQLClient extends PGClient {
+    constructor(url?: URL | string);
+    static logger: Logger;
+}

package/dist/index.mjs

@@ -0,0 +1,71 @@
+// index.ts
+import { AbstractPGProvider, PGClient, assert, registerProvider } from "@juit/pgproxy-client";
+import { ConnectionPool } from "@juit/pgproxy-pool";
+function setupPoolOption(url, options, option) {
+  if (url.searchParams.has(option)) {
+    options[option] = Number(url.searchParams.get(option));
+  }
+}
+function setupPoolOptions(url, options) {
+  setupPoolOption(url, options, "minimumPoolSize");
+  setupPoolOption(url, options, "maximumPoolSize");
+  setupPoolOption(url, options, "maximumIdleConnections");
+  setupPoolOption(url, options, "acquireTimeout");
+  setupPoolOption(url, options, "borrowTimeout");
+  setupPoolOption(url, options, "retryInterval");
+}
+var PSQLProvider = class extends AbstractPGProvider {
+  _pool;
+  constructor(url) {
+    super();
+    if (!url) {
+      this._pool = new ConnectionPool(PSQLClient.logger);
+    } else {
+      if (typeof url === "string")
+        url = new URL(url);
+      assert(url.protocol === "psql:", `Unsupported protocol "${url.protocol}"`);
+      const options = {};
+      if (url.username)
+        options.user = decodeURIComponent(url.username);
+      if (url.password)
+        options.password = decodeURIComponent(url.password);
+      if (url.hostname)
+        options.host = url.hostname;
+      if (url.port)
+        options.port = Number(url.port);
+      if (url.pathname !== "/")
+        options.database = url.pathname.substring(1);
+      setupPoolOptions(url, options);
+      this._pool = new ConnectionPool(PSQLClient.logger, options);
+    }
+  }
+  async acquire() {
+    if (!this._pool.running)
+      await this._pool.start();
+    return this._pool.acquire();
+  }
+  async release(connection) {
+    await this._pool.release(connection);
+  }
+  async destroy() {
+    await this._pool.stop();
+  }
+};
+var PSQLClient = class extends PGClient {
+  constructor(url) {
+    super(new PSQLProvider(url));
+  }
+  /* coverage ignore next */
+  static logger = {
+    debug: () => void 0,
+    info: () => void 0,
+    warn: () => void 0,
+    error: () => void 0
+  };
+};
+registerProvider("psql", PSQLProvider);
+export {
+  PSQLClient,
+  PSQLProvider
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";AAAA,SAAS,oBAAoB,UAAU,QAAQ,wBAAwB;AACvE,SAAS,sBAAsB;AAI/B,SAAS,gBACL,KACA,SACA,QAOI;AACN,MAAI,IAAI,aAAa,IAAI,MAAM,GAAG;AAChC,YAAQ,MAAM,IAAI,OAAO,IAAI,aAAa,IAAI,MAAM,CAAC;AAAA,EACvD;AACF;AAEA,SAAS,iBAAiB,KAAU,SAAsC;AACxE,kBAAgB,KAAK,SAAS,iBAAiB;AAC/C,kBAAgB,KAAK,SAAS,iBAAiB;AAC/C,kBAAgB,KAAK,SAAS,wBAAwB;AACtD,kBAAgB,KAAK,SAAS,gBAAgB;AAC9C,kBAAgB,KAAK,SAAS,eAAe;AAC7C,kBAAgB,KAAK,SAAS,eAAe;AAC/C;AAEO,IAAM,eAAN,cAA2B,mBAA+B;AAAA,EACvD;AAAA,EAER,YAAY,KAAoB;AAC9B,UAAM;AAEN,QAAI,CAAE,KAAK;AACT,WAAK,QAAQ,IAAI,eAAe,WAAW,MAAM;AAAA,IACnD,OAAO;AACL,UAAI,OAAO,QAAQ;AAAU,cAAM,IAAI,IAAI,GAAG;AAC9C,aAAO,IAAI,aAAa,SAAS,yBAAyB,IAAI,QAAQ,GAAG;AAEzE,YAAM,UAAiC,CAAC;AACxC,UAAI,IAAI;AAAU,gBAAQ,OAAO,mBAAmB,IAAI,QAAQ;AAChE,UAAI,IAAI;AAAU,gBAAQ,WAAW,mBAAmB,IAAI,QAAQ;AACpE,UAAI,IAAI;AAAU,gBAAQ,OAAO,IAAI;AACrC,UAAI,IAAI;AAAM,gBAAQ,OAAO,OAAO,IAAI,IAAI;AAC5C,UAAI,IAAI,aAAa;AAAK,gBAAQ,WAAW,IAAI,SAAS,UAAU,CAAC;AAErE,uBAAiB,KAAK,OAAO;AAC7B,WAAK,QAAQ,IAAI,eAAe,WAAW,QAAQ,OAAO;AAAA,IAC5D;AAAA,EACF;AAAA,EAEA,MAAM,UAA+B;AACnC,QAAI,CAAE,KAAK,MAAM;AAAS,YAAM,KAAK,MAAM,MAAM;AACjD,WAAO,KAAK,MAAM,QAAQ;AAAA,EAC5B;AAAA,EAEA,MAAM,QAAQ,YAAuC;AACnD,UAAM,KAAK,MAAM,QAAQ,UAAU;AAAA,EACrC;AAAA,EAEA,MAAM,UAAyB;AAC7B,UAAM,KAAK,MAAM,KAAK;AAAA,EACxB;AACF;AAEO,IAAM,aAAN,cAAyB,SAAS;AAAA,EACvC,YAAY,KAAoB;AAC9B,UAAM,IAAI,aAAa,GAAG,CAAC;AAAA,EAC7B;AAAA;AAAA,EAGA,OAAO,SAAiB;AAAA,IACtB,OAAO,MAAM;AAAA,IACb,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,OAAO,MAAM;AAAA,EACf;AACF;AAEA,iBAAiB,QAAQ,YAAY;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@juit/pgproxy-client-psql",
+  "version": "1.0.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/juitnow/juit-pgproxy.git"
+  },
+  "keywords": [
+    "database",
+    "pg",
+    "pool",
+    "postgres",
+    "proxy"
+  ],
+  "bugs": {
+    "url": "https://github.com/juitnow/juit-pgproxy/issues"
+  },
+  "homepage": "https://github.com/juitnow/juit-pgproxy#readme",
+  "dependencies": {
+    "@juit/pgproxy-client": "1.0.0",
+    "@juit/pgproxy-pool": "1.0.0"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "*.md",
+    "dist/",
+    "src/"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+import { AbstractPGProvider, PGClient, assert, registerProvider } from '@juit/pgproxy-client'
+import { ConnectionPool } from '@juit/pgproxy-pool'
+
+import type { Connection, ConnectionPoolOptions, Logger } from '@juit/pgproxy-pool'
+
+function setupPoolOption(
+    url: URL,
+    options: ConnectionPoolOptions,
+    option:
+    | 'minimumPoolSize'
+    | 'maximumPoolSize'
+    | 'maximumIdleConnections'
+    | 'acquireTimeout'
+    | 'borrowTimeout'
+    | 'retryInterval',
+): void {
+  if (url.searchParams.has(option)) {
+    options[option] = Number(url.searchParams.get(option))
+  }
+}
+
+function setupPoolOptions(url: URL, options: ConnectionPoolOptions): void {
+  setupPoolOption(url, options, 'minimumPoolSize')
+  setupPoolOption(url, options, 'maximumPoolSize')
+  setupPoolOption(url, options, 'maximumIdleConnections')
+  setupPoolOption(url, options, 'acquireTimeout')
+  setupPoolOption(url, options, 'borrowTimeout')
+  setupPoolOption(url, options, 'retryInterval')
+}
+
+export class PSQLProvider extends AbstractPGProvider<Connection> {
+  private _pool: ConnectionPool
+
+  constructor(url?: URL | string) {
+    super()
+
+    if (! url) {
+      this._pool = new ConnectionPool(PSQLClient.logger)
+    } else {
+      if (typeof url === 'string') url = new URL(url)
+      assert(url.protocol === 'psql:', `Unsupported protocol "${url.protocol}"`)
+
+      const options: ConnectionPoolOptions = {}
+      if (url.username) options.user = decodeURIComponent(url.username)
+      if (url.password) options.password = decodeURIComponent(url.password)
+      if (url.hostname) options.host = url.hostname
+      if (url.port) options.port = Number(url.port)
+      if (url.pathname !== '/') options.database = url.pathname.substring(1)
+
+      setupPoolOptions(url, options)
+      this._pool = new ConnectionPool(PSQLClient.logger, options)
+    }
+  }
+
+  async acquire(): Promise<Connection> {
+    if (! this._pool.running) await this._pool.start()
+    return this._pool.acquire()
+  }
+
+  async release(connection: Connection): Promise<void> {
+    await this._pool.release(connection)
+  }
+
+  async destroy(): Promise<void> {
+    await this._pool.stop()
+  }
+}
+
+export class PSQLClient extends PGClient {
+  constructor(url?: URL | string) {
+    super(new PSQLProvider(url))
+  }
+
+  /* coverage ignore next */
+  static logger: Logger = {
+    debug: () => void 0,
+    info: () => void 0,
+    warn: () => void 0,
+    error: () => void 0,
+  }
+}
+
+registerProvider('psql', PSQLProvider)