@owlmeans/postgres 0.1.18-rc.22 → 0.1.18-rc.24

package/README.md

@@ -14,7 +14,7 @@ provisioning, and an opt-in least-privilege bootstrap path.
 ## Installation
 
 ```bash
-bun add @owlmeans/postgres@^0.1.18-rc.13 @owlmeans/postgres-resource@^0.1.18-rc.12
+bun add @owlmeans/postgres@^0.1.18-rc.23 @owlmeans/postgres-resource@^0.1.18-rc.22
 ```
 
 ## Usage
@@ -129,7 +129,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.22
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/postgres",
-  "version": "0.1.18-rc.22",
-  "generatedAt": "2026-09-12T14:18:54.800Z",
+  "version": "0.1.18-rc.24",
+  "generatedAt": "2026-09-15T12:38:15.244Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/postgres/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/postgres
 
 **Layer:** Infra
-**Install:** `"@owlmeans/postgres": "^0.1.18-rc.22"` in `dependencies`
+**Install:** `"@owlmeans/postgres": "^0.1.18-rc.24"` in `dependencies`
 
 Pooled `pg` connections for a server context, plus the admin path that provisions the role, database
 and schema an app connects with. All DDL for application tables belongs to [[postgres-resource]] —

package/build/health.d.ts

@@ -0,0 +1,40 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+export interface DbHealth {
+    ok: boolean;
+    /** One line fit for a boot log — states what was checked, not only whether it passed. */
+    summary: string;
+    error?: string;
+}
+/**
+ * The outcome of the last {@link checkDbHealth} for the same pair of aliases.
+ *
+ * A request time handler wants the verdict of the boot check without paying for it again: the
+ * structure was reconciled once, at init, and re-asserting it per request buys nothing.
+ */
+export declare const getLastDbHealth: (alias?: string, configAlias?: string) => DbHealth | undefined;
+/**
+ * Surface the Postgres fields (code/severity/detail/hint) an error carries — a bare `.message`
+ * hides the real FATAL/permission reason, and the cause chain is where the driver's error ends up
+ * once a resource wraps it.
+ */
+export declare const formatDbError: (error: unknown) => string;
+/**
+ * Liveness only, through the context's own pool — no private client, no connection string, no
+ * migration journal. The service is looked up by alias exactly as any other consumer looks it up,
+ * so a health probe cannot end up connected differently from the app it reports on.
+ *
+ * The context arrives as an argument rather than as a module import: a handler is given the
+ * context that actually served the request (possibly an entity scoped derivative), and taking it
+ * as a parameter keeps this module out of the boot import cycle.
+ */
+export declare const pingDb: (context: BasicContext<BasicConfig>, alias?: string, configAlias?: string) => Promise<DbHealth>;
+/**
+ * The boot gate check: wait for the service to be ready, then assert the connection still works.
+ *
+ * Structure is reconciled by the resources during the context's `init()`; if that succeeded the
+ * tables are correct by construction, and if it failed the process never got here. There is
+ * nothing left to assert beyond "the connection works", which is why this is a `SELECT 1` and not
+ * a schema walk. The result is cached for {@link getLastDbHealth}.
+ */
+export declare const checkDbHealth: (context: BasicContext<BasicConfig>, alias?: string, configAlias?: string) => Promise<DbHealth>;
+//# sourceMappingURL=health.d.ts.map

package/build/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,OAAO,CAAA;IACX,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,WACnB,MAAM,gBAAgC,MAAM,KAClD,QAAQ,GAAG,SAAsD,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,aAAa,UAAW,OAAO,KAAG,MAmB9C,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,YACR,YAAY,CAAC,WAAW,CAAC,UAAS,MAAM,gBAAgC,MAAM,KACtF,OAAO,CAAC,QAAQ,CASlB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,YACf,YAAY,CAAC,WAAW,CAAC,UAAS,MAAM,gBAAgC,MAAM,KACtF,OAAO,CAAC,QAAQ,CAelB,CAAA"}

package/build/health.js

