@owlmeans/postgres-resource 0.1.18-rc.41 → 0.1.18-rc.42

package/build/utils/types.local.d.ts

@@ -0,0 +1,33 @@
+import type { SQL } from 'drizzle-orm';
+import { PG_KEYWORD } from '../consts.js';
+import type { PgPropertyOverride, PgRootOverride } from '../types.js';
+/**
+ * A value at a path, as the jsonb it is (`#>`) and as text (`#>>`). The path is ONE bound `text[]`
+ * parameter, so a segment holding a comma or a brace stays one segment.
+ */
+export interface PathTarget {
+    value: SQL;
+    text: SQL;
+    /** Absent, or a JSON `null` — what every other store reads as "no value". */
+    missing: SQL;
+}
+export interface RawProperty {
+    type?: string | string[];
+    format?: string;
+    enum?: unknown[];
+    items?: RawProperty;
+    maxLength?: number;
+    maximum?: number;
+    minimum?: number;
+    default?: unknown;
+    nullable?: boolean;
+    secure?: boolean;
+    [PG_KEYWORD]?: PgPropertyOverride;
+}
+export interface RawSchema {
+    properties?: Record<string, RawProperty>;
+    required?: string[];
+    allOf?: RawSchema[];
+    [PG_KEYWORD]?: PgRootOverride;
+}
+//# sourceMappingURL=types.local.d.ts.map

package/build/utils/types.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../../src/utils/types.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAErE;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,GAAG,CAAA;IACV,IAAI,EAAE,GAAG,CAAA;IACT,6EAA6E;IAC7E,OAAO,EAAE,GAAG,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;IAChB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,CAAC,UAAU,CAAC,CAAC,EAAE,kBAAkB,CAAA;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAA;IACnB,CAAC,UAAU,CAAC,CAAC,EAAE,cAAc,CAAA;CAC9B"}

package/build/utils/types.local.js

@@ -0,0 +1,2 @@
+import { PG_KEYWORD } from '../consts.js';
+//# sourceMappingURL=types.local.js.map

