@owlmeans/postgres 0.1.18-rc.12 → 0.1.18-rc.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -2
- package/agent-meta/manifest.json +2 -2
- package/agent-meta/skills/postgres/SKILL.md +65 -14
- package/build/bootstrap.d.ts.map +1 -1
- package/build/health.d.ts +40 -0
- package/build/health.d.ts.map +1 -0
- package/build/health.js +80 -0
- package/build/health.js.map +1 -0
- package/build/index.d.ts +1 -0
- package/build/index.d.ts.map +1 -1
- package/build/index.js +1 -0
- package/build/index.js.map +1 -1
- package/build/middleware.d.ts.map +1 -1
- package/build/middleware.js.map +1 -1
- package/build/service.d.ts.map +1 -1
- package/build/service.js.map +1 -1
- package/build/utils/config.d.ts.map +1 -1
- package/build/utils/connection.d.ts.map +1 -1
- package/package.json +7 -7
- package/src/health.ts +100 -0
- package/src/index.ts +1 -0
package/README.md
CHANGED
|
@@ -10,11 +10,12 @@ provisioning, and an opt-in least-privilege bootstrap path.
|
|
|
10
10
|
- Reads connection config from `context.cfg.dbs` entries whose `service` is `'postgres'`
|
|
11
11
|
- Backs `@owlmeans/postgres-resource`; the resource layer owns all DDL
|
|
12
12
|
- `bootstrap()` provisions a role, database and schema from a separate superuser config alias
|
|
13
|
+
- `checkDbHealth()` / `pingDb()` answer a health endpoint through the registered service
|
|
13
14
|
|
|
14
15
|
## Installation
|
|
15
16
|
|
|
16
17
|
```bash
|
|
17
|
-
bun add @owlmeans/postgres @owlmeans/postgres-resource
|
|
18
|
+
bun add @owlmeans/postgres@^0.1.18-rc.13 @owlmeans/postgres-resource@^0.1.18-rc.12
|
|
18
19
|
```
|
|
19
20
|
|
|
20
21
|
## Usage
|
|
@@ -53,6 +54,36 @@ At `init()` the service opens a pool, runs a `SELECT 1` readiness probe (30 atte
|
|
|
53
54
|
default — a Postgres sidecar routinely accepts TCP before it accepts queries), issues
|
|
54
55
|
`CREATE SCHEMA IF NOT EXISTS`, and installs a `SIGTERM` handler that drains the pool.
|
|
55
56
|
|
|
57
|
+
### Health checks
|
|
58
|
+
|
|
59
|
+
`pingDb` and `checkDbHealth` go through the **registered service**, looked up by alias exactly the
|
|
60
|
+
way any other consumer looks it up — never a connection string of their own, so a probe can never
|
|
61
|
+
report on a connection the app does not use.
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
import { checkDbHealth, pingDb, getLastDbHealth } from '@owlmeans/postgres'
|
|
65
|
+
|
|
66
|
+
// Boot gate — after the context's init(), before the API server binds.
|
|
67
|
+
const health = await checkDbHealth(context)
|
|
68
|
+
if (!health.ok) throw new Error(health.error ?? health.summary)
|
|
69
|
+
console.log(`[db-check] ${health.summary}`)
|
|
70
|
+
|
|
71
|
+
// Request time — inside a health entrypoint handler, with the context it was given.
|
|
72
|
+
const live = await pingDb(ctx)
|
|
73
|
+
const boot = getLastDbHealth()
|
|
74
|
+
return { db: { ok: live.ok && (boot?.ok ?? true), summary: boot?.summary ?? live.summary } }
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Both return `{ ok, summary, error? }` and never throw; a driver failure is formatted by
|
|
78
|
+
`formatDbError`, which walks the `cause` chain and surfaces the Postgres `severity`/`code`/`detail`/
|
|
79
|
+
`hint` a bare `.message` hides. `checkDbHealth` awaits `service.ready()` and caches its verdict for
|
|
80
|
+
`getLastDbHealth(alias?, configAlias?)`; `pingDb` is a bare `SELECT 1` on the pool and caches
|
|
81
|
+
nothing. Neither inspects the schema — structure is reconciled by the resources at `init()`, so a
|
|
82
|
+
process that is serving at all has the tables it was built with.
|
|
83
|
+
|
|
84
|
+
The context is a parameter, not a module import: a handler is given the context that actually
|
|
85
|
+
served the request, and passing it keeps these functions out of the boot import cycle.
|
|
86
|
+
|
|
56
87
|
### Bootstrap (admin path)
|
|
57
88
|
|
|
58
89
|
Hold the superuser connection under a **separate** config alias so the application's own entry never
|
|
@@ -100,6 +131,14 @@ Extends `PostgresDbService` from `@owlmeans/postgres-resource`:
|
|
|
100
131
|
- `lock` / `unlock` — AES field encryption via `config.encryptionKey`
|
|
101
132
|
- `bootstrap(configAlias, opts): Promise<BootstrapReport>`
|
|
102
133
|
|
|
134
|
+
### Health
|
|
135
|
+
|
|
136
|
+
- `pingDb(context, alias?, configAlias?): Promise<DbHealth>` — liveness through the pool
|
|
137
|
+
- `checkDbHealth(context, alias?, configAlias?): Promise<DbHealth>` — `ready()` + liveness, cached
|
|
138
|
+
- `getLastDbHealth(alias?, configAlias?): DbHealth | undefined` — the last cached verdict
|
|
139
|
+
- `formatDbError(error): string` — cause-chain formatter with `severity`/`code`/`detail`/`hint`
|
|
140
|
+
- `DbHealth` — `{ ok: boolean, summary: string, error?: string }`
|
|
141
|
+
|
|
103
142
|
### Helpers
|
|
104
143
|
|
|
105
144
|
- `parseUrl(url)` / `prepareConfig(config, overrides?)` / `poolDatabase(pool)`
|
|
@@ -129,7 +168,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
|
|
|
129
168
|
your project's skill store (`.agents/skills/`):
|
|
130
169
|
|
|
131
170
|
```sh
|
|
132
|
-
npx @owlmeans/agent-skills
|
|
171
|
+
npx @owlmeans/agent-skills@^0.1.18-rc.12
|
|
133
172
|
```
|
|
134
173
|
|
|
135
174
|
The embedded files are version-matched to this package release. Do not edit them
|
package/agent-meta/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 2,
|
|
3
3
|
"package": "@owlmeans/postgres",
|
|
4
|
-
"version": "0.1.18-rc.
|
|
5
|
-
"generatedAt": "2026-09-
|
|
4
|
+
"version": "0.1.18-rc.14",
|
|
5
|
+
"generatedAt": "2026-09-04T22:43:25.454Z",
|
|
6
6
|
"canonicalRepo": "https://github.com/owlmeans/common",
|
|
7
7
|
"entries": [
|
|
8
8
|
{
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: postgres
|
|
3
|
-
description: How to use @owlmeans/postgres — PostgreSQL connection service (makePostgresDbService / appendPostgres) registered on a server context, plus the least-privilege bootstrap admin path. Auto-invoked when wiring PostgreSQL into a server app.
|
|
3
|
+
description: How to use @owlmeans/postgres — PostgreSQL connection service (makePostgresDbService / appendPostgres) registered on a server context, its health checks, plus the least-privilege bootstrap admin path. Auto-invoked when wiring PostgreSQL into a server app.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
|
|
@@ -8,7 +8,7 @@ user-invocable: false
|
|
|
8
8
|
# @owlmeans/postgres
|
|
9
9
|
|
|
10
10
|
**Layer:** Infra
|
|
11
|
-
**Install:** `"@owlmeans/postgres": "^0.1.18-rc.
|
|
11
|
+
**Install:** `"@owlmeans/postgres": "^0.1.18-rc.14"` in `dependencies`
|
|
12
12
|
|
|
13
13
|
Pooled `pg` connections for a server context, plus the admin path that provisions the role, database
|
|
14
14
|
and schema an app connects with. All DDL for application tables belongs to [[postgres-resource]] —
|
|
@@ -21,7 +21,9 @@ this package only creates the schema those tables live in.
|
|
|
21
21
|
| `makePostgresDbService(alias?)` | The connection service. `alias` defaults to `DEFAULT_ALIAS` (`'postgres'`). |
|
|
22
22
|
| `appendPostgres(context, alias?)` | Registers the service **and** its drain middleware. Use this, not a bare `registerService`. |
|
|
23
23
|
| `PostgresService` | `PostgresDbService` + `bootstrap(configAlias, opts)`. |
|
|
24
|
-
| `BootstrapOptions`, `BootstrapReport`, `bootstrapDb` | The admin path
|
|
24
|
+
| `BootstrapOptions`, `BootstrapReport`, `bootstrapDb` | The admin path. `bootstrapDb(service, configAlias, opts)` is what `service.bootstrap(configAlias, opts)` calls — both read the config through a **context-bound** service, so neither runs outside a context. |
|
|
25
|
+
| `pingDb(context, alias?, configAlias?)` / `checkDbHealth(...)` | Health checks through the registered service; `DbHealth` = `{ ok, summary, error? }`. |
|
|
26
|
+
| `getLastDbHealth(alias?, configAlias?)` / `formatDbError(error)` | The cached verdict, and the cause-chain error formatter. |
|
|
25
27
|
| `drainMiddleware(alias?)` | Drains work deferred until every resource has initialized. |
|
|
26
28
|
| `parseUrl`, `prepareConfig`, `poolDatabase`, `probe`, `ensureSchema` | Config and connection helpers. |
|
|
27
29
|
| `DEFAULT_ALIAS`, `DEF_ADMIN_ALIAS`, `DEF_MAINTENANCE_DB`, `DEF_PORT`, `DEF_POOL_SIZE`, `DEF_RETRIES`, `DEF_RETRY_DELAY`, `TERMINAL_CONNECT_CODES` | Constants. |
|
|
@@ -50,7 +52,7 @@ cfg.dbs = [{
|
|
|
50
52
|
for a `DATABASE_URL` env var. Because a leading `/` is auto-read, moving to file-mounted secrets
|
|
51
53
|
later is a config change, not a code change.
|
|
52
54
|
|
|
53
|
-
**`schema` is the SCHEMA, not the database.** `
|
|
55
|
+
**`schema` is the SCHEMA, not the database.** The service's `name(alias?)` returns it as given
|
|
54
56
|
(`config.schema ?? config.alias ?? service.alias`), so a separate namespace costs a `CREATE SCHEMA`
|
|
55
57
|
inside a shared database rather than a `CREATE DATABASE`. The database comes from `meta.database`.
|
|
56
58
|
|
|
@@ -59,11 +61,27 @@ Other `meta` keys: `autoSync` (see [[postgres-resource]]), `ssl`, `max`, `idleTi
|
|
|
59
61
|
|
|
60
62
|
## What `init()` does
|
|
61
63
|
|
|
62
|
-
Opens a `pg.Pool` →
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
64
|
+
Opens a `pg.Pool` → attaches the pool's `error` handler → `SELECT 1` readiness probe
|
|
65
|
+
(`DEF_RETRIES` 30 attempts, `DEF_RETRY_DELAY` 2s apart, both overridable through
|
|
66
|
+
`meta.retries`/`meta.retryDelayMillis`) → `SIGTERM` handler that drains the pool → registers the
|
|
67
|
+
client → `CREATE SCHEMA IF NOT EXISTS`.
|
|
68
|
+
|
|
69
|
+
Do **not** hand-roll the retry loop around it: a Postgres sidecar routinely accepts TCP before it
|
|
70
|
+
accepts queries, which is precisely what the probe is for. Credential, missing-database and
|
|
71
|
+
permission failures (`TERMINAL_CONNECT_CODES`) fail immediately instead of burning the full retry
|
|
72
|
+
budget on an error that will never clear. A probe that gives up ends the pool before raising, so a
|
|
73
|
+
failed boot leaves no sockets behind.
|
|
74
|
+
|
|
75
|
+
**The schema is created only when the config entry names one.** `config.schema` absent means no
|
|
76
|
+
`CREATE SCHEMA` at all — an entry that identifies its database through `meta.database` or
|
|
77
|
+
`meta.url` and omits `schema` gets none, deliberately: resources create the schema they need
|
|
78
|
+
anyway, and inventing one from the service alias would leave an empty `postgres` schema behind on
|
|
79
|
+
every boot of the admin connection.
|
|
80
|
+
|
|
81
|
+
**The pool's `error` handler is not optional.** `node-postgres` emits `error` on *idle* clients
|
|
82
|
+
whenever the server closes a connection — routine behind a load balancer — and an unhandled
|
|
83
|
+
`error` on an EventEmitter terminates the process. The service attaches one that logs; a pool you
|
|
84
|
+
open yourself needs the same.
|
|
67
85
|
|
|
68
86
|
Keep the pool small. Postgres caps connections cluster-wide (`max_connections`, 100 by default), so
|
|
69
87
|
an oversized per-process pool starves every other client of the same server — the opposite of the
|
|
@@ -73,7 +91,8 @@ Mongo driver's tuning instinct.
|
|
|
73
91
|
|
|
74
92
|
`db(alias?)` → `{ drizzle, pool, schema, database }` · `client(alias?)` / `clients` ·
|
|
75
93
|
`qualify(resourceAlias, configAlias?)` · `query(text, params?, configAlias?)` ·
|
|
76
|
-
`transaction(fn, configAlias?)` · `lock`/`unlock` (
|
|
94
|
+
`transaction(fn, configAlias?)` · `lock`/`unlock` (field encryption through
|
|
95
|
+
`makeKeyPairModel(config.encryptionKey)` from `@owlmeans/basic-keys`) ·
|
|
77
96
|
`defer(configAlias, task)` / `drain(configAlias?)`.
|
|
78
97
|
|
|
79
98
|
`defer` exists for work that can't run during one resource's `init()` because it points at another
|
|
@@ -81,6 +100,35 @@ resource that hasn't initialized yet — foreign keys, above all. Queue it; the
|
|
|
81
100
|
`appendPostgres` registers drains it once the context is up. Do not reorder resource registrations
|
|
82
101
|
to work around this.
|
|
83
102
|
|
|
103
|
+
## Health
|
|
104
|
+
|
|
105
|
+
Do not hand-roll a health check, and never open a connection of your own for one: `pingDb` and
|
|
106
|
+
`checkDbHealth` resolve the service by alias exactly as any other consumer does, so a probe can
|
|
107
|
+
never report on a connection the app does not use. Both return `{ ok, summary, error? }` and never
|
|
108
|
+
throw.
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
const health = await checkDbHealth(context) // boot gate, after init()
|
|
112
|
+
if (!health.ok) throw new Error(health.error ?? health.summary)
|
|
113
|
+
|
|
114
|
+
const live = await pingDb(ctx) // request time, in a health handler
|
|
115
|
+
const boot = getLastDbHealth()
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`checkDbHealth` awaits `service.ready()`, runs `SELECT 1` and caches its verdict for
|
|
119
|
+
`getLastDbHealth`; `pingDb` is the bare `SELECT 1` and caches nothing. Neither inspects the schema
|
|
120
|
+
— structure is reconciled by the resources during `init()`, so a process that reached the check has
|
|
121
|
+
the tables it was built with and there is nothing left to assert beyond "the connection works".
|
|
122
|
+
|
|
123
|
+
The context is a parameter, not a module import: a handler is handed the context that actually
|
|
124
|
+
served the request (possibly an entity-scoped derivative), and passing it keeps these functions out
|
|
125
|
+
of the boot import cycle. Errors go through `formatDbError`, which walks the `cause` chain and
|
|
126
|
+
surfaces the `severity`/`code`/`detail`/`hint` a bare `.message` hides — that is where the real
|
|
127
|
+
FATAL/permission reason lives.
|
|
128
|
+
|
|
129
|
+
Pair it with the bind-first boot in [[server-app]]: `checkDbHealth` is the boot gate, and a failure
|
|
130
|
+
becomes `setBootPhase('failed', …)` on a port that is already bound.
|
|
131
|
+
|
|
84
132
|
## Bootstrap — the admin path
|
|
85
133
|
|
|
86
134
|
Superuser credentials belong to a **separate config alias**. The application's own entry connects as
|
|
@@ -94,10 +142,13 @@ await context.service<PostgresService>('postgres').bootstrap('pg-admin', {
|
|
|
94
142
|
|
|
95
143
|
Idempotent by design — every OwlMeans deployment calls it on each start and each rebuild. It probes
|
|
96
144
|
`pg_roles` / `pg_database` before creating, rotates the password of an existing role (the caller
|
|
97
|
-
generated the password it just passed in, so the role has to accept it)
|
|
98
|
-
applies `REVOKE CONNECT … FROM PUBLIC`,
|
|
99
|
-
`GRANT CONNECT … TO <role>`,
|
|
100
|
-
|
|
145
|
+
generated the password it just passed in, so the role has to accept it). The two grant branches are
|
|
146
|
+
independent: `leastPrivilege` applies `REVOKE CONNECT … FROM PUBLIC`,
|
|
147
|
+
`REVOKE CREATE ON SCHEMA public FROM PUBLIC` and `GRANT CONNECT … TO <role>`, while `schema`
|
|
148
|
+
applies `CREATE SCHEMA … AUTHORIZATION <role>`, `GRANT ALL ON SCHEMA … TO <role>` and
|
|
149
|
+
`ALTER ROLE … SET search_path`. **`search_path` comes from `schema`** — a call with
|
|
150
|
+
`leastPrivilege` and no `schema` sets none. The returned `BootstrapReport` says what actually
|
|
151
|
+
changed. Identifiers are validated and quoted; the password is the only literal.
|
|
101
152
|
|
|
102
153
|
**This replaces hand-written bootstrap SQL.** If you find `CREATE ROLE` / `CREATE DATABASE` /
|
|
103
154
|
`GRANT` strings in a deployment script, a provisioner, or a `DEPLOYMENT.md`, they are a duplicate of
|
package/build/bootstrap.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AASpF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,
|
|
1
|
+
{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AASpF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,YACb,eAAe,eAAe,MAAM,QAAQ,gBAAgB,KACpE,OAAO,CAAC,eAAe,CAwFzB,CAAA"}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { BasicConfig, BasicContext } from '@owlmeans/context';
|
|
2
|
+
export interface DbHealth {
|
|
3
|
+
ok: boolean;
|
|
4
|
+
/** One line fit for a boot log — states what was checked, not only whether it passed. */
|
|
5
|
+
summary: string;
|
|
6
|
+
error?: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The outcome of the last {@link checkDbHealth} for the same pair of aliases.
|
|
10
|
+
*
|
|
11
|
+
* A request time handler wants the verdict of the boot check without paying for it again: the
|
|
12
|
+
* structure was reconciled once, at init, and re-asserting it per request buys nothing.
|
|
13
|
+
*/
|
|
14
|
+
export declare const getLastDbHealth: (alias?: string, configAlias?: string) => DbHealth | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* Surface the Postgres fields (code/severity/detail/hint) an error carries — a bare `.message`
|
|
17
|
+
* hides the real FATAL/permission reason, and the cause chain is where the driver's error ends up
|
|
18
|
+
* once a resource wraps it.
|
|
19
|
+
*/
|
|
20
|
+
export declare const formatDbError: (error: unknown) => string;
|
|
21
|
+
/**
|
|
22
|
+
* Liveness only, through the context's own pool — no private client, no connection string, no
|
|
23
|
+
* migration journal. The service is looked up by alias exactly as any other consumer looks it up,
|
|
24
|
+
* so a health probe cannot end up connected differently from the app it reports on.
|
|
25
|
+
*
|
|
26
|
+
* The context arrives as an argument rather than as a module import: a handler is given the
|
|
27
|
+
* context that actually served the request (possibly an entity scoped derivative), and taking it
|
|
28
|
+
* as a parameter keeps this module out of the boot import cycle.
|
|
29
|
+
*/
|
|
30
|
+
export declare const pingDb: (context: BasicContext<BasicConfig>, alias?: string, configAlias?: string) => Promise<DbHealth>;
|
|
31
|
+
/**
|
|
32
|
+
* The boot gate check: wait for the service to be ready, then assert the connection still works.
|
|
33
|
+
*
|
|
34
|
+
* Structure is reconciled by the resources during the context's `init()`; if that succeeded the
|
|
35
|
+
* tables are correct by construction, and if it failed the process never got here. There is
|
|
36
|
+
* nothing left to assert beyond "the connection works", which is why this is a `SELECT 1` and not
|
|
37
|
+
* a schema walk. The result is cached for {@link getLastDbHealth}.
|
|
38
|
+
*/
|
|
39
|
+
export declare const checkDbHealth: (context: BasicContext<BasicConfig>, alias?: string, configAlias?: string) => Promise<DbHealth>;
|
|
40
|
+
//# sourceMappingURL=health.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { DEFAULT_ALIAS } from './consts.js';
|
|
2
|
+
const lastHealth = new Map();
|
|
3
|
+
const keyOf = (alias, configAlias) => `${alias}:${configAlias ?? ''}`;
|
|
4
|
+
/**
|
|
5
|
+
* The outcome of the last {@link checkDbHealth} for the same pair of aliases.
|
|
6
|
+
*
|
|
7
|
+
* A request time handler wants the verdict of the boot check without paying for it again: the
|
|
8
|
+
* structure was reconciled once, at init, and re-asserting it per request buys nothing.
|
|
9
|
+
*/
|
|
10
|
+
export const getLastDbHealth = (alias = DEFAULT_ALIAS, configAlias) => lastHealth.get(keyOf(alias, configAlias));
|
|
11
|
+
/**
|
|
12
|
+
* Surface the Postgres fields (code/severity/detail/hint) an error carries — a bare `.message`
|
|
13
|
+
* hides the real FATAL/permission reason, and the cause chain is where the driver's error ends up
|
|
14
|
+
* once a resource wraps it.
|
|
15
|
+
*/
|
|
16
|
+
export const formatDbError = (error) => {
|
|
17
|
+
const parts = [];
|
|
18
|
+
const seen = new Set();
|
|
19
|
+
let current = error;
|
|
20
|
+
while (current != null && !seen.has(current)) {
|
|
21
|
+
seen.add(current);
|
|
22
|
+
const meta = [];
|
|
23
|
+
if (current.severity != null)
|
|
24
|
+
meta.push(`severity=${current.severity}`);
|
|
25
|
+
if (current.code != null)
|
|
26
|
+
meta.push(`code=${current.code}`);
|
|
27
|
+
if (current.detail != null)
|
|
28
|
+
meta.push(`detail=${current.detail}`);
|
|
29
|
+
if (current.hint != null)
|
|
30
|
+
meta.push(`hint=${current.hint}`);
|
|
31
|
+
const message = current.message ?? String(current);
|
|
32
|
+
parts.push(meta.length > 0 ? `${message} (${meta.join(', ')})` : message);
|
|
33
|
+
current = current.cause;
|
|
34
|
+
}
|
|
35
|
+
const joined = parts.join('; caused by: ');
|
|
36
|
+
return joined !== '' ? joined : String(error);
|
|
37
|
+
};
|
|
38
|
+
/**
|
|
39
|
+
* Liveness only, through the context's own pool — no private client, no connection string, no
|
|
40
|
+
* migration journal. The service is looked up by alias exactly as any other consumer looks it up,
|
|
41
|
+
* so a health probe cannot end up connected differently from the app it reports on.
|
|
42
|
+
*
|
|
43
|
+
* The context arrives as an argument rather than as a module import: a handler is given the
|
|
44
|
+
* context that actually served the request (possibly an entity scoped derivative), and taking it
|
|
45
|
+
* as a parameter keeps this module out of the boot import cycle.
|
|
46
|
+
*/
|
|
47
|
+
export const pingDb = async (context, alias = DEFAULT_ALIAS, configAlias) => {
|
|
48
|
+
try {
|
|
49
|
+
const pool = await context.service(alias).client(configAlias);
|
|
50
|
+
await pool.query('SELECT 1');
|
|
51
|
+
return { ok: true, summary: 'DB reachable' };
|
|
52
|
+
}
|
|
53
|
+
catch (error) {
|
|
54
|
+
return { ok: false, summary: 'DB unreachable', error: formatDbError(error) };
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* The boot gate check: wait for the service to be ready, then assert the connection still works.
|
|
59
|
+
*
|
|
60
|
+
* Structure is reconciled by the resources during the context's `init()`; if that succeeded the
|
|
61
|
+
* tables are correct by construction, and if it failed the process never got here. There is
|
|
62
|
+
* nothing left to assert beyond "the connection works", which is why this is a `SELECT 1` and not
|
|
63
|
+
* a schema walk. The result is cached for {@link getLastDbHealth}.
|
|
64
|
+
*/
|
|
65
|
+
export const checkDbHealth = async (context, alias = DEFAULT_ALIAS, configAlias) => {
|
|
66
|
+
let result;
|
|
67
|
+
try {
|
|
68
|
+
const service = context.service(alias);
|
|
69
|
+
await service.ready();
|
|
70
|
+
const pool = await service.client(configAlias);
|
|
71
|
+
await pool.query('SELECT 1');
|
|
72
|
+
result = { ok: true, summary: 'DB OK — connected; structure reconciled at init' };
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
result = { ok: false, summary: 'DB check failed', error: formatDbError(error) };
|
|
76
|
+
}
|
|
77
|
+
lastHealth.set(keyOf(alias, configAlias), result);
|
|
78
|
+
return result;
|
|
79
|
+
};
|
|
80
|
+
//# sourceMappingURL=health.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"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"}
|
package/build/index.d.ts
CHANGED
package/build/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}
|
package/build/index.js
CHANGED
package/build/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAKnD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,
|
|
1
|
+
{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAKnD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,WAAW,MAAM,KAAmB,UAW9D,CAAA"}
|
package/build/middleware.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGnE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,
|
|
1
|
+
{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGnE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,GAAW,aAAa,EAAc,EAAE,CAAC,CAAC;IAC7E,IAAI,EAAE,cAAc,CAAC,OAAO;IAC5B,KAAK,EAAE,eAAe,CAAC,OAAO;IAE9B,KAAK,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;QACrB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAM;QACR,CAAC;QAED,MAAM,OAAO,CAAC,OAAO,CAAkB,KAAK,CAAC,CAAC,KAAK,EAAE,CAAA;IACvD,CAAC;CACF,CAAC,CAAA"}
|
package/build/service.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAS3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAIjD,KAAK,MAAM,GAAG,YAAY,CAAA;AAC1B,UAAU,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI;AAEzE,eAAO,MAAM,qBAAqB,
|
|
1
|
+
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAS3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAIjD,KAAK,MAAM,GAAG,YAAY,CAAA;AAC1B,UAAU,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI;AAEzE,eAAO,MAAM,qBAAqB,WAAW,MAAM,KAAmB,eA2NrE,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,WACvE,CAAC,UAAS,MAAM,KACxB,CAOF,CAAA"}
|
package/build/service.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EACL,MAAM,EAAE,sBAAsB,EAAE,YAAY,EAAE,KAAK,EAAE,mBAAmB,EACzE,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEpD,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAK3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,
|
|
1
|
+
{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAA;AAIpC;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAA;AAIpC;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,QAAS,MAAM,KAAG,UAsCtC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,WAAY,QAAQ,cAAc,UAAU,KAAG,UAuCxE,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,YAAY,SAAU;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,KAAG,MACV,CAAA"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAkB9B;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,
|
|
1
|
+
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAkB9B;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,SAAgB,IAAI,QAAQ,YAAY,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAyB1F,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,YAAY,SAAgB,IAAI,UAAU,MAAM,KAAG,OAAO,CAAC,IAAI,CAM3E,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/postgres",
|
|
3
|
-
"version": "0.1.18-rc.
|
|
3
|
+
"version": "0.1.18-rc.14",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -22,17 +22,17 @@
|
|
|
22
22
|
}
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@owlmeans/basic-keys": "^0.1.18-rc.
|
|
26
|
-
"@owlmeans/context": "^0.1.18-rc.
|
|
27
|
-
"@owlmeans/postgres-resource": "^0.1.18-rc.
|
|
28
|
-
"@owlmeans/resource": "^0.1.18-rc.
|
|
29
|
-
"@owlmeans/server-context": "^0.1.18-rc.
|
|
25
|
+
"@owlmeans/basic-keys": "^0.1.18-rc.12",
|
|
26
|
+
"@owlmeans/context": "^0.1.18-rc.8",
|
|
27
|
+
"@owlmeans/postgres-resource": "^0.1.18-rc.13",
|
|
28
|
+
"@owlmeans/resource": "^0.1.18-rc.9",
|
|
29
|
+
"@owlmeans/server-context": "^0.1.18-rc.12",
|
|
30
30
|
"drizzle-orm": "~0.45.2",
|
|
31
31
|
"pg": "^8.22.0"
|
|
32
32
|
},
|
|
33
33
|
"devDependencies": {
|
|
34
34
|
"@owlmeans/dep-config": "workspace:*",
|
|
35
|
-
"@owlmeans/test-integration": "^0.1.18-rc.
|
|
35
|
+
"@owlmeans/test-integration": "^0.1.18-rc.8",
|
|
36
36
|
"@types/bun": "^1.4.0",
|
|
37
37
|
"@types/node": "^26.1.0",
|
|
38
38
|
"@types/pg": "^8.20.4",
|
package/src/health.ts
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import type { BasicConfig, BasicContext } from '@owlmeans/context'
|
|
2
|
+
|
|
3
|
+
import { DEFAULT_ALIAS } from './consts.js'
|
|
4
|
+
import type { PostgresService } from './types.js'
|
|
5
|
+
|
|
6
|
+
export interface DbHealth {
|
|
7
|
+
ok: boolean
|
|
8
|
+
/** One line fit for a boot log — states what was checked, not only whether it passed. */
|
|
9
|
+
summary: string
|
|
10
|
+
error?: string
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const lastHealth: Map<string, DbHealth> = new Map()
|
|
14
|
+
|
|
15
|
+
const keyOf = (alias: string, configAlias?: string): string => `${alias}:${configAlias ?? ''}`
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The outcome of the last {@link checkDbHealth} for the same pair of aliases.
|
|
19
|
+
*
|
|
20
|
+
* A request time handler wants the verdict of the boot check without paying for it again: the
|
|
21
|
+
* structure was reconciled once, at init, and re-asserting it per request buys nothing.
|
|
22
|
+
*/
|
|
23
|
+
export const getLastDbHealth = (
|
|
24
|
+
alias: string = DEFAULT_ALIAS, configAlias?: string
|
|
25
|
+
): DbHealth | undefined => lastHealth.get(keyOf(alias, configAlias))
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Surface the Postgres fields (code/severity/detail/hint) an error carries — a bare `.message`
|
|
29
|
+
* hides the real FATAL/permission reason, and the cause chain is where the driver's error ends up
|
|
30
|
+
* once a resource wraps it.
|
|
31
|
+
*/
|
|
32
|
+
export const formatDbError = (error: unknown): string => {
|
|
33
|
+
const parts: string[] = []
|
|
34
|
+
const seen = new Set<unknown>()
|
|
35
|
+
let current = error as (Record<string, any> | null | undefined)
|
|
36
|
+
while (current != null && !seen.has(current)) {
|
|
37
|
+
seen.add(current)
|
|
38
|
+
const meta: string[] = []
|
|
39
|
+
if (current.severity != null) meta.push(`severity=${current.severity}`)
|
|
40
|
+
if (current.code != null) meta.push(`code=${current.code}`)
|
|
41
|
+
if (current.detail != null) meta.push(`detail=${current.detail}`)
|
|
42
|
+
if (current.hint != null) meta.push(`hint=${current.hint}`)
|
|
43
|
+
const message = current.message ?? String(current)
|
|
44
|
+
parts.push(meta.length > 0 ? `${message} (${meta.join(', ')})` : message)
|
|
45
|
+
current = current.cause
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const joined = parts.join('; caused by: ')
|
|
49
|
+
|
|
50
|
+
return joined !== '' ? joined : String(error)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Liveness only, through the context's own pool — no private client, no connection string, no
|
|
55
|
+
* migration journal. The service is looked up by alias exactly as any other consumer looks it up,
|
|
56
|
+
* so a health probe cannot end up connected differently from the app it reports on.
|
|
57
|
+
*
|
|
58
|
+
* The context arrives as an argument rather than as a module import: a handler is given the
|
|
59
|
+
* context that actually served the request (possibly an entity scoped derivative), and taking it
|
|
60
|
+
* as a parameter keeps this module out of the boot import cycle.
|
|
61
|
+
*/
|
|
62
|
+
export const pingDb = async (
|
|
63
|
+
context: BasicContext<BasicConfig>, alias: string = DEFAULT_ALIAS, configAlias?: string
|
|
64
|
+
): Promise<DbHealth> => {
|
|
65
|
+
try {
|
|
66
|
+
const pool = await context.service<PostgresService>(alias).client(configAlias)
|
|
67
|
+
await pool.query('SELECT 1')
|
|
68
|
+
|
|
69
|
+
return { ok: true, summary: 'DB reachable' }
|
|
70
|
+
} catch (error) {
|
|
71
|
+
return { ok: false, summary: 'DB unreachable', error: formatDbError(error) }
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The boot gate check: wait for the service to be ready, then assert the connection still works.
|
|
77
|
+
*
|
|
78
|
+
* Structure is reconciled by the resources during the context's `init()`; if that succeeded the
|
|
79
|
+
* tables are correct by construction, and if it failed the process never got here. There is
|
|
80
|
+
* nothing left to assert beyond "the connection works", which is why this is a `SELECT 1` and not
|
|
81
|
+
* a schema walk. The result is cached for {@link getLastDbHealth}.
|
|
82
|
+
*/
|
|
83
|
+
export const checkDbHealth = async (
|
|
84
|
+
context: BasicContext<BasicConfig>, alias: string = DEFAULT_ALIAS, configAlias?: string
|
|
85
|
+
): Promise<DbHealth> => {
|
|
86
|
+
let result: DbHealth
|
|
87
|
+
try {
|
|
88
|
+
const service = context.service<PostgresService>(alias)
|
|
89
|
+
await service.ready()
|
|
90
|
+
const pool = await service.client(configAlias)
|
|
91
|
+
await pool.query('SELECT 1')
|
|
92
|
+
result = { ok: true, summary: 'DB OK — connected; structure reconciled at init' }
|
|
93
|
+
} catch (error) {
|
|
94
|
+
result = { ok: false, summary: 'DB check failed', error: formatDbError(error) }
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
lastHealth.set(keyOf(alias, configAlias), result)
|
|
98
|
+
|
|
99
|
+
return result
|
|
100
|
+
}
|