@owlmeans/postgres 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OwlMeans Common — Fullstack typescript framework
+
+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,139 @@
+# @owlmeans/postgres
+
+PostgreSQL service for OwlMeans server contexts — pooled connections, readiness probing, schema
+provisioning, and an opt-in least-privilege bootstrap path.
+
+## Overview
+
+- `makePostgresDbService(alias?)` — creates a PostgreSQL connection service
+- `appendPostgres(context, alias?)` — registers the service **and** its drain middleware in the context
+- Reads connection config from `context.cfg.dbs` entries whose `service` is `'postgres'`
+- Backs `@owlmeans/postgres-resource`; the resource layer owns all DDL
+- `bootstrap()` provisions a role, database and schema from a separate superuser config alias
+
+## Installation
+
+```bash
+bun add @owlmeans/postgres @owlmeans/postgres-resource
+```
+
+## Usage
+
+```typescript
+import { appendPostgres, DEFAULT_ALIAS as POSTGRES_SERVICE } from '@owlmeans/postgres'
+
+// In context setup (backend/src/context.ts)
+appendPostgres<C, T>(context)
+```
+
+Config:
+
+```typescript
+cfg.dbs = [{
+  service: 'postgres',
+  alias: 'postgres',
+  host: '/etc/app-config/pg-host',            // values starting with `/` are read as files
+  user: '/etc/app-config/pg-role-name',
+  secret: '/etc/master-secret/pg-app-password',
+  schema: 'app',                               // ← Postgres SCHEMA
+  meta: { database: '/etc/app-config/pg-db-name' }
+}]
+```
+
+A whole connection string works too, and wins over `host`/`user`/`secret`:
+
+```typescript
+cfg.dbs = [{ service: 'postgres', alias: 'postgres', schema: 'app', meta: { url: process.env.DATABASE_URL } }]
+```
+
+`schema` is the Postgres **schema**, not the database — `dbName()` suffixes it per Entity/User layer,
+so per-tenant namespaces stay cheap. The database comes from `meta.database` and is never suffixed.
+
+At `init()` the service opens a pool, runs a `SELECT 1` readiness probe (30 attempts, 2s apart by
+default — a Postgres sidecar routinely accepts TCP before it accepts queries), issues
+`CREATE SCHEMA IF NOT EXISTS`, and installs a `SIGTERM` handler that drains the pool.
+
+### Bootstrap (admin path)
+
+Hold the superuser connection under a **separate** config alias so the application's own entry never
+carries superuser credentials:
+
+```typescript
+cfg.dbs = [
+  { service: 'postgres', alias: 'postgres',  /* least privileged app role */ },
+  { service: 'postgres', alias: 'pg-admin', /* superuser */ }
+]
+
+const postgres = context.service<PostgresService>('postgres')
+await postgres.bootstrap('pg-admin', {
+  role: 'app_role', password: appPassword, database: 'app_db', schema: 'app', leastPrivilege: true
+})
+```
+
+Idempotent by design — it probes `pg_roles` and `pg_database` before creating anything, rotates the
+password of a role that already exists, and applies `REVOKE CONNECT … FROM PUBLIC`,
+`REVOKE CREATE ON SCHEMA public FROM PUBLIC`, `GRANT CONNECT … TO <role>` and
+`ALTER ROLE … SET search_path`. Returns a `BootstrapReport` saying what it actually changed.
+Identifiers are validated and quoted; the password is the only literal and is escaped.
+
+## API
+
+### `makePostgresDbService(alias?): PostgresService`
+
+Creates the PostgreSQL service. `alias` defaults to `DEFAULT_ALIAS` (`'postgres'`).
+
+### `appendPostgres<C, T>(context, alias?): T`
+
+Registers the service and the drain middleware in the context.
+
+### `PostgresService`
+
+Extends `PostgresDbService` from `@owlmeans/postgres-resource`:
+
+- `db(alias?): Promise<PostgresDb>` — `{ drizzle, pool, schema, database }`
+- `client(alias?): Promise<Pool>` / `clients: Record<string, Pool>`
+- `qualify(resourceAlias, configAlias?): string` — `"schema"."table"` of a registered resource
+- `query(text, params?, configAlias?)` — parameterised query straight on the pool
+- `transaction(fn, configAlias?)` — a `PostgresTx`
+- `defer(configAlias, task)` / `drain(configAlias?)` — work held back until every resource has
+  initialized (foreign keys whose target table belongs to a resource that hasn't run `init()` yet)
+- `lock` / `unlock` — AES field encryption via `config.encryptionKey`
+- `bootstrap(configAlias, opts): Promise<BootstrapReport>`
+
+### Helpers
+
+- `parseUrl(url)` / `prepareConfig(config, overrides?)` / `poolDatabase(pool)`
+- `probe(pool, meta, location)` / `ensureSchema(pool, schema)`
+- `bootstrapDb(...)` — the bootstrap implementation, usable without a context
+- `drainMiddleware(alias?)`
+
+### Constants
+
+- `DEFAULT_ALIAS` — `'postgres'`
+- `DEF_ADMIN_ALIAS` — `'pg-admin'`
+- `DEF_MAINTENANCE_DB` — `'postgres'`; `DEF_PORT` — `5432`; `DEF_POOL_SIZE` — `10`
+- `DEF_RETRIES` — `30`; `DEF_RETRY_DELAY` — `2000`
+- `TERMINAL_CONNECT_CODES` — auth/database/permission failures the probe treats as final
+
+## Related Packages
+
+- [`@owlmeans/postgres-resource`](../postgres-resource) — `makePostgresResource` uses this service
+- [`@owlmeans/server-app`](../server-app) — `makeContext` in conjunction with `appendPostgres`
+- [`@owlmeans/mongo`](../mongo) — the MongoDB counterpart
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/postgres.instructions.md

@@ -0,0 +1,57 @@
+---
+description: "How to use @owlmeans/postgres — PostgreSQL connection service (makePostgresDbService / appendPostgres) registered on a server context, plus the least-privilege bootstrap admin path."
+applyTo: "**/context.ts, **/config.ts, **/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/postgres
+
+**Layer:** Infra
+**Install:** `"@owlmeans/postgres": "^0.1.15"` in `dependencies`
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makePostgresDbService(alias?)` | PostgreSQL connection service factory |
+| `appendPostgres(context, alias?)` | Registers the service **and** its drain middleware |
+| `PostgresService`, `BootstrapOptions`, `BootstrapReport` | Service contract and the admin path |
+| `bootstrapDb`, `drainMiddleware`, `parseUrl`, `prepareConfig`, `probe`, `ensureSchema` | Helpers |
+| `DEFAULT_ALIAS` (`'postgres'`), `DEF_ADMIN_ALIAS` (`'pg-admin'`), `DEF_POOL_SIZE`, `DEF_RETRIES` | Constants |
+
+## Usage
+
+```typescript
+import { appendPostgres } from '@owlmeans/postgres'
+appendPostgres<C, T>(context)
+
+cfg.dbs = [{
+  service: 'postgres', alias: 'postgres',
+  host: '/etc/app-config/pg-host', user: '/etc/app-config/pg-role-name',
+  secret: '/etc/master-secret/pg-app-password',
+  schema: 'app', meta: { database: '/etc/app-config/pg-db-name' }
+}]
+```
+
+## Rules
+
+- Use `appendPostgres`, not a bare `registerService` — the drain middleware is half the wiring.
+- `DbConfig.schema` is the Postgres **SCHEMA** (layer-suffixed by `dbName()`); the **DATABASE** is
+  `meta.database` and is never suffixed. `meta.url` accepts a whole connection string and wins over
+  `host`/`user`/`secret`. A value starting with `/` is read as a file.
+- `init()` already probes readiness (`SELECT 1`, 30×2s) and creates the schema — do not hand-roll a
+  retry loop. Auth / missing-database / permission codes fail fast instead of retrying.
+- Keep the pool small; `max_connections` is a cluster-wide cap, so an oversized pool starves other
+  clients. Default `DEF_POOL_SIZE` is 10.
+- All application-table DDL belongs to `@owlmeans/postgres-resource`. This service only creates the
+  schema.
+- Superuser credentials go under a **separate** config alias (`pg-admin`), never the app's own entry.
+- `bootstrap()` is idempotent and replaces hand-written `CREATE ROLE` / `CREATE DATABASE` / `GRANT`
+  SQL. If such SQL exists in a deployment script or doc, collapse it into a `bootstrap()` call.
+- Use `defer()` for work that depends on another resource being initialized (foreign keys); it is
+  drained by the middleware once the context is up.
+
+## Depends On
+
+- `@owlmeans/postgres-resource`, `@owlmeans/resource`, `@owlmeans/context`,
+  `@owlmeans/server-context`, `@owlmeans/basic-keys`, `pg`, `drizzle-orm`

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/postgres",
+  "version": "0.1.15",
+  "generatedAt": "2026-08-07T18:11:56.992Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "postgres",
+      "category": "package-specific",
+      "file": "skills/postgres/SKILL.md",
+      "canonicalPath": ".claude/skills/postgres/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "postgres",
+      "category": "package-specific",
+      "file": "instructions/postgres.instructions.md",
+      "canonicalPath": ".github/instructions/postgres.instructions.md"
+    }
+  ]
+}

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

@@ -0,0 +1,121 @@
+---
+name: postgres
+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.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/postgres
+
+**Layer:** Infra
+**Install:** `"@owlmeans/postgres": "^0.1.15"` 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]] —
+this package only creates the schema those tables live in.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makePostgresDbService(alias?)` | The connection service. `alias` defaults to `DEFAULT_ALIAS` (`'postgres'`). |
+| `appendPostgres(context, alias?)` | Registers the service **and** its drain middleware. Use this, not a bare `registerService`. |
+| `PostgresService` | `PostgresDbService` + `bootstrap(configAlias, opts)`. |
+| `BootstrapOptions`, `BootstrapReport`, `bootstrapDb` | The admin path; `bootstrapDb` is usable without a context. |
+| `drainMiddleware(alias?)` | Drains work deferred until every resource has initialized. |
+| `parseUrl`, `prepareConfig`, `poolDatabase`, `probe`, `ensureSchema` | Config and connection helpers. |
+| `DEFAULT_ALIAS`, `DEF_ADMIN_ALIAS`, `DEF_MAINTENANCE_DB`, `DEF_PORT`, `DEF_POOL_SIZE`, `DEF_RETRIES`, `DEF_RETRY_DELAY`, `TERMINAL_CONNECT_CODES` | Constants. |
+
+## Wiring
+
+```typescript
+import { appendPostgres } from '@owlmeans/postgres'
+
+appendPostgres<C, T>(context)
+```
+
+```typescript
+cfg.dbs = [{
+  service: 'postgres',
+  alias: 'postgres',
+  host: '/etc/app-config/pg-host',          // a leading `/` means "read this file"
+  user: '/etc/app-config/pg-role-name',
+  secret: '/etc/master-secret/pg-app-password',
+  schema: 'app',                             // ← Postgres SCHEMA
+  meta: { database: '/etc/app-config/pg-db-name' }
+}]
+```
+
+`meta.url` takes a whole connection string and wins over `host`/`user`/`secret` — that is the shape
+for a `DATABASE_URL` env var. Because a leading `/` is auto-read, moving to file-mounted secrets
+later is a config change, not a code change.
+
+**`schema` is the SCHEMA, not the database.** `dbName()` suffixes it per Entity/User layer, so
+per-tenant namespaces cost a `CREATE SCHEMA` rather than a `CREATE DATABASE`. The database comes
+from `meta.database` and is never suffixed.
+
+Other `meta` keys: `autoSync` (see [[postgres-resource]]), `ssl`, `max`, `idleTimeoutMillis`,
+`connectionTimeoutMillis`, `statementTimeoutMillis`, `retries`, `retryDelayMillis`.
+
+## What `init()` does
+
+Opens a `pg.Pool` → `SELECT 1` readiness probe (30 attempts, 2s apart) → `CREATE SCHEMA IF NOT
+EXISTS` → `SIGTERM` handler that drains the pool. Do **not** hand-roll the retry loop around it: a
+Postgres sidecar routinely accepts TCP before it accepts queries, which is precisely what the probe
+is for. Credential, missing-database and permission failures (`TERMINAL_CONNECT_CODES`) fail
+immediately instead of burning the full retry budget on an error that will never clear.
+
+Keep the pool small. Postgres caps connections cluster-wide (`max_connections`, 100 by default), so
+an oversized per-process pool starves every other client of the same server — the opposite of the
+Mongo driver's tuning instinct.
+
+## Service surface
+
+`db(alias?)` → `{ drizzle, pool, schema, database }` · `client(alias?)` / `clients` ·
+`qualify(resourceAlias, configAlias?)` · `query(text, params?, configAlias?)` ·
+`transaction(fn, configAlias?)` · `lock`/`unlock` (AES via `config.encryptionKey`) ·
+`defer(configAlias, task)` / `drain(configAlias?)`.
+
+`defer` exists for work that can't run during one resource's `init()` because it points at another
+resource that hasn't initialized yet — foreign keys, above all. Queue it; the middleware
+`appendPostgres` registers drains it once the context is up. Do not reorder resource registrations
+to work around this.
+
+## Bootstrap — the admin path
+
+Superuser credentials belong to a **separate config alias**. The application's own entry connects as
+the least-privileged role and must never carry them.
+
+```typescript
+await context.service<PostgresService>('postgres').bootstrap('pg-admin', {
+  role: 'app_role', password: appPassword, database: 'app_db', schema: 'app', leastPrivilege: true
+})
+```
+
+Idempotent by design — every OwlMeans deployment calls it on each start and each rebuild. It probes
+`pg_roles` / `pg_database` before creating, rotates the password of an existing role (the caller
+generated the password it just passed in, so the role has to accept it), and with `leastPrivilege`
+applies `REVOKE CONNECT … FROM PUBLIC`, `REVOKE CREATE ON SCHEMA public FROM PUBLIC`,
+`GRANT CONNECT … TO <role>`, `ALTER ROLE … SET search_path`. The returned `BootstrapReport` says
+what actually changed. Identifiers are validated and quoted; the password is the only literal.
+
+**This replaces hand-written bootstrap SQL.** If you find `CREATE ROLE` / `CREATE DATABASE` /
+`GRANT` strings in a deployment script, a provisioner, or a `DEPLOYMENT.md`, they are a duplicate of
+this function — collapse them into a `bootstrap()` call rather than keeping both in step.
+
+## Tests
+
+`bun test ./tests` in the package. Integration specs that build a real `ServerContext` live **here**,
+not in `postgres-resource` — see [[testing-integration]]. Gated on `POSTGRES_URL`; the bootstrap
+specs additionally probe for `CREATEROLE`/`CREATEDB` and self-skip without them.
+
+## Depends On
+
+- `@owlmeans/postgres-resource` · `@owlmeans/resource` · `@owlmeans/context` ·
+  `@owlmeans/server-context` · `@owlmeans/basic-keys`
+- `pg` · `drizzle-orm`
+
+## Related
+
+- [[postgres-resource]] — the `Resource<T>` implementation this service backs
+- [[mongo]] — the MongoDB counterpart · [[kluster]] — `kluster:` directives in `cfg.dbs`

package/build/bootstrap.d.ts

@@ -0,0 +1,16 @@
+import type { BootstrapOptions, BootstrapReport, PostgresService } from './types.js';
+/**
+ * Provision a least privileged role, its database and its schema.
+ *
+ * This is the one copy of a script every OwlMeans deployment used to carry inline. It runs
+ * on every start and every rebuild, so each step probes before it acts — "already exists"
+ * is the expected outcome, not an error.
+ *
+ * Two connections are unavoidable. `CREATE DATABASE` cannot run from inside the database
+ * it creates, so roles and databases are made over the maintenance connection the admin
+ * config points at, and the grants are applied over a short lived connection to the target.
+ *
+ * @throws {PostgresBootstrapError}
+ */
+export declare const bootstrapDb: (service: PostgresService, configAlias: string, opts: BootstrapOptions) => Promise<BootstrapReport>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/build/bootstrap.d.ts.map

@@ -0,0 +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,GACtB,SAAS,eAAe,EAAE,aAAa,MAAM,EAAE,MAAM,gBAAgB,KACpE,OAAO,CAAC,eAAe,CAwFzB,CAAA"}

package/build/bootstrap.js

@@ -0,0 +1,106 @@
+import { assertSqlIdentifier, PostgresBootstrapError, quoteIdent, quoteLiteral } from '@owlmeans/postgres-resource';
+import { Pool } from 'pg';
+import { prepareConfig } from './utils/config.js';
+const exists = async (client, text, value) => {
+    const result = await client.query(text, [value]);
+    return result.rowCount != null && result.rowCount > 0;
+};
+/**
+ * Provision a least privileged role, its database and its schema.
+ *
+ * This is the one copy of a script every OwlMeans deployment used to carry inline. It runs
+ * on every start and every rebuild, so each step probes before it acts — "already exists"
+ * is the expected outcome, not an error.
+ *
+ * Two connections are unavoidable. `CREATE DATABASE` cannot run from inside the database
+ * it creates, so roles and databases are made over the maintenance connection the admin
+ * config points at, and the grants are applied over a short lived connection to the target.
+ *
+ * @throws {PostgresBootstrapError}
+ */
+export const bootstrapDb = async (service, configAlias, opts) => {
+    const role = assertSqlIdentifier(opts.role, 'role');
+    const database = assertSqlIdentifier(opts.database ?? opts.role, 'database');
+    const schema = opts.schema != null ? assertSqlIdentifier(opts.schema, 'schema') : null;
+    const leastPrivilege = opts.leastPrivilege ?? true;
+    const rotate = opts.rotatePassword ?? true;
+    if (opts.password === '') {
+        throw new PostgresBootstrapError(`empty-password:${role}`);
+    }
+    const report = {
+        roleCreated: false,
+        passwordRotated: false,
+        databaseCreated: false,
+        schemaCreated: false,
+        grantsApplied: false
+    };
+    const config = service.config(configAlias);
+    const admin = await service.client(configAlias);
+    /**
+     * The password is the only value here that can't be bound: `CREATE ROLE` takes no
+     * parameters, so it reaches the server inside the statement text. Identifiers have
+     * already been asserted safe; the literal is escaped.
+     */
+    const secret = quoteLiteral(opts.password);
+    const client = await admin.connect();
+    try {
+        if (await exists(client, 'SELECT 1 FROM pg_roles WHERE rolname = $1', role)) {
+            if (rotate) {
+                await client.query(`ALTER ROLE ${quoteIdent(role)} WITH LOGIN PASSWORD ${secret}`);
+                report.passwordRotated = true;
+            }
+        }
+        else {
+            await client.query(`CREATE ROLE ${quoteIdent(role)} WITH LOGIN PASSWORD ${secret}`);
+            report.roleCreated = true;
+        }
+        if (!await exists(client, 'SELECT 1 FROM pg_database WHERE datname = $1', database)) {
+            /** Never inside a transaction — Postgres refuses `CREATE DATABASE` in one. */
+            await client.query(`CREATE DATABASE ${quoteIdent(database)} OWNER ${quoteIdent(role)}`);
+            report.databaseCreated = true;
+        }
+    }
+    catch (error) {
+        throw wrap(error, `${role}@${database}`);
+    }
+    finally {
+        client.release();
+    }
+    const target = new Pool(prepareConfig(config, { database, max: 1 }));
+    try {
+        if (schema != null) {
+            /**
+             * The resource layer creates its own schema too, but only once an application with
+             * resources boots. Creating it here — owned by the role — is what lets that
+             * application connect as a role with no `CREATE` right on the database at all.
+             */
+            await target.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)} AUTHORIZATION ${quoteIdent(role)}`);
+            await target.query(`GRANT ALL ON SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(role)}`);
+            await target.query(`ALTER ROLE ${quoteIdent(role)} SET search_path = ${quoteIdent(schema)}`);
+            report.schemaCreated = true;
+        }
+        if (leastPrivilege) {
+            await target.query(`REVOKE CONNECT ON DATABASE ${quoteIdent(database)} FROM PUBLIC`);
+            await target.query('REVOKE CREATE ON SCHEMA public FROM PUBLIC');
+            await target.query(`GRANT CONNECT ON DATABASE ${quoteIdent(database)} TO ${quoteIdent(role)}`);
+            report.grantsApplied = true;
+        }
+    }
+    catch (error) {
+        throw wrap(error, `${role}@${database}`);
+    }
+    finally {
+        await target.end().catch(() => undefined);
+    }
+    console.log(`@owlmeans/postgres: bootstrap ${role}@${database} —`
+        + ` role ${report.roleCreated ? 'created' : report.passwordRotated ? 'rotated' : 'present'},`
+        + ` database ${report.databaseCreated ? 'created' : 'present'}`
+        + (schema != null ? `, schema ${schema} ready` : ''));
+    return report;
+};
+const wrap = (error, subject) => {
+    const failure = new PostgresBootstrapError(`${subject}:${error?.message ?? error}`);
+    failure.cause = error;
+    return failure;
+};
+//# sourceMappingURL=bootstrap.js.map

package/build/bootstrap.js.map

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

package/build/consts.d.ts

@@ -0,0 +1,29 @@
+export declare const DEFAULT_ALIAS = "postgres";
+/**
+ * Config alias conventionally holding the superuser connection the admin path needs.
+ * Never the same as {@link DEFAULT_ALIAS} — the application connects as a least
+ * privileged role and must not carry superuser credentials in the same config entry.
+ */
+export declare const DEF_ADMIN_ALIAS = "pg-admin";
+/** The database `CREATE DATABASE` has to be issued from, since it can't create the one it's in. */
+export declare const DEF_MAINTENANCE_DB = "postgres";
+export declare const DEF_PORT = 5432;
+/**
+ * `SELECT 1` readiness probe, generalized from the boot loop every OwlMeans deployment
+ * hand-rolled: a Postgres sidecar routinely accepts TCP before it accepts queries.
+ */
+export declare const DEF_RETRIES = 30;
+export declare const DEF_RETRY_DELAY = 2000;
+/**
+ * Postgres caps connections cluster wide (`max_connections`, 100 by default), so the
+ * per-process pool stays deliberately small — unlike a Mongo driver pool, an oversized
+ * one here starves every other client of the same server.
+ */
+export declare const DEF_POOL_SIZE = 10;
+/**
+ * Failures the readiness probe treats as final rather than as "not up yet":
+ * `28P01`/`28000` wrong credentials, `3D000` no such database, `42501` no rights.
+ * Retrying any of them just delays the same error by a minute.
+ */
+export declare const TERMINAL_CONNECT_CODES: string[];
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,aAAmB,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,eAAe,aAAa,CAAA;AAEzC,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,eAAO,MAAM,QAAQ,OAAO,CAAA;AAE5B;;;GAGG;AACH,eAAO,MAAM,WAAW,KAAK,CAAA;AAC7B,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,UAAuC,CAAA"}

package/build/consts.js

@@ -0,0 +1,30 @@
+import { DEFAULT_DB_ALIAS } from '@owlmeans/postgres-resource';
+export const DEFAULT_ALIAS = DEFAULT_DB_ALIAS;
+/**
+ * Config alias conventionally holding the superuser connection the admin path needs.
+ * Never the same as {@link DEFAULT_ALIAS} — the application connects as a least
+ * privileged role and must not carry superuser credentials in the same config entry.
+ */
+export const DEF_ADMIN_ALIAS = 'pg-admin';
+/** The database `CREATE DATABASE` has to be issued from, since it can't create the one it's in. */
+export const DEF_MAINTENANCE_DB = 'postgres';
+export const DEF_PORT = 5432;
+/**
+ * `SELECT 1` readiness probe, generalized from the boot loop every OwlMeans deployment
+ * hand-rolled: a Postgres sidecar routinely accepts TCP before it accepts queries.
+ */
+export const DEF_RETRIES = 30;
+export const DEF_RETRY_DELAY = 2000;
+/**
+ * Postgres caps connections cluster wide (`max_connections`, 100 by default), so the
+ * per-process pool stays deliberately small — unlike a Mongo driver pool, an oversized
+ * one here starves every other client of the same server.
+ */
+export const DEF_POOL_SIZE = 10;
+/**
+ * Failures the readiness probe treats as final rather than as "not up yet":
+ * `28P01`/`28000` wrong credentials, `3D000` no such database, `42501` no rights.
+ * Retrying any of them just delays the same error by a minute.
+ */
+export const TERMINAL_CONNECT_CODES = ['28P01', '28000', '3D000', '42501'];
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAE9D,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAA;AAEzC,mGAAmG;AACnG,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAA;AAE5C,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAA;AAE5B;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAA;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAA;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAA;AAE/B;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './bootstrap.js';
+export * from './middleware.js';
+export * from './service.js';
+export * from './utils/config.js';
+export * from './utils/connection.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +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"}

package/build/index.js

@@ -0,0 +1,7 @@
+export * from './consts.js';
+export * from './bootstrap.js';
+export * from './middleware.js';
+export * from './service.js';
+export * from './utils/config.js';
+export * from './utils/connection.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +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"}

package/build/middleware.d.ts

@@ -0,0 +1,11 @@
+import type { Middleware } from '@owlmeans/context';
+/**
+ * Run the work resources held back until every one of them had initialized.
+ *
+ * Foreign keys are the reason this exists: a key points at a table another resource owns,
+ * and resource initialization order is registration order, not dependency order. The
+ * Loading stage of the Context middleware type runs immediately after the last resource's
+ * `init()` — the first moment at which every table is known to exist.
+ */
+export declare const drainMiddleware: (alias?: string) => Middleware;
+//# sourceMappingURL=middleware.d.ts.map

package/build/middleware.d.ts.map

@@ -0,0 +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,GAAI,QAAO,MAAsB,KAAG,UAW9D,CAAA"}

package/build/middleware.js

@@ -0,0 +1,21 @@
+import { MiddlewareStage, MiddlewareType } from '@owlmeans/context';
+import { DEFAULT_ALIAS } from './consts.js';
+/**
+ * Run the work resources held back until every one of them had initialized.
+ *
+ * Foreign keys are the reason this exists: a key points at a table another resource owns,
+ * and resource initialization order is registration order, not dependency order. The
+ * Loading stage of the Context middleware type runs immediately after the last resource's
+ * `init()` — the first moment at which every table is known to exist.
+ */
+export const drainMiddleware = (alias = DEFAULT_ALIAS) => ({
+    type: MiddlewareType.Context,
+    stage: MiddlewareStage.Loading,
+    apply: async (context) => {
+        if (!context.hasService(alias)) {
+            return;
+        }
+        await context.service(alias).drain();
+    }
+});
+//# sourceMappingURL=middleware.js.map

package/build/middleware.js.map

@@ -0,0 +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,QAAgB,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

@@ -0,0 +1,9 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+import type { PostgresService } from './types.js';
+type Config = ServerConfig;
+interface Context<C extends Config = Config> extends ServerContext<C> {
+}
+export declare const makePostgresDbService: (alias?: string) => PostgresService;
+export declare const appendPostgres: <C extends Config, T extends Context<C> = Context<C>>(context: T, alias?: string) => T;
+export {};
+//# sourceMappingURL=service.d.ts.map