dynalitics-postgres 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynalitics contributors
+
+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

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# dynalitics-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **PostgreSQL adapter** for [dynalitics](https://www.npmjs.com/package/dynalitics). `dynalitics` itself never loads a database driver; this package is the piece that connects it to PostgreSQL through [`pg`](https://node-postgres.com). It depends on `pg` (pinned to `8.23.1`) and nothing else, so installing it brings in exactly one driver.
+
+```sh
+npm install dynalitics dynalitics-postgres     # Node 22+, ESM only
+```
+
+## Usage
+
+Pass the exported `postgres` adapter as `adapter` when you create an instance. Everything else (table, consent, IP mode, the read API) is configured on `dynalitics`; see its README.
+
+```ts
+import { createDynalitics } from 'dynalitics';
+import { postgres } from 'dynalitics-postgres';
+
+const dyn = await createDynalitics({
+  adapter: postgres,
+  connection: {
+    writer: { connectionString: process.env.ANALYTICS_WRITER_URL! }, // INSERT only
+    reader: { connectionString: process.env.ANALYTICS_READER_URL! }, // SELECT only
+  },
+  table: 'public.dynalitics_events',
+});
+```
+
+Create the table first with `npx dynalitics sql --dialect postgres --table public.dynalitics_events --grants` (prints SQL, never connects).
+
+## What the adapter does
+
+**Connection strings.** For each credential it creates a `pg.Pool` with:
+
+| Setting                   | Value                                           |
+| ------------------------- | ----------------------------------------------- |
+| `max`                     | `poolSize` (writer 4, reader 2 by default)      |
+| `connectionTimeoutMillis` | `connectTimeoutMs` (10 s by default)            |
+| `idleTimeoutMillis`       | 30 s                                            |
+| `statement_timeout`       | 30 s, a server-side ceiling for every statement |
+
+TLS, host, port and database come from the connection string itself. Use `sslmode=require` for anything that is not on localhost. An idle connection that dies (server restart, network blip) never crashes your process: the pool's `error` event is handled.
+
+**Your own pool.** Pass `{ pool: yourPgPool }` instead of a connection string. dynalitics never closes it on `close()`.
+
+**Deadlines.** Every read runs on its own pooled client. When the read handler's deadline passes (`limits.timeoutMs`, 10 s by default), the adapter sends `SELECT pg_cancel_backend(pid)` (allowed for your own role, waits at most 2 s) and destroys that connection, so a slow query cannot keep running unseen. A pool without `connect()` only gets a client-side `query_timeout`; in that case set `statement_timeout` on the reader role yourself.
+
+**Errors.** The adapter never passes a raw `pg` error on. Data and constraint errors (SQLSTATE classes 22 and 23) forward no message text at all, because PostgreSQL prints the offending value. Permission errors (`42501`) become a fixed sentence. Connection, authentication and timeout errors keep their message, redacted and with quoted values removed. Connection drops, `57P0x` shutdowns, serialization failures and deadlocks (`40001`, `40P01`) and "too many connections" are marked transient, so the writer retries them.
+
+## Versions
+
+`dynalitics-postgres` and `dynalitics` are released together with the same version number, and the adapter declares `dynalitics` as a peer dependency at exactly that version. If the two ever disagree on the adapter contract, `createDynalitics` refuses to start and names both versions.
+
+Tested against PostgreSQL 17 (integration tests, local Docker).
+
+MIT licensed.

package/dist/driver.d.ts

@@ -0,0 +1,4 @@
+import { type Classification, type Driver, type DriverOptions } from 'dynalitics/adapter';
+export declare function classifyPg(err: unknown): Classification;
+export declare function createPostgresDriver(o: DriverOptions): Promise<Driver>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.js

