@owlmeans/postgres-resource 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,219 @@
+# @owlmeans/postgres-resource
+
+PostgreSQL-backed `Resource<T>` implementation — schema-driven tables, structure reconciliation,
+code-registered migrations, and custom SQL with resource-alias placeholders.
+
+## Overview
+
+- `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?)` — factory for Postgres resources
+- `PostgresResource<T>` — extends `Resource<T>` with a Drizzle table, custom SQL, transactions, and field encryption
+- The resource's **AJV schema is the single source of truth for the table structure** — columns, types,
+  nullability, defaults, primary key and indexes are all derived from it
+- A `pg:` keyword vocabulary inside that schema covers what JSON Schema can't express: column types and
+  lengths, foreign keys, composite indexes, checks, partial indexes
+- Tables are created and reconciled automatically at `init()`; migrations run around that in `pre`/`post` stages
+
+## Installation
+
+```bash
+bun add @owlmeans/postgres-resource @owlmeans/postgres pg
+```
+
+`pg` and `ajv` are peer dependencies of this package. `@owlmeans/postgres` provides the connection
+service this package resolves through.
+
+## Usage
+
+Define a resource:
+
+```typescript
+import { makePostgresResource } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type { ResourceMaker } from '@owlmeans/resource'
+
+export interface ProjectResource extends PostgresResource<ProjectRecord> {}
+
+export const makeProjectResource: ResourceMaker<ProjectRecord, ProjectResource> = (dbAlias, serviceAlias) => {
+  const resource = makePostgresResource<ProjectRecord, ProjectResource>(
+    RES_PROJECT, dbAlias, serviceAlias, makeProjectResource
+  )
+  resource.schema = ProjectSchema
+  resource.index('idx_project_entity', { columns: ['entityId'] })
+
+  return resource
+}
+```
+
+Register in context:
+
+```typescript
+context.registerResource(makeProjectResource())
+```
+
+Use in a handler:
+
+```typescript
+const projects = context.resource<ProjectResource>(RES_PROJECT)
+const record = await projects.create({ entityId, alias, title })
+const list = await projects.list({ criteria: { entityId } })
+```
+
+### Schema → table
+
+```typescript
+const ProjectSchema: JSONSchemaType<ProjectRecord> = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    email: { type: 'string', pg: { type: 'varchar', length: 320, unique: true } },
+    ownerId: { type: 'string', pg: { references: { resource: 'users', onDelete: 'cascade' } } },
+    payload: { type: 'object', nullable: true },          // → jsonb
+    createdAt: DateSchema                                  // → timestamptz
+  },
+  required: ['id', 'email'],
+  pg: {
+    table: 'app_projects',
+    indexes: [{ name: 'idx_owner_created', columns: ['ownerId', 'createdAt'] }]
+  }
+}
+```
+
+| JSON Schema | Postgres |
+|---|---|
+| `string` | `text` |
+| `string` + `format: 'uuid'` | `uuid` |
+| `DateSchema` (`{type:'object', format:'date-time'}`) | `timestamptz` |
+| `integer` / `number` / `boolean` | `integer` / `double precision` / `boolean` |
+| `array`, nested `object` | `jsonb` |
+| string `enum` | `text` + `CHECK` |
+| `nullable: true` | nullable column |
+| in `required[]` | `NOT NULL` |
+| `secure: true` | ciphertext column, `lock`/`unlock` aware |
+| `id` property | primary key, `gen_random_uuid()::text` default |
+
+AJV in strict mode rejects unknown keywords — register `pgKeyword` to allow `pg:`:
+
+```typescript
+ajv.addKeyword(pgKeyword)
+```
+
+### Structure reconciliation
+
+At `init()` the resource introspects `information_schema` / `pg_catalog`, diffs against the compiled
+spec, and applies the DDL plan in one transaction under a `pg_advisory_xact_lock`, so concurrent
+replicas never race. Policy comes from `DbConfig.meta.autoSync`:
+
+| `PgAutoSync` | Behaviour |
+|---|---|
+| `Full` (default) | add / retype / backfill / drop columns, reconcile indexes and constraints |
+| `Additive` | add only — never retypes, never drops. The adoption path for a pre-existing table |
+| `Off` | create the table if absent, otherwise leave it alone |
+
+A cast Postgres cannot perform raises `PostgresCastRequired` rather than truncating data. Columns
+listed in `pg.unmanaged` are outside reconciliation's authority entirely.
+
+### Migrations
+
+```typescript
+resource.migration('0001-backfill-slug', async tx => {
+  await tx.execute(`UPDATE {{}} SET slug = lower(title) WHERE slug IS NULL`)
+}, MigrationStage.Post)
+```
+
+Stages bracket the structure sync: `Pre` runs **before** the table is reshaped (so a migration can
+rescue data reconciliation would drop), `Post` **after** (so it can use the new columns). Applied
+once, in registration order, each in its own transaction, recorded in `_owlmeans_migrations`.
+Migrations declared on a table this package just created are **baselined**, not executed. An edited
+body raises `MigrationConflict`; a failing one raises `MigrationError` and aborts `init()`.
+
+### Custom SQL
+
+Placeholders resolve **identifiers only** — values stay in `params` and are bound as `$1..$n`:
+
+| Placeholder | Resolves to |
+|---|---|
+| `{{}}` / `{{self}}` | the owning resource's `"schema"."table"` |
+| `{{alias}}` | another registered Postgres resource's qualified table |
+| `{{alias.property}}` | that resource's qualified column |
+| `{{#alias}}` | the bare quoted table name (for `ON CONFLICT ON CONSTRAINT`) |
+| `{{$}}` | the owning resource's quoted schema |
+
+```typescript
+const rows = await projects.select(
+  `SELECT p.* FROM {{}} p JOIN {{users}} u ON u.id = {{self.ownerId}} WHERE u.active = $1`,
+  [true]
+)
+```
+
+An unknown alias or property raises `PostgresPlaceholderError` at parse time rather than being
+substituted blindly.
+
+## API
+
+### `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?): T`
+
+Creates a Postgres resource. `dbAlias` and `serviceAlias` default to `DEFAULT_DB_ALIAS`
+(`'postgres'`). `tableName` overrides the physical table name, which otherwise derives from the alias.
+
+### `PostgresResource<T>`
+
+Extends `Resource<T>` with:
+
+- `schema?: AnySchema` — the source of truth for the table structure
+- `table: TableSpec` / `entity: PgRuntimeTable` — the compiled spec and the runtime Drizzle table
+- `db(): Promise<PostgresDb>` / `client(): Promise<Pool>`
+- `index(name, spec): this` / `migration(name, apply, stage?): this` — chainable declarations
+- `query` / `queryOne` / `execute` — raw rows and affected counts
+- `select` / `selectOne` — rows marshalled back into `T`
+- `ref(alias?): string` — fully qualified identifier of this or another resource
+- `transaction(fn)` — a `PostgresTx` with the same placeholder-aware helpers
+- `insert` / `upsert` / `patch` / `purge` / `count` — beyond the base contract
+- `lock(record, fields?)` / `unlock(record, fields?)` — encrypt/decrypt `secure` fields
+- `getDefaults(): Partial<T>`
+
+### `Resource<T>` methods (all implemented)
+
+`get`, `load`, `create`, `update`, `save`, `delete`, `pick`, `list`
+
+`create` refuses a caller-supplied id (use `insert`); `update` replaces the whole record (use `patch`
+to merge); `pick` deletes the record it returns, atomically.
+
+### Errors
+
+`PostgresError` and its subclasses — `PostgresSyncError`, `PostgresCastRequired`,
+`PostgresConstraintError`, `PostgresForeignKeyError`, `PostgresCheckError`, `PostgresDeadlockError`,
+`PostgresPlaceholderError`, `PostgresConnectionError`, `PostgresBootstrapError`. Driver errors are
+translated by `pgErrorToResourceError`, which unwraps Drizzle's `DrizzleQueryError` to reach the
+`pg` error underneath and preserves the raw `code`/`detail`/`hint`/`severity`. Unique violations
+surface as `RecordExists` and not-null violations as `MisshapedRecord`.
+
+### Constants
+
+- `DEFAULT_DB_ALIAS` — `'postgres'`
+- `DEFAULT_PAGE_SIZE` — `10`
+- `DEF_MIGRATIONS_TABLE` — `'_owlmeans_migrations'`
+- `PG_KEYWORD` — `'pg'`; `PG_MAX_IDENTIFIER` — `63`
+- `PgAutoSync`, `PgIndexMethod`, `PgReferentialAction`, `PgErrorCode`
+
+## Related Packages
+
+- [`@owlmeans/resource`](../resource) — `Resource<T>`, `ResourceRecord`, migrations, error family
+- [`@owlmeans/postgres`](../postgres) — the connection service required by this package
+- [`@owlmeans/mongo-resource`](../mongo-resource) — 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-resource.instructions.md