package/build/utils/types.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../../src/utils/types.local.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/postgres-resource",
-  "version": "0.1.18-rc.41",
+  "version": "0.1.18-rc.42",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -26,22 +26,23 @@
     "pg": "*"
   },
   "dependencies": {
-    "@noble/hashes": "^1.5.0",
-    "@owlmeans/basic-ids": "^0.1.18-rc.34",
-    "@owlmeans/context": "^0.1.18-rc.32",
-    "@owlmeans/resource": "^0.1.18-rc.37",
-    "@owlmeans/server-context": "^0.1.18-rc.40",
-    "@scure/base": "^2.3.0",
-    "drizzle-orm": "~0.45.2"
+    "@noble/hashes": "^2.4.0",
+    "@owlmeans/basic-ids": "^0.1.18-rc.36",
+    "@owlmeans/context": "^0.1.18-rc.33",
+    "@owlmeans/log": "^0.1.18-rc.1",
+    "@owlmeans/resource": "^0.1.18-rc.39",
+    "@owlmeans/server-context": "^0.1.18-rc.42",
+    "@scure/base": "^2.4.0",
+    "drizzle-orm": "~0.45.3"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-integration": "^0.1.18-rc.30",
-    "@types/bun": "^1.4.0",
-    "@types/node": "^26.1.0",
-    "@types/pg": "^8.20.4",
+    "@owlmeans/test-integration": "^0.1.18-rc.32",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
+    "@types/pg": "^8.23.1",
     "nodemon": "^3.1.14",
-    "pg": "^8.22.0",
+    "pg": "^8.23.1",
     "typescript": "^7.0.2"
   },
   "publishConfig": {

package/src/declarations.ts

@@ -1,14 +1,6 @@
 import { createMigrationRegistry } from '@owlmeans/resource'
-import type { MigrationRegistry } from '@owlmeans/resource'
-import type { AnySchema } from 'ajv'
 
-import type { PgIndexSpec, PostgresTx } from './types.js'
-
-export interface PostgresDeclaration {
-  schema?: AnySchema
-  indexes: PgIndexSpec[]
-  migrations: MigrationRegistry<PostgresTx>
-}
+import type { PostgresTx, PostgresDeclaration } from './types.js'
 
 /**
  * Per-alias declaration store, held at module scope rather than on the resource object.

package/src/errors.ts

@@ -4,6 +4,7 @@ import {
 } from '@owlmeans/resource'
 
 import { PgErrorCode } from './consts.js'
+import type { PgDriverError } from './types.local.js'
 
 export class PostgresError extends ResourceError {
   public static override typeName = `${ResourceError.typeName}PostgresError`
@@ -106,17 +107,6 @@ export class PostgresBootstrapError extends PostgresError {
   }
 }
 
-interface PgDriverError {
-  code?: string
-  detail?: string
-  hint?: string
-  severity?: string
-  constraint?: string
-  table?: string
-  column?: string
-  message?: string
-}
-
 const isDriverError = (error: unknown): error is PgDriverError =>
   error != null && typeof error === 'object' && 'code' in error
 

package/src/resource.ts

@@ -1,14 +1,7 @@
 import { appendContextual, assertContext } from '@owlmeans/context'
-import {
-  MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError, UnsupportedArgumentError
-} from '@owlmeans/resource'
-import type {
-  Criteria, FirstOptions, ListOptions, ListResult, MigrationStage, ResourceRecord, WriteOptions
-} from '@owlmeans/resource'
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError, UnsupportedArgumentError, type Criteria, type FirstOptions, type ListOptions, type ListResult, type MigrationStage, type ResourceRecord, type WriteOptions } from '@owlmeans/resource'
 import type { AnySchema, JSONSchemaType } from 'ajv'
-import { eq, sql } from 'drizzle-orm'
-import type { SQL } from 'drizzle-orm'
+import { eq, sql, type SQL } from 'drizzle-orm'
 import type { PoolClient, QueryResultRow } from 'pg'
 
 import { DEFAULT_DB_ALIAS, DEFAULT_PAGE_SIZE, ID_FIELD } from './consts.js'
@@ -24,9 +17,8 @@ import { initializeTable } from './utils/life-cycle.js'
 import { recordToFullValues, recordToValues, resultToRecord, rowToRecord } from './utils/marshal.js'
 import { makeTx } from './utils/migrations.js'
 import { refOf, resolvePlaceholders } from './utils/sql.js'
+import type { Config, Context } from './types.local.js'
 
-type Config = ServerConfig
-type Context<C extends Config = Config> = ServerContext<C>
 
 /** Postgres has no row expiry — silently ignoring a TTL would lose data. */
 const refuseTtl = (opts?: WriteOptions): void => {

package/src/types.local.ts

@@ -0,0 +1,16 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export interface PgDriverError {
+  code?: string
+  detail?: string
+  hint?: string
+  severity?: string
+  constraint?: string
+  table?: string
+  column?: string
+  message?: string
+}
+
+export type Config = ServerConfig
+
+export type Context<C extends Config = Config> = ServerContext<C>

package/src/types.ts

@@ -1,7 +1,4 @@
-import type {
-  Criteria, DbLocker, LockableResource, MigratableResource, Resource,
-  ResourceDbService, ResourceRecord, WriteOptions
-} from '@owlmeans/resource'
+import type { Criteria, DbLocker, LockableResource, MigratableResource, Resource, ResourceDbService, ResourceRecord, WriteOptions, MigrationRegistry } from '@owlmeans/resource'
 import type { AnySchema } from 'ajv'
 import type { Pool, PoolClient, QueryResultRow } from 'pg'
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
@@ -321,3 +318,9 @@ export interface DdlPlan {
   fresh: boolean
   statements: DdlStatement[]
 }
+
+export interface PostgresDeclaration {
+  schema?: AnySchema
+  indexes: PgIndexSpec[]
+  migrations: MigrationRegistry<PostgresTx>
+}

package/src/utils/consts.local.ts

@@ -0,0 +1,68 @@
+import { PgErrorCode } from '../consts.js'
+
+export const COMPARISON: Record<string, string> = {
+  $eq: '=', $ne: '<>', $gt: '>', $gte: '>=', $lt: '<', $lte: '<='
+}
+
+/** A type cast as `pg_get_expr` / `pg_get_indexdef` print one: `::text`, `::character varying(64)[]`. */
+export const CAST = /::(?:character varying|double precision|bit varying|timestamp with(?:out)? time zone|time with(?:out)? time zone|[a-z_][a-z0-9_]*)(?:\(\d+(?:\s*,\s*\d+)?\))?(?:\[\])?/g
+
+/**
+ * `pg_attribute` + `format_type` rather than `information_schema.columns`, because it
+ * returns one canonical type string with the typmod already baked in
+ * (`character varying(320)`). `information_schema` splits the same information across
+ * four columns and reports every array as `ARRAY`, which no comparison can use.
+ */
+export const COLUMNS = `
+  SELECT a.attname                            AS name,
+         format_type(a.atttypid, a.atttypmod) AS type,
+         a.attnotnull                         AS not_null,
+         pg_get_expr(d.adbin, d.adrelid)      AS default_expr,
+         a.attidentity                        AS identity,
+         a.attgenerated                       AS generated,
+         a.attnum                             AS ordinal
+    FROM pg_attribute a
+    LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+   WHERE a.attrelid = to_regclass($1) AND a.attnum > 0 AND NOT a.attisdropped
+   ORDER BY a.attnum
+`
+
+export const INDEXES = `
+  SELECT indexname AS name, indexdef AS definition
+    FROM pg_indexes
+   WHERE schemaname = $1 AND tablename = $2
+`
+
+export const CONSTRAINTS = `
+  SELECT c.conname AS name, c.contype AS type, pg_get_constraintdef(c.oid) AS definition
+    FROM pg_constraint c
+   WHERE c.conrelid = to_regclass($1)
+     AND c.contype <> 'n'
+`
+
+export const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/
+
+/**
+ * `{{ }}` / `{{self}}`      — the owning resource's qualified table
+ * `{{alias}}`               — another registered postgres resource's qualified table
+ * `{{alias.property}}`      — a qualified column of that resource
+ * `{{#alias}}`              — the bare quoted table name, for `ON CONFLICT ON CONSTRAINT`
+ * `{{$}}`                   — the owning resource's quoted schema
+ *
+ * Resource aliases in this codebase use `-` and `:` but never `.`, so `.` is unambiguous
+ * as the column separator.
+ */
+export const PLACEHOLDER = /\{\{\s*([#$]?)([A-Za-z0-9_:-]*)(?:\.([A-Za-z0-9_]+))?\s*\}\}/g
+
+/**
+ * Codes that mean "the cast is legal, the data isn't": a `text` column holding `'a'` retyped to
+ * `integer`, a value too wide for the new length, a number past the new range. Postgres refuses
+ * each of these rather than truncating, and the remedy is the same one a refused cast needs — so
+ * they are only read as a cast problem here, inside DDL. On the CRUD path the identical code means
+ * a caller passed a bad value, which is a different bug with a different fix.
+ */
+export const CAST_DATA_CODES: string[] = [
+  PgErrorCode.InvalidTextRepresentation,
+  PgErrorCode.StringDataRightTruncation,
+  PgErrorCode.NumericValueOutOfRange
+]

package/src/utils/criteria.ts

@@ -1,13 +1,9 @@
-import { UnsupportedArgumentError } from '@owlmeans/resource'
-import type { Criteria, FieldOperators, Sort } from '@owlmeans/resource'
-import { and, asc, desc, or, param, sql } from 'drizzle-orm'
-import type { SQL } from 'drizzle-orm'
+import { UnsupportedArgumentError, type Criteria, type FieldOperators, type Sort } from '@owlmeans/resource'
+import { and, asc, desc, or, param, sql, type SQL } from 'drizzle-orm'
 
 import type { ColumnSpec, PgRuntimeTable, TableSpec } from '../types.js'
-
-const COMPARISON: Record<string, string> = {
-  $eq: '=', $ne: '<>', $gt: '>', $gte: '>=', $lt: '<', $lte: '<='
-}
+import { COMPARISON } from './consts.local.js'
+import type { PathTarget } from './types.local.js'
 
 const columnRef = (table: PgRuntimeTable, column: ColumnSpec): SQL => sql`${table[column.property]}`
 
@@ -166,17 +162,6 @@ const escapeLike = (value: string): string => value.replace(/[\\%_]/g, match =>
 
 // ─── Dotted paths into a jsonb column ────────────────────────────────────────────────────────────
 
-/**
- * A value at a path, as the jsonb it is (`#>`) and as text (`#>>`). The path is ONE bound `text[]`
- * parameter, so a segment holding a comma or a brace stays one segment.
- */
-interface PathTarget {
-  value: SQL
-  text: SQL
-  /** Absent, or a JSON `null` — what every other store reads as "no value". */
-  missing: SQL
-}
-
 const pathTarget = (table: PgRuntimeTable, column: ColumnSpec, path: string[]): PathTarget => {
   const value = sql`(${columnRef(table, column)} #> ${param(path)}::text[])`
 

package/src/utils/diff.ts

@@ -7,6 +7,7 @@ import type {
   ColumnSpec, DdlPlan, DdlStatement, LiveTable, PgIndexSpec, PostgresResource, TableSpec
 } from '../types.js'
 import { qualify, quoteIdent } from './name.js'
+import { CAST } from './consts.local.js'
 
 const literal = (value: string | number | boolean | null): string => {
   if (value === null) return 'NULL'
@@ -23,9 +24,6 @@ const defaultExpression = (column: ColumnSpec): string | undefined => {
   return undefined
 }
 
-/** A type cast as `pg_get_expr` / `pg_get_indexdef` print one: `::text`, `::character varying(64)[]`. */
-const CAST = /::(?:character varying|double precision|bit varying|timestamp with(?:out)? time zone|time with(?:out)? time zone|[a-z_][a-z0-9_]*)(?:\(\d+(?:\s*,\s*\d+)?\))?(?:\[\])?/g
-
 /**
  * Postgres echoes defaults back with explicit casts — a declared `'active'` comes back as
  * `'active'::text`. Compare without them, so an unchanged default doesn't look like drift on
@@ -303,7 +301,10 @@ export const planSync = (
   }
   const liveConstraints: Record<string, string> = {}
   for (const constraint of live.constraints) {
-    if (constraint.type === 'p' || constraint.type === 'f') {
+    // Primary and foreign keys have their own paths. A NOT NULL (`n`) is a constraint row since
+    // Postgres 18 (`<table>_<column>_not_null`) and is owned by the column step above: dropping it by
+    // name is refused on a primary key column, and on any other it would undo a `required` property.
+    if (constraint.type === 'p' || constraint.type === 'f' || constraint.type === 'n') {
       continue
     }
     liveConstraints[constraint.name] = constraint.definition

package/src/utils/index.ts

@@ -2,6 +2,7 @@ export * from './criteria.js'
 export * from './diff.js'
 export * from './introspect.js'
 export * from './life-cycle.js'
+export type * from './types.js'
 export * from './marshal.js'
 export * from './migrations.js'
 export * from './name.js'

package/src/utils/introspect.ts

@@ -1,38 +1,7 @@
 import type { PoolClient } from 'pg'
 
 import type { LiveColumn, LiveConstraint, LiveIndex, LiveTable } from '../types.js'
-
-/**
- * `pg_attribute` + `format_type` rather than `information_schema.columns`, because it
- * returns one canonical type string with the typmod already baked in
- * (`character varying(320)`). `information_schema` splits the same information across
- * four columns and reports every array as `ARRAY`, which no comparison can use.
- */
-const COLUMNS = `
-  SELECT a.attname                            AS name,
-         format_type(a.atttypid, a.atttypmod) AS type,
-         a.attnotnull                         AS not_null,
-         pg_get_expr(d.adbin, d.adrelid)      AS default_expr,
-         a.attidentity                        AS identity,
-         a.attgenerated                       AS generated,
-         a.attnum                             AS ordinal
-    FROM pg_attribute a
-    LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
-   WHERE a.attrelid = to_regclass($1) AND a.attnum > 0 AND NOT a.attisdropped
-   ORDER BY a.attnum
-`
-
-const INDEXES = `
-  SELECT indexname AS name, indexdef AS definition
-    FROM pg_indexes
-   WHERE schemaname = $1 AND tablename = $2
-`
-
-const CONSTRAINTS = `
-  SELECT c.conname AS name, c.contype AS type, pg_get_constraintdef(c.oid) AS definition
-    FROM pg_constraint c
-   WHERE c.conrelid = to_regclass($1)
-`
+import { COLUMNS, CONSTRAINTS, INDEXES } from './consts.local.js'
 
 /** Read the table exactly as Postgres currently holds it. */
 export const introspectTable = async (

package/src/utils/life-cycle.ts

@@ -1,14 +1,12 @@
 import type { BasicContext } from '@owlmeans/context'
-import { MigrationStage, runMigrations } from '@owlmeans/resource'
-import type { DbConfig, MigrationReport, ResourceRecord } from '@owlmeans/resource'
+import { MigrationStage, runMigrations, type DbConfig, type MigrationReport, type ResourceRecord } from '@owlmeans/resource'
+import { logger } from '@owlmeans/log'
 import type { PoolClient } from 'pg'
 
 import { DEF_MIGRATIONS_TABLE, PgAutoSync } from '../consts.js'
 import { getDeclaration } from '../declarations.js'
 import { describePgError, pgErrorToResourceError } from '../errors.js'
-import type {
-  PgRuntimeTable, PostgresDb, PostgresMeta, PostgresResource, TableSpec
-} from '../types.js'
+import type { PostgresDb, PostgresMeta, PostgresResource, TableSpec } from '../types.js'
 import { planForeignKeys, planSync } from './diff.js'
 import { introspectTable } from './introspect.js'
 import { makeMigrationStore } from './migrations.js'
@@ -17,13 +15,9 @@ import { schemaToTableSpec } from './schema.js'
 import { refOf, resolvePlaceholders } from './sql.js'
 import { acquireLock, applyPlan, ensureSchema, releaseLock } from './sync.js'
 import { specToTable } from './table.js'
+import type { TableInit } from './types.js'
 
-export interface TableInit {
-  spec: TableSpec
-  /** The Drizzle table CRUD is built against. */
-  entity: PgRuntimeTable
-  reports: MigrationReport[]
-}
+const log = logger('postgres-resource')
 
 /**
  * Bring a resource's table to the shape its schema declares, then hand back everything the
@@ -90,10 +84,9 @@ export const initializeTable = async (
 
     for (const report of reports) {
       if (report.applied.length > 0) {
-        console.log(
-          `@owlmeans/postgres-resource: ${spec.qualified} applied ${report.stage} migrations —`
-          + ` ${report.applied.join(', ')}`
-        )
+        log.info('Migrations applied', {
+          resource: resource.alias, table: spec.qualified, stage: report.stage, applied: report.applied,
+        }, { event: 'migration.applied' })
       }
     }
   } finally {

package/src/utils/marshal.ts

@@ -1,9 +1,12 @@
 import type { ResourceRecord } from '@owlmeans/resource'
+import { logThrottle, logger } from '@owlmeans/log'
 import { types as pgTypes } from 'pg'
 
 import { ID_FIELD, PgTypeOid } from '../consts.js'
 import type { ColumnSpec, TableSpec } from '../types.js'
 
+const log = logger('postgres-resource')
+
 /**
  * Parse a temporal value the way the driver would have.
  *
@@ -23,7 +26,7 @@ const toDate = (value: string, column: ColumnSpec): unknown => {
   return (pgTypes.getTypeParser(oid as never) as (raw: string) => unknown)(value)
 }
 
-const fromDriver = (value: unknown, column: ColumnSpec): unknown => {
+const fromDriver = (value: unknown, column: ColumnSpec, table?: string): unknown => {
   if (value == null) {
     return value
   }
@@ -44,10 +47,12 @@ const fromDriver = (value: unknown, column: ColumnSpec): unknown => {
       }
       const parsed = Number(value)
       if (!Number.isSafeInteger(parsed)) {
-        console.warn(
-          `@owlmeans/postgres-resource: "${column.column}" holds ${value}, which exceeds the safe`
-          + ' integer range — the value read back is imprecise.'
-        )
+        // Fires per row read: one line per window per column is enough.
+        if (logThrottle(`postgres-resource:${table ?? ''}:${column.column}:unsafe-bigint`, 300_000)) {
+          log.warn('Bigint column value exceeds the safe integer range; the value read back is imprecise', {
+            table, column: column.column,
+          })
+        }
       }
 
       return parsed
@@ -100,7 +105,7 @@ export const rowToRecord = <T extends ResourceRecord>(row: Record<string, unknow
       record[key] = value
       continue
     }
-    record[column.property] = fromDriver(value, column)
+    record[column.property] = fromDriver(value, column, spec.qualified)
   }
   if (record[ID_FIELD] != null) {
     record[ID_FIELD] = `${record[ID_FIELD]}`
@@ -123,7 +128,7 @@ export const resultToRecord = <T extends ResourceRecord>(
   const record: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(row)) {
     const column = spec.byProperty[key]
-    record[key] = column == null ? value : fromDriver(value, column)
+    record[key] = column == null ? value : fromDriver(value, column, spec.qualified)
   }
   if (record[ID_FIELD] != null) {
     record[ID_FIELD] = `${record[ID_FIELD]}`

package/src/utils/name.ts

@@ -1,11 +1,10 @@
-import { sha256 } from '@noble/hashes/sha2'
+import { sha256 } from '@noble/hashes/sha2.js'
 import { hex } from '@scure/base'
 import type { DbConfig, ResourceRecord } from '@owlmeans/resource'
 
 import { PG_MAX_IDENTIFIER } from '../consts.js'
 import type { PostgresResource } from '../types.js'
-
-const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/
+import { SAFE_IDENTIFIER } from './consts.local.js'
 
 /**
  * Coerce an arbitrary name into a legal Postgres identifier of at most 63 bytes.

package/src/utils/schema.ts

@@ -1,35 +1,15 @@
 import { UnsupportedArgumentError } from '@owlmeans/resource'
 import type { AnySchema } from 'ajv'
+import { logger } from '@owlmeans/log'
 
 import {
   DEF_ID_DEFAULT, DEF_JSON_TYPE, DEF_SQL_TYPE, ID_FIELD, PG_KEYWORD, PgIndexMethod
 } from '../consts.js'
-import type {
-  ColumnJsonType, ColumnSpec, PgCheckSpec, PgIndexSpec, PgPropertyOverride, PgRootOverride,
-  PgReferenceSpec, PgUniqueSpec, TableSpec
-} from '../types.js'
+import type { ColumnJsonType, ColumnSpec, PgCheckSpec, PgIndexSpec, PgPropertyOverride, PgReferenceSpec, PgUniqueSpec, TableSpec } from '../types.js'
 import { pgIdentifier, qualify, quoteIdent } from './name.js'
+import type { RawProperty, RawSchema } from './types.local.js'
 
-interface RawProperty {
-  type?: string | string[]
-  format?: string
-  enum?: unknown[]
-  items?: RawProperty
-  maxLength?: number
-  maximum?: number
-  minimum?: number
-  default?: unknown
-  nullable?: boolean
-  secure?: boolean
-  [PG_KEYWORD]?: PgPropertyOverride
-}
-
-interface RawSchema {
-  properties?: Record<string, RawProperty>
-  required?: string[]
-  allOf?: RawSchema[]
-  [PG_KEYWORD]?: PgRootOverride
-}
+const log = logger('postgres-resource')
 
 const INT32_MAX = 2147483647
 
@@ -244,10 +224,7 @@ const byName = <T extends { name?: string }>(specs: T[], alias: string, kind: st
   for (const spec of specs) {
     const name = spec.name!
     if (seen.has(name)) {
-      console.warn(
-        `@owlmeans/postgres-resource: ${alias} declares ${kind} "${name}" more than once —`
-        + ' keeping the first declaration.'
-      )
+      log.warn('Duplicate declaration, keeping the first one', { resource: alias, kind, name })
       continue
     }
     seen.set(name, spec)
@@ -305,10 +282,9 @@ export const schemaToTableSpec = (
 
     if (override.index != null && override.index !== false) {
       if (column.secure) {
-        console.warn(
-          `@owlmeans/postgres-resource: index on secure column "${alias}.${name}" — encryption`
-          + ' is non-deterministic, so equality lookups through it will never match.'
-        )
+        log.warn('Index on a secure column will never match: encryption is non-deterministic', {
+          resource: alias, column: name,
+        })
       }
       const specs = override.index === true
         ? [{ columns: [name] }]

package/src/utils/sync.ts

@@ -1,23 +1,13 @@
+import { logger } from '@owlmeans/log'
 import type { PoolClient } from 'pg'
 
-import { PgErrorCode } from '../consts.js'
 import { PostgresCastRequired, PostgresSyncError, describePgError, pgErrorToResourceError } from '../errors.js'
 import type { DdlPlan, TableSpec } from '../types.js'
 import { countNonNull } from './introspect.js'
 import { advisoryKey, quoteIdent } from './name.js'
+import { CAST_DATA_CODES } from './consts.local.js'
 
-/**
- * Codes that mean "the cast is legal, the data isn't": a `text` column holding `'a'` retyped to
- * `integer`, a value too wide for the new length, a number past the new range. Postgres refuses
- * each of these rather than truncating, and the remedy is the same one a refused cast needs — so
- * they are only read as a cast problem here, inside DDL. On the CRUD path the identical code means
- * a caller passed a bad value, which is a different bug with a different fix.
- */
-const CAST_DATA_CODES: string[] = [
-  PgErrorCode.InvalidTextRepresentation,
-  PgErrorCode.StringDataRightTruncation,
-  PgErrorCode.NumericValueOutOfRange
-]
+const log = logger('postgres-resource')
 
 /**
  * Serialize initialization across replicas. A session level lock, not `xact`, because
@@ -75,11 +65,9 @@ export const applyPlan = async (
     for (const statement of plan.statements) {
       current = statement.sql
       if (statement.destructive === true && (statement.affected ?? 0) > 0) {
-        console.warn(
-          `@owlmeans/postgres-resource: dropping ${spec.qualified}.${statement.target} —`
-          + ` ${statement.affected} row(s) hold a value. Declare it under \`pg.unmanaged\``
-          + ' or set `pg: { managed: false }` to keep it.'
-        )
+        log.warn('Dropping a column that holds values; declare it under pg.unmanaged or set pg.managed false to keep it', {
+          table: spec.qualified, column: statement.target, rows: statement.affected,
+        }, { event: 'migration.drop' })
       }
       await client.query(statement.sql)
     }

package/src/utils/types.local.ts

@@ -0,0 +1,35 @@
+import type { SQL } from 'drizzle-orm'
+import { PG_KEYWORD } from '../consts.js'
+import type { PgPropertyOverride, PgRootOverride } from '../types.js'
+
+/**
+ * A value at a path, as the jsonb it is (`#>`) and as text (`#>>`). The path is ONE bound `text[]`
+ * parameter, so a segment holding a comma or a brace stays one segment.
+ */
+export interface PathTarget {
+  value: SQL
+  text: SQL
+  /** Absent, or a JSON `null` — what every other store reads as "no value". */
+  missing: SQL
+}
+
+export interface RawProperty {
+  type?: string | string[]
+  format?: string
+  enum?: unknown[]
+  items?: RawProperty
+  maxLength?: number
+  maximum?: number
+  minimum?: number
+  default?: unknown
+  nullable?: boolean
+  secure?: boolean
+  [PG_KEYWORD]?: PgPropertyOverride
+}
+
+export interface RawSchema {
+  properties?: Record<string, RawProperty>
+  required?: string[]
+  allOf?: RawSchema[]
+  [PG_KEYWORD]?: PgRootOverride
+}