@@ -0,0 +1,111 @@
+import pgModule from 'pg';
+import { DEFAULT_REQUEST_TIMEOUT_MS, IDLE_TIMEOUT_MS, errCode, errMessage, isTransientError, toDriverError, } from 'dynalitics/adapter';
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    '57P01',
+    '57P02',
+    '57P03',
+    '53300',
+    '53400',
+    '40001',
+    '40P01',
+]);
+const CANCEL_GUARD_MS = 2000;
+export function classifyPg(err) {
+    const code = errCode(err);
+    const msg = errMessage(err);
+    const timeout = msg.includes('read timeout') || msg.includes('statement timeout') || code === '57014';
+    const transient = timeout ||
+        TRANSIENT_CODES.has(code) ||
+        code.startsWith('08') ||
+        msg.includes('connection terminated') ||
+        msg.includes('connection timeout');
+    return {
+        transient,
+        timeout,
+        // SQLSTATE class 22 (data exception) and 23 (integrity constraint violation)
+        data: /^(22|23)/.test(code),
+        permission: code === '42501',
+        // connection (08), network, server shutdown (57P0x) and invalid authorization (28xxx) classes
+        forward: transient || code.startsWith('28') || code === 'ENOTFOUND' || code === 'EAI_AGAIN',
+    };
+}
+/** Asks the server to stop the backend (own-role queries only), never waiting longer than CANCEL_GUARD_MS. */
+async function cancelBackend(pool, pid) {
+    if (pid === undefined)
+        return;
+    const attempt = pool
+        .query({ text: 'SELECT pg_cancel_backend($1)', values: [pid], query_timeout: CANCEL_GUARD_MS })
+        .then(() => undefined, () => undefined);
+    await Promise.race([
+        attempt,
+        new Promise((resolve) => setTimeout(resolve, CANCEL_GUARD_MS).unref?.()),
+    ]);
+}
+// async on purpose: a throwing pool constructor must become a rejection, not a synchronous throw.
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function createPostgresDriver(o) {
+    let pool;
+    let owned = false;
+    if ('pool' in o.credential) {
+        pool = o.credential.pool;
+    }
+    else {
+        const pg = pgModule;
+        pool = new pg.Pool({
+            connectionString: o.credential.connectionString,
+            max: o.max,
+            connectionTimeoutMillis: o.connectTimeoutMs,
+            idleTimeoutMillis: IDLE_TIMEOUT_MS,
+            statement_timeout: o.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        });
+        // An idle client dying must not crash the host process with an unhandled 'error' event.
+        pool.on?.('error', () => undefined);
+        owned = true;
+    }
+    /** Host pools without connect(): client-side deadline only (the host must set statement_timeout). */
+    async function viaPool(sql, params, timeoutMs) {
+        return (await pool.query({ text: sql, values: [...params], query_timeout: timeoutMs })).rows;
+    }
+    async function viaClient(connect, sql, params, timeoutMs) {
+        const client = await connect();
+        let destroy = false;
+        try {
+            const running = client.query({ text: sql, values: [...params] });
+            running.catch(() => undefined); // an abandoned query may reject later; that must never be unhandled
+            const result = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    destroy = true;
+                    // The slot is only freed after the cancel was attempted and the connection is being destroyed.
+                    void cancelBackend(pool, client.processID).then(() => reject(new Error('Query read timeout')));
+                }, timeoutMs);
+                running.then((r) => (clearTimeout(timer), resolve(r)), (e) => (clearTimeout(timer), reject(e)));
+            });
+            return result.rows;
+        }
+        finally {
+            client.release(destroy);
+        }
+    }
+    return {
+        async query(q, { timeoutMs }) {
+            try {
+                return pool.connect === undefined
+                    ? await viaPool(q.sql, q.params, timeoutMs)
+                    : await viaClient(() => pool.connect?.(), q.sql, q.params, timeoutMs);
+            }
+            catch (err) {
+                throw toDriverError(err, o.redact, classifyPg);
+            }
+        },
+        isTransient: isTransientError,
+        async close() {
+            if (owned)
+                await pool.end?.();
+        },
+    };
+}
+//# sourceMappingURL=driver.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { DriverAdapter } from 'dynalitics/adapter';
+/**
+ * The PostgreSQL adapter for dynalitics: `createDynalitics({ adapter: postgres, ... })`.
+ * apiVersion is a literal on purpose: it states the contract THIS package was built for (spec 5.2).
+ */
+export declare const postgres: DriverAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+import { createPostgresDriver } from './driver.js';
+/**
+ * The PostgreSQL adapter for dynalitics: `createDynalitics({ adapter: postgres, ... })`.
+ * apiVersion is a literal on purpose: it states the contract THIS package was built for (spec 5.2).
+ */
+export const postgres = Object.freeze({
+    apiVersion: 1,
+    dialect: 'postgres',
+    packageName: 'dynalitics-postgres',
+    createDriver: createPostgresDriver,
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "dynalitics-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "PostgreSQL adapter for dynalitics: brings in the pg driver and nothing else.",
+  "keywords": [
+    "analytics",
+    "dynalitics",
+    "postgres",
+    "pg",
+    "adapter"
+  ],
+  "license": "MIT",
+  "author": "dynalitics contributors",
+  "homepage": "https://github.com/lucsoftsl/dynalitics/tree/main/packages/dynalitics-postgres#readme",
+  "bugs": {
+    "url": "https://github.com/lucsoftsl/dynalitics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucsoftsl/dynalitics.git",
+    "directory": "packages/dynalitics-postgres"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "pg": "8.23.1"
+  },
+  "peerDependencies": {
+    "dynalitics": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}