@@ -0,0 +1,60 @@
+---
+description: "How to use @owlmeans/postgres-resource — PostgreSQL-backed Resource implementation. The AJV schema is the single source of truth for the table; structure reconciliation, code migrations, and {{alias}} custom SQL."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/postgres-resource
+
+**Layer:** Infra
+**Install:** `"@owlmeans/postgres-resource": "^0.1.15"` in `dependencies` (peers `pg`, `ajv`)
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?)` | Resource factory; aliases default to `'postgres'` |
+| `PostgresResource<T>`, `PostgresTx`, `PostgresDb`, `TableSpec` | Resource, transaction, db handle and compiled table types |
+| `pgKeyword` | `{ keyword: 'pg', valid: true }` — register when AJV runs in strict mode |
+| `pgErrorToResourceError`, `PostgresError` family | Driver-error translation |
+| `PgAutoSync`, `PgErrorCode`, `DEF_MIGRATIONS_TABLE`, `DEFAULT_DB_ALIAS` | Constants |
+
+## Usage
+
+```typescript
+const resource = makePostgresResource<ProjectRecord, ProjectResource>(RES_PROJECT, dbAlias, serviceAlias, maker)
+resource.schema = ProjectSchema
+resource.index('idx_project_entity', { columns: ['entityId'] })
+context.registerResource(resource)
+```
+
+## Rules
+
+- **The AJV schema is the table.** Never call `pgTable`/`pgSchema`, never call `drizzle()`, never run
+  `drizzle-kit`, never hand-write `CREATE TABLE`. Two owners of the same DDL means reconciliation
+  drops what the other owner added.
+- Express what JSON Schema can't through the `pg:` keyword — per property (`type`, `length`,
+  `unique`, `index`, `references`, `check`, `managed`, …) and at the root (`table`, `indexes`,
+  `unmanaged`, `autoSync`, …).
+- `DbConfig.meta.autoSync` defaults to `Full`, which **DROPs** undeclared columns. Adopt a
+  pre-existing table with `Additive` first, confirm an empty plan, then flip to `Full`. Use
+  `pg.unmanaged` for columns reconciliation must never touch.
+- Thread `nullable` at **every** recursion level of the type mapper — `date-time` and optional nested
+  objects are where the Mongo mapper broke twice.
+- Migration `Pre` runs before the structure sync (the only place to rescue data a drop would lose),
+  `Post` after. Migrations on a freshly created table are baselined, not executed. Keep bodies at
+  **module scope** — the checksum fingerprints the function's source text.
+- Custom SQL interpolates **identifiers only**: `{{}}`/`{{self}}`, `{{alias}}`, `{{alias.property}}`,
+  `{{#alias}}`, `{{$}}`. Values stay in `params` as `$1..$n`.
+- `{{alias}}` needs the target resource **initialized** — unlike Mongo's `ref`, which is a pure
+  function of config. For foreign keys use `service.defer()`; don't reorder registrations.
+- `create` refuses a caller-supplied id (use `insert`); `update` replaces the whole record (use
+  `patch`); `pick` deletes the record it returns; `load` rejects `opts.ttl`.
+- Drizzle wraps driver errors in `DrizzleQueryError` with the `pg` error on `cause` — classify
+  through `pgErrorToResourceError`, never by reading `error.code` off the outer error.
+- `DbConfig.schema` is the Postgres SCHEMA; the DATABASE is `meta.database`.
+- Unit specs live here; specs building a real `ServerContext` live in `@owlmeans/postgres`.
+
+## Depends On
+
+- `@owlmeans/resource`, `@owlmeans/context`, `@owlmeans/server-context`, `drizzle-orm`, peer `pg`/`ajv`

package/agent-meta/manifest.json

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

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

@@ -0,0 +1,186 @@
+---
+name: postgres-resource
+description: How to use @owlmeans/postgres-resource — PostgreSQL-backed Resource implementation. The AJV schema is the single source of truth for the table; structure reconciliation, code migrations, and {{alias}} custom SQL. Auto-invoked when defining a resource backed by PostgreSQL.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/postgres-resource
+
+**Layer:** Infra
+**Install:** `"@owlmeans/postgres-resource": "^0.1.15"` in `dependencies` (peers `pg`, `ajv`)
+
+The Postgres counterpart of [[mongo-resource]]. The difference that governs everything else: a
+Mongo collection has no structure, a Postgres table does — so **the resource layer owns the DDL**
+and derives it from the resource's AJV schema.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?)` | The resource factory. Aliases default to `DEFAULT_DB_ALIAS` (`'postgres'`). |
+| `PostgresResource<T>` | `Resource<T>` + `table`/`entity`, custom SQL, transactions, `insert`/`upsert`/`patch`/`purge`/`count`, `lock`/`unlock`. |
+| `PostgresDbService`, `PostgresDb`, `PostgresTx` | Service contract implemented by `@owlmeans/postgres`; the db handle `{ drizzle, pool, schema, database }`; the transaction façade. |
+| `TableSpec`, `ColumnSpec`, `PgPropertyOverride`, `PgRootOverride`, `DdlPlan` | The compiled table description and the `pg:` vocabulary types. |
+| `pgKeyword` | `{ keyword: 'pg', valid: true }` — register it when running AJV in strict mode. |
+| `schemaToTableSpec`, `pgTableName`, `pgIdentifier`, `quoteIdent`, `qualify`, `advisoryKey` | The compiler and identifier helpers. |
+| `refOf`, `resolvePlaceholders` | `{{alias}}` resolution — identifiers only. |
+| `PostgresError` family, `pgErrorToResourceError`, `describePgError` | Driver-error translation. |
+| `getDeclaration`, `resetDeclarations` | Module-scope index/migration declarations, keyed by alias. |
+| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `DEF_MIGRATIONS_TABLE`, `PgAutoSync`, `PgIndexMethod`, `PgReferentialAction`, `PgErrorCode` | Constants. |
+
+## The schema is the table — never write DDL
+
+```typescript
+export const makeProjectResource: ResourceMaker<ProjectRecord, ProjectResource> = (dbAlias, serviceAlias) => {
+  const resource = makePostgresResource<ProjectRecord, ProjectResource>(
+    RES_PROJECT, dbAlias, serviceAlias, makeProjectResource
+  )
+  resource.schema = ProjectSchema
+  resource.index('idx_project_entity', { columns: ['entityId'] })
+
+  return resource
+}
+context.registerResource(makeProjectResource())
+```
+
+Never call `pgTable`/`pgSchema`, never call `drizzle()`, never run `drizzle-kit`, never hand-write
+`CREATE TABLE`. Two owners of the same DDL is the failure mode this package exists to remove:
+reconciliation would drop what the other owner added.
+
+| JSON Schema | Postgres |
+|---|---|
+| `string` · `string`+`format:'uuid'` | `text` · `uuid` |
+| `DateSchema` (`{type:'object', format:'date-time'}`) | `timestamptz` |
+| `integer` · `number` · `boolean` | `integer` · `double precision` · `boolean` |
+| `array`, nested `object` | `jsonb` |
+| string `enum` | `text` + `CHECK` |
+| `nullable: true` · in `required[]` | nullable · `NOT NULL` |
+| `secure: true` | ciphertext column, `lock`/`unlock` aware |
+| `id` property | primary key, `gen_random_uuid()::text` default |
+
+**Thread `nullable` at every recursion level.** Mongo's mapper shipped this bug twice in exactly the
+same two places — `date-time` and optional nested objects. Cover both when you touch the mapper.
+
+## The `pg:` override vocabulary
+
+For what JSON Schema can't say. Per property: `column`, `type`, `length`, `precision`, `scale`,
+`nullable`, `default`/`defaultRaw`, `primaryKey`, `unique`, `index`, `references`, `jsonb`, `array`,
+`check`, `using`, `managed`, `comment`. At the root: `table`, `schema`, `primaryKey`, `unique`,
+`indexes`, `checks`, `unmanaged`, `autoSync`, `comment`.
+
+```typescript
+{
+  type: 'object',
+  properties: {
+    email: { type: 'string', pg: { type: 'varchar', length: 320, unique: true } },
+    ownerId: { type: 'string', pg: { references: { resource: 'users', onDelete: 'cascade' } } }
+  },
+  required: ['email'],
+  pg: { indexes: [{ name: 'idx_owner_created', columns: ['ownerId', 'createdAt'] }] }
+}
+```
+
+The compiler reads the raw schema object and never validates through AJV, so `pg:` costs nothing at
+runtime — but a consumer compiling that schema in **strict mode** must `ajv.addKeyword(pgKeyword)`.
+
+## Reconciliation is authoritative — `PgAutoSync`
+
+At `init()`: introspect → diff → apply the whole `DdlPlan` in one transaction under
+`pg_advisory_xact_lock`, so concurrent replicas don't race. `DbConfig.meta.autoSync`:
+
+| Value | Behaviour |
+|---|---|
+| `Full` (default) | add / retype+backfill / drop columns, reconcile indexes and constraints |
+| `Additive` | add only — never retypes, never drops |
+| `Off` | create if absent, otherwise leave alone |
+
+**`Full` DROPs columns the schema doesn't declare.** Adopting a table this package didn't create:
+boot once with `Additive`, confirm the plan comes out empty, then flip to `Full`. Columns listed in
+`pg.unmanaged` stay outside reconciliation's authority permanently. A cast Postgres cannot perform
+raises `PostgresCastRequired` instead of truncating.
+
+## Migrations bracket the sync
+
+```typescript
+resource.migration('0001-rescue-legacy', async tx => {
+  await tx.execute(`UPDATE {{}} SET slug = legacy WHERE slug IS NULL`)
+}, MigrationStage.Pre)
+```
+
+- `Pre` runs **before** the table is reshaped — the only place to rescue data reconciliation is
+  about to drop. `Post` runs **after**, so it can use the new columns.
+- On a table this package just created, every declared migration is **baselined** (recorded, not
+  executed) — a fresh table is already at head.
+- Applied once, in registration order, each in its own transaction, ledgered in
+  `_owlmeans_migrations` in the same Postgres schema.
+- The checksum fingerprints the function's **source text**. Keep bodies at module scope; a body
+  closed over a loop variable fingerprints the wrapper and drifts. An edited applied body raises
+  `MigrationConflict`; a throwing one raises `MigrationError` and aborts `init()`.
+
+## Custom SQL: identifiers interpolate, values never
+
+| Placeholder | Resolves to |
+|---|---|
+| `{{}}` / `{{self}}` | the owning resource's `"schema"."table"` |
+| `{{alias}}` | another registered Postgres resource's qualified table |
+| `{{alias.property}}` | that resource's qualified column |
+| `{{#alias}}` | the bare quoted table name (`ON CONFLICT ON CONSTRAINT`) |
+| `{{$}}` | the owning resource's quoted schema |
+
+```typescript
+await projects.select(
+  `SELECT p.* FROM {{}} p JOIN {{users}} u ON u.id = {{self.ownerId}} WHERE u.active = $1`, [true]
+)
+```
+
+Postgres cannot bind an identifier as a parameter — that is the entire reason this mechanism exists.
+Values have no such excuse: they stay in `params` as `$1..$n`. An unknown alias or property raises
+`PostgresPlaceholderError` at parse time.
+
+**Registration order matters here, unlike Mongo.** `{{alias}}` reads the other resource's
+*initialized* `table` spec, where mongo's `ref` derives a collection name from config alone. A
+foreign key whose target hasn't initialized is queued with `service.defer()` and drained by the
+middleware `appendPostgres` installs — use that rather than reordering registrations.
+
+## Method semantics that differ from the base contract
+
+| Method | Semantics |
+|---|---|
+| `create` | refuses a caller-supplied id (`RecordExists`) — use `insert` |
+| `update` | **replaces** the whole record — use `patch` to merge |
+| `pick` | `DELETE … RETURNING`: it deletes the record it returns, atomically |
+| `load` | rejects `opts.ttl` with `UnsupportedArgumentError` (mongo parity) |
+| `upsert` | `INSERT … ON CONFLICT DO UPDATE`, conflicting on the primary key by default |
+| `select`/`selectOne` | custom SQL marshalled back into `T`; `query`/`queryOne` return raw rows |
+
+## Errors
+
+Drizzle raises `DrizzleQueryError` and hangs the `pg` error off `cause`, so the driver `code` is not
+at the top level. `pgErrorToResourceError` unwraps (bounded — `cause` chains can be circular) before
+classifying, and keeps the original wrapper as `cause`. Unique violation → `RecordExists`, not-null →
+`MisshapedRecord`, plus the `Postgres*Error` family. Raw `code`/`detail`/`hint`/`severity` survive
+translation — consumers classify retryable DDL races on `42P01`/`42703`.
+
+## Config
+
+`DbConfig.schema` is the Postgres **SCHEMA** (layer-suffixed by `dbName()`); the **DATABASE** comes
+from `meta.database` and is never suffixed. Values starting with `/` are read as files by the
+existing `fileConfigReader` middleware.
+
+## Tests
+
+`bun test ./tests` in the package — unit specs (schema compilation, identifiers, placeholder
+resolution, error translation), no gate, no service. Specs that build a real `ServerContext` live in
+`@owlmeans/postgres` instead: a devDependency here on its own dependent is a cycle. See
+[[testing-integration]].
+
+## Depends On
+
+- `@owlmeans/resource` · `@owlmeans/context` · `@owlmeans/server-context` · `@owlmeans/basic-ids`
+- `drizzle-orm` (internal query builder) · peer `pg`, `ajv`
+
+## Related
+
+- [[postgres]] — the connection service this resolves through
+- [[resource]] — `Resource<T>`, migrations, the error family · [[mongo-resource]] — the Mongo counterpart

package/build/consts.d.ts

@@ -0,0 +1,81 @@
+export declare const DEFAULT_DB_ALIAS = "postgres";
+export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Table that records which code-registered migrations have already been applied.
+ * Lives in the same Postgres schema as the resources it tracks, so dropping the
+ * schema drops the ledger with it.
+ */
+export declare const DEF_MIGRATIONS_TABLE = "_owlmeans_migrations";
+/** JSON Schema keyword carrying the Postgres specific overrides. */
+export declare const PG_KEYWORD = "pg";
+/** Postgres `NAMEDATALEN - 1`. Identifiers past this are silently truncated by the server. */
+export declare const PG_MAX_IDENTIFIER = 63;
+/** Property name that carries the record identity across every OwlMeans resource. */
+export declare const ID_FIELD = "id";
+/** Fallback when a scalar property can't be mapped to anything more specific. */
+export declare const DEF_SQL_TYPE = "text";
+export declare const DEF_JSON_TYPE = "jsonb";
+/** Server side identity default for the implicit `id` primary key. */
+export declare const DEF_ID_DEFAULT = "gen_random_uuid()::text";
+/**
+ * How far structure reconciliation is allowed to go.
+ *
+ * `additive` is the adoption path for a table this package didn't create: it adds what's
+ * missing but never retypes and never drops, so a first boot against an existing schema
+ * converges without touching data. Flip to `full` once the plan comes out empty.
+ */
+export declare enum PgAutoSync {
+    Full = "full",
+    Additive = "additive",
+    Off = "off"
+}
+export declare enum PgIndexMethod {
+    BTree = "btree",
+    Hash = "hash",
+    Gin = "gin",
+    Gist = "gist",
+    Brin = "brin",
+    SpGist = "spgist"
+}
+export declare enum PgReferentialAction {
+    NoAction = "no action",
+    Restrict = "restrict",
+    Cascade = "cascade",
+    SetNull = "set null",
+    SetDefault = "set default"
+}
+/**
+ * Postgres error codes the resource layer translates into framework errors. Sourced
+ * from the `pg` driver's `DatabaseError.code`.
+ */
+export declare enum PgErrorCode {
+    UniqueViolation = "23505",
+    ForeignKeyViolation = "23503",
+    NotNullViolation = "23502",
+    CheckViolation = "23514",
+    UndefinedTable = "42P01",
+    UndefinedColumn = "42703",
+    DuplicateTable = "42P07",
+    DuplicateColumn = "42701",
+    DuplicateObject = "42710",
+    CannotCoerce = "42846",
+    DatatypeMismatch = "42804",
+    InvalidTextRepresentation = "22P02",
+    StringDataRightTruncation = "22001",
+    NumericValueOutOfRange = "22003",
+    SerializationFailure = "40001",
+    DeadlockDetected = "40P01",
+    NoActiveTransaction = "25001"
+}
+/**
+ * Postgres reports scalar values of these types as strings to avoid precision loss.
+ * The marshaller converts them back using the resource's schema.
+ */
+export declare const STRING_RETURNING_TYPES: readonly ["numeric", "bigint", "int8", "decimal", "money"];
+/** Built-in type OIDs the marshaller has to name to reach the driver's own parsers. */
+export declare enum PgTypeOid {
+    Date = 1082,
+    Timestamp = 1114,
+    TimestampTz = 1184
+}
+//# 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":"AACA,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAE1D,oEAAoE;AACpE,eAAO,MAAM,UAAU,OAAO,CAAA;AAE9B,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,qFAAqF;AACrF,eAAO,MAAM,QAAQ,OAAO,CAAA;AAE5B,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,eAAO,MAAM,aAAa,UAAU,CAAA;AAEpC,sEAAsE;AACtE,eAAO,MAAM,cAAc,4BAA4B,CAAA;AAEvD;;;;;;GAMG;AACH,oBAAY,UAAU;IACpB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAED,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,oBAAY,mBAAmB;IAC7B,QAAQ,cAAc;IACtB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,UAAU,gBAAgB;CAC3B;AAED;;;GAGG;AACH,oBAAY,WAAW;IACrB,eAAe,UAAU;IACzB,mBAAmB,UAAU;IAC7B,gBAAgB,UAAU;IAC1B,cAAc,UAAU;IACxB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,eAAe,UAAU;IACzB,YAAY,UAAU;IACtB,gBAAgB,UAAU;IAC1B,yBAAyB,UAAU;IACnC,yBAAyB,UAAU;IACnC,sBAAsB,UAAU;IAChC,oBAAoB,UAAU;IAC9B,gBAAgB,UAAU;IAC1B,mBAAmB,UAAU;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,4DAA6D,CAAA;AAEhG,uFAAuF;AACvF,oBAAY,SAAS;IACnB,IAAI,OAAO;IACX,SAAS,OAAO;IAChB,WAAW,OAAO;CACnB"}