@@ -0,0 +1,80 @@
+import { DEFAULT_ALIAS } from './consts.js';
+const lastHealth = new Map();
+const keyOf = (alias, configAlias) => `${alias}:${configAlias ?? ''}`;
+/**
+ * The outcome of the last {@link checkDbHealth} for the same pair of aliases.
+ *
+ * A request time handler wants the verdict of the boot check without paying for it again: the
+ * structure was reconciled once, at init, and re-asserting it per request buys nothing.
+ */
+export const getLastDbHealth = (alias = DEFAULT_ALIAS, configAlias) => lastHealth.get(keyOf(alias, configAlias));
+/**
+ * Surface the Postgres fields (code/severity/detail/hint) an error carries — a bare `.message`
+ * hides the real FATAL/permission reason, and the cause chain is where the driver's error ends up
+ * once a resource wraps it.
+ */
+export const formatDbError = (error) => {
+    const parts = [];
+    const seen = new Set();
+    let current = error;
+    while (current != null && !seen.has(current)) {
+        seen.add(current);
+        const meta = [];
+        if (current.severity != null)
+            meta.push(`severity=${current.severity}`);
+        if (current.code != null)
+            meta.push(`code=${current.code}`);
+        if (current.detail != null)
+            meta.push(`detail=${current.detail}`);
+        if (current.hint != null)
+            meta.push(`hint=${current.hint}`);
+        const message = current.message ?? String(current);
+        parts.push(meta.length > 0 ? `${message} (${meta.join(', ')})` : message);
+        current = current.cause;
+    }
+    const joined = parts.join('; caused by: ');
+    return joined !== '' ? joined : String(error);
+};
+/**
+ * Liveness only, through the context's own pool — no private client, no connection string, no
+ * migration journal. The service is looked up by alias exactly as any other consumer looks it up,
+ * so a health probe cannot end up connected differently from the app it reports on.
+ *
+ * The context arrives as an argument rather than as a module import: a handler is given the
+ * context that actually served the request (possibly an entity scoped derivative), and taking it
+ * as a parameter keeps this module out of the boot import cycle.
+ */
+export const pingDb = async (context, alias = DEFAULT_ALIAS, configAlias) => {
+    try {
+        const pool = await context.service(alias).client(configAlias);
+        await pool.query('SELECT 1');
+        return { ok: true, summary: 'DB reachable' };
+    }
+    catch (error) {
+        return { ok: false, summary: 'DB unreachable', error: formatDbError(error) };
+    }
+};
+/**
+ * The boot gate check: wait for the service to be ready, then assert the connection still works.
+ *
+ * Structure is reconciled by the resources during the context's `init()`; if that succeeded the
+ * tables are correct by construction, and if it failed the process never got here. There is
+ * nothing left to assert beyond "the connection works", which is why this is a `SELECT 1` and not
+ * a schema walk. The result is cached for {@link getLastDbHealth}.
+ */
+export const checkDbHealth = async (context, alias = DEFAULT_ALIAS, configAlias) => {
+    let result;
+    try {
+        const service = context.service(alias);
+        await service.ready();
+        const pool = await service.client(configAlias);
+        await pool.query('SELECT 1');
+        result = { ok: true, summary: 'DB OK — connected; structure reconciled at init' };
+    }
+    catch (error) {
+        result = { ok: false, summary: 'DB check failed', error: formatDbError(error) };
+    }
+    lastHealth.set(keyOf(alias, configAlias), result);
+    return result;
+};
+//# sourceMappingURL=health.js.map

package/build/health.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/postgres",
-  "version": "0.1.18-rc.22",
+  "version": "0.1.18-rc.24",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,17 +22,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/basic-keys": "^0.1.18-rc.20",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/postgres-resource": "^0.1.18-rc.21",
-    "@owlmeans/resource": "^0.1.18-rc.17",
-    "@owlmeans/server-context": "^0.1.18-rc.20",
+    "@owlmeans/basic-keys": "^0.1.18-rc.22",
+    "@owlmeans/context": "^0.1.18-rc.18",
+    "@owlmeans/postgres-resource": "^0.1.18-rc.23",
+    "@owlmeans/resource": "^0.1.18-rc.19",
+    "@owlmeans/server-context": "^0.1.18-rc.22",
     "drizzle-orm": "~0.45.2",
     "pg": "^8.22.0"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-integration": "^0.1.18-rc.16",
+    "@owlmeans/test-integration": "^0.1.18-rc.18",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "@types/pg": "^8.20.4",