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

package/src/utils/sql/types.ts

@@ -0,0 +1,25 @@
+import type { TableSpec } from '../../types.js'
+
+/**
+ * `{{alias}}` placeholders of custom SQL, resolved through ONE context's registered postgres
+ * resources. Reached as `pgPlaceholdersOf(context)`.
+ */
+export interface PgPlaceholderHelper {
+  /**
+   * Fully qualified table of a registered postgres resource; omit the alias for `self`.
+   * This is what `PostgresTx.ref` and `PostgresResource.ref` resolve through.
+   *
+   * @throws {PostgresPlaceholderError}
+   */
+  refOf: (self: TableSpec | null, alias?: string) => string
+  /**
+   * Rewrite `{{...}}` placeholders into quoted identifiers.
+   *
+   * Identifiers only — `$1`-style parameters are left exactly as written and their values
+   * never pass through here. Postgres can't bind an identifier as a parameter, which is the
+   * whole reason this mechanism has to exist; values have no such excuse.
+   *
+   * @throws {PostgresPlaceholderError}
+   */
+  resolvePlaceholders: (text: string, self: TableSpec | null) => string
+}

package/src/utils/sync/types.ts

@@ -0,0 +1,25 @@
+import type { DdlPlan, TableSpec } from '../../types.js'
+
+/** The reconciliation steps run over one checked out connection. */
+export interface PgSyncHelper {
+  /**
+   * Serialize initialization across replicas. A session level lock, not `xact`, because
+   * migrations run in their own transactions inside the critical section.
+   */
+  acquireLock: (qualified: string) => Promise<void>
+  /** Release the {@link PgSyncHelper.acquireLock} lock; never masks the failure that preceded it. */
+  releaseLock: (qualified: string) => Promise<void>
+  /** `CREATE SCHEMA IF NOT EXISTS`. */
+  ensureSchema: (schema: string) => Promise<void>
+  /**
+   * Apply a reconciliation plan in a single transaction.
+   *
+   * Postgres DDL is transactional, so a plan that fails partway leaves the table exactly as
+   * it was. That property is what makes converging without confirmation prompts tolerable —
+   * the table is either fully converged or untouched, never half migrated.
+   *
+   * @throws {PostgresCastRequired} Postgres refused an automatic cast.
+   * @throws {PostgresSyncError} any other statement failed — the message names the statement.
+   */
+  applyPlan: (spec: TableSpec, plan: DdlPlan) => Promise<DdlPlan>
+}

package/src/utils/sync.ts

@@ -1,106 +1,88 @@
+import { logger } from '@owlmeans/log'
 import type { PoolClient } from 'pg'
 
-import { PgErrorCode } from '../consts.js'
-import { PostgresCastRequired, PostgresSyncError, describePgError, pgErrorToResourceError } from '../errors.js'
+import { PostgresCastRequired, PostgresSyncError } from '../errors.js'
+import { pgErrorHelper } from '../pg-error.js'
 import type { DdlPlan, TableSpec } from '../types.js'
-import { countNonNull } from './introspect.js'
-import { advisoryKey, quoteIdent } from './name.js'
+import { makePgIntrospectHelper } from './introspect.js'
+import { pgNameHelper } from './name.js'
+import { CAST_DATA_CODES } from './consts.local.js'
+import type { PgSyncHelper } from './sync/types.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
- * migrations run in their own transactions inside the critical section.
- */
-export const acquireLock = async (client: PoolClient, qualified: string): Promise<void> => {
-  const [first, second] = advisoryKey(qualified)
-  await client.query('SELECT pg_advisory_lock($1, $2)', [first, second])
-}
+export const makePgSyncHelper = (client: PoolClient): PgSyncHelper => {
+  const { describePgError, pgErrorToResourceError } = pgErrorHelper
+  const { advisoryKey, quoteIdent } = pgNameHelper
+  const introspect = makePgIntrospectHelper(client)
 
-export const releaseLock = async (client: PoolClient, qualified: string): Promise<void> => {
-  const [first, second] = advisoryKey(qualified)
-  try {
-    await client.query('SELECT pg_advisory_unlock($1, $2)', [first, second])
-  } catch {
-    /** Releasing the session drops the lock anyway — never mask the original failure. */
+  const acquireLock = async (qualified: string): Promise<void> => {
+    const [first, second] = advisoryKey(qualified)
+    await client.query('SELECT pg_advisory_lock($1, $2)', [first, second])
   }
-}
 
-export const ensureSchema = async (client: PoolClient, schema: string): Promise<void> => {
-  try {
-    await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
-  } catch (error) {
-    throw pgErrorToResourceError(error)
+  const releaseLock = async (qualified: string): Promise<void> => {
+    const [first, second] = advisoryKey(qualified)
+    try {
+      await client.query('SELECT pg_advisory_unlock($1, $2)', [first, second])
+    } catch {
+      /** Releasing the session drops the lock anyway — never mask the original failure. */
+    }
   }
-}
 
-/**
- * Apply a reconciliation plan in a single transaction.
- *
- * Postgres DDL is transactional, so a plan that fails partway leaves the table exactly as
- * it was. That property is what makes converging without confirmation prompts tolerable —
- * the table is either fully converged or untouched, never half migrated.
- *
- * @throws {PostgresCastRequired} Postgres refused an automatic cast.
- * @throws {PostgresSyncError} any other statement failed — the message names the statement.
- */
-export const applyPlan = async (
-  client: PoolClient, spec: TableSpec, plan: DdlPlan
-): Promise<DdlPlan> => {
-  if (plan.statements.length < 1) {
-    return plan
+  const ensureSchema = async (schema: string): Promise<void> => {
+    try {
+      await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
+    } catch (error) {
+      throw pgErrorToResourceError(error)
+    }
   }
 
-  /** Read what a drop would cost before the transaction opens, so the log can say it. */
-  for (const statement of plan.statements) {
-    if (statement.destructive === true) {
-      statement.affected = await countNonNull(client, spec.qualified, statement.target)
+  const applyPlan = async (spec: TableSpec, plan: DdlPlan): Promise<DdlPlan> => {
+    if (plan.statements.length < 1) {
+      return plan
     }
-  }
 
-  await client.query('BEGIN')
-  let current = ''
-  try {
+    /** Read what a drop would cost before the transaction opens, so the log can say it. */
     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.'
-        )
+      if (statement.destructive === true) {
+        statement.affected = await introspect.countNonNull(spec.qualified, statement.target)
       }
-      await client.query(statement.sql)
     }
-    await client.query('COMMIT')
-  } catch (error) {
-    await client.query('ROLLBACK').catch(() => undefined)
-    const translated = pgErrorToResourceError(error)
-    const code = (error as { code?: string } | null)?.code
-    if (translated instanceof PostgresCastRequired || (code != null && CAST_DATA_CODES.includes(code))) {
-      const failure = new PostgresCastRequired(
-        `${spec.qualified}: ${describePgError(error)} — statement: ${current}.`
-        + ' Declare `pg: { using: \'<expr>\' }` on the property, or perform the change in a'
-        + ' `pre` migration so reconciliation observes no drift.'
-      )
+
+    await client.query('BEGIN')
+    let current = ''
+    try {
+      for (const statement of plan.statements) {
+        current = statement.sql
+        if (statement.destructive === true && (statement.affected ?? 0) > 0) {
+          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)
+      }
+      await client.query('COMMIT')
+    } catch (error) {
+      await client.query('ROLLBACK').catch(() => undefined)
+      const translated = pgErrorToResourceError(error)
+      const code = (error as { code?: string } | null)?.code
+      if (translated instanceof PostgresCastRequired || (code != null && CAST_DATA_CODES.includes(code))) {
+        const failure = new PostgresCastRequired(
+          `${spec.qualified}: ${describePgError(error)} — statement: ${current}.`
+          + ' Declare `pg: { using: \'<expr>\' }` on the property, or perform the change in a'
+          + ' `pre` migration so reconciliation observes no drift.'
+        )
+        failure.cause = error
+        throw failure
+      }
+      const failure = new PostgresSyncError(`${spec.qualified}: ${describePgError(error)} — statement: ${current}`)
       failure.cause = error
       throw failure
     }
-    const failure = new PostgresSyncError(`${spec.qualified}: ${describePgError(error)} — statement: ${current}`)
-    failure.cause = error
-    throw failure
+
+    return plan
   }
 
-  return plan
+  return { acquireLock, releaseLock, ensureSchema, applyPlan }
 }

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
+}

package/src/utils/types.ts

@@ -0,0 +1,19 @@
+import type { PgRuntimeTable, TableSpec } from '../types.js'
+import type { MigrationReport } from '@owlmeans/resource'
+import type { BasicContext } from '@owlmeans/context'
+
+export interface TableInit {
+  spec: TableSpec
+  /** The Drizzle table CRUD is built against. */
+  entity: PgRuntimeTable
+  reports: MigrationReport[]
+}
+
+/**
+ * The context a placeholder resolves through.
+ *
+ * Resolution reads exactly one thing — `context.resource(alias).table` — so the config a context
+ * carries is irrelevant here, and pinning one would force every caller holding a server context
+ * to cast its way in. Deliberately open, and named so callers pass what they already have.
+ */
+export type PlaceholderContext = BasicContext<any>

package/tests/criteria.spec.ts

@@ -6,9 +6,12 @@ import { sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
 import { PgDialect } from 'drizzle-orm/pg-core'
 
-import { criteriaToSql, schemaToTableSpec, sortToSql, specToTable } from '@owlmeans/postgres-resource'
+import { pgCriteriaHelper, pgSchemaHelper, specToTable } from '@owlmeans/postgres-resource'
 import type { PgRuntimeTable, TableSpec } from '@owlmeans/postgres-resource'
 
+const { criteriaToSql, sortToSql } = pgCriteriaHelper
+const { schemaToTableSpec } = pgSchemaHelper
+
 /**
  * Criteria translation is where a typo becomes either an error or a whole-table scan, and
  * where a value has to stay a bound parameter instead of becoming statement text. Neither

package/tests/diff.spec.ts

@@ -1,8 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 
-import { canonicalDefinition, planSync, schemaToTableSpec } from '@owlmeans/postgres-resource'
+import { pgDiffHelper, pgSchemaHelper } from '@owlmeans/postgres-resource'
 import type { LiveColumn, LiveTable, TableSpec } from '@owlmeans/postgres-resource'
 
+const { canonicalDefinition, planSync } = pgDiffHelper
+const { schemaToTableSpec } = pgSchemaHelper
+
 const specOf = (idType: 'string' | 'integer'): TableSpec =>
   schemaToTableSpec('tasks', {
     type: 'object',
@@ -109,3 +112,27 @@ describe('@owlmeans/postgres-resource — comparing a declared definition with t
     }
   })
 })
+
+describe('@owlmeans/postgres-resource — NOT NULL constraints of Postgres 18', () => {
+  test('a not-null constraint row is never planned for a drop', () => {
+    // From 18 every NOT NULL is a pg_constraint row named `<table>_<column>_not_null`. The platform
+    // names its own constraints after the table too, so it took these for its own leftovers and sent
+    // `DROP CONSTRAINT …_id_not_null` — which Postgres refuses on a primary key column.
+    const live: LiveTable = {
+      exists: true,
+      columns: [
+        columnOf({ name: 'id', type: 'text' }),
+        columnOf({ name: 'title', type: 'text', notNull: false }),
+      ],
+      indexes: [],
+      constraints: [
+        { name: 'tasks_id_not_null', type: 'n', definition: 'NOT NULL id' },
+        { name: 'task_entry_id_not_null', type: 'n', definition: 'NOT NULL id' },
+      ],
+    }
+
+    const dropped = planSync(specOf('string'), live).statements.filter(statement => statement.kind === 'drop-constraint')
+    expect(dropped).toEqual([])
+  })
+})
+

package/tests/errors.spec.ts

@@ -2,11 +2,12 @@ import { describe, expect, test } from 'bun:test'
 import { MisshapedRecord, RecordExists, ResourceError } from '@owlmeans/resource'
 
 import {
-  describePgError, PgErrorCode, PostgresCastRequired, PostgresCheckError, PostgresConnectionError,
-  PostgresConstraintError, PostgresDeadlockError, PostgresError, PostgresForeignKeyError,
-  pgErrorToResourceError
+  PgErrorCode, pgErrorHelper, PostgresCastRequired, PostgresCheckError, PostgresConnectionError,
+  PostgresConstraintError, PostgresDeadlockError, PostgresError, PostgresForeignKeyError
 } from '@owlmeans/postgres-resource'
 
+const { describePgError, pgErrorToResourceError } = pgErrorHelper
+
 interface DriverShape {
   code: string
   message?: string

package/tests/name.spec.ts

@@ -1,11 +1,13 @@
 import { describe, expect, test } from 'bun:test'
 import type { DbConfig, ResourceRecord } from '@owlmeans/resource'
 
-import {
-  advisoryKey, assertSqlIdentifier, pgIdentifier, pgTableName, qualify, quoteIdent, quoteLiteral
-} from '@owlmeans/postgres-resource'
+import { pgNameHelper } from '@owlmeans/postgres-resource'
 import type { PostgresResource } from '@owlmeans/postgres-resource'
 
+const {
+  advisoryKey, assertSqlIdentifier, pgIdentifier, pgTableName, qualify, quoteIdent, quoteLiteral
+} = pgNameHelper
+
 const resource = (alias: string, name?: string): PostgresResource<ResourceRecord> =>
   ({ alias, ...(name != null ? { name } : {}) }) as PostgresResource<ResourceRecord>
 

package/tests/schema.spec.ts

@@ -2,9 +2,11 @@ import { describe, expect, test } from 'bun:test'
 import { UnsupportedArgumentError } from '@owlmeans/resource'
 import type { AnySchema } from 'ajv'
 
-import { schemaToTableSpec, toFormatType } from '@owlmeans/postgres-resource'
+import { pgSchemaHelper } from '@owlmeans/postgres-resource'
 import type { TableSpec } from '@owlmeans/postgres-resource'
 
+const { schemaToTableSpec, toFormatType } = pgSchemaHelper
+
 /**
  * Compiling an AJV schema into a table specification is the one step every other part of
  * the package trusts: DDL emission, drift detection, marshalling and placeholder

package/tests/sql.spec.ts

@@ -1,13 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 import type { BasicContext } from '@owlmeans/context'
 
-import {
-  PostgresPlaceholderError, refOf, resolvePlaceholders, schemaToTableSpec
-} from '@owlmeans/postgres-resource'
+import { pgPlaceholdersOf, pgSchemaHelper, PostgresPlaceholderError } from '@owlmeans/postgres-resource'
 import type { TableSpec } from '@owlmeans/postgres-resource'
 
 const specOf = (alias: string, schema: string, table: string): TableSpec =>
-  schemaToTableSpec(alias, {
+  pgSchemaHelper.schemaToTableSpec(alias, {
     type: 'object',
     properties: {
       id: { type: 'string', format: 'uuid' },
@@ -37,47 +35,47 @@ const context = contextOf({ users, posts })
 
 describe('@owlmeans/postgres-resource — placeholder resolution', () => {
   test('resolves the owning resource', () => {
-    expect(resolvePlaceholders('SELECT * FROM {{}}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{}}', posts))
       .toBe('SELECT * FROM "app"."posts"')
-    expect(resolvePlaceholders('SELECT * FROM {{ self }}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{ self }}', posts))
       .toBe('SELECT * FROM "app"."posts"')
   })
 
   test('resolves another registered resource, its columns, its bare name and its schema', () => {
-    expect(resolvePlaceholders('SELECT * FROM {{users}}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{users}}', posts))
       .toBe('SELECT * FROM "app"."users"')
     /** The physical column, not the property — a `pg: { column }` rename has to survive. */
-    expect(resolvePlaceholders('SELECT {{users.email}}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SELECT {{users.email}}', posts))
       .toBe('SELECT "app"."users"."email_address"')
-    expect(resolvePlaceholders('ON CONSTRAINT {{#users}}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('ON CONSTRAINT {{#users}}', posts))
       .toBe('ON CONSTRAINT "users"')
-    expect(resolvePlaceholders('SET search_path = {{$}}', context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SET search_path = {{$}}', posts))
       .toBe('SET search_path = "app"')
   })
 
   test('leaves bound parameters exactly as written', () => {
     const text = `SELECT * FROM {{}} WHERE "id" = $1 AND "email" = $2 AND note = '{{not-a-placeholder'`
-    expect(resolvePlaceholders(text, context, posts))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders(text, posts))
       .toBe(`SELECT * FROM "app"."posts" WHERE "id" = $1 AND "email" = $2 AND note = '{{not-a-placeholder'`)
   })
 
   test('refuses an alias it cannot resolve rather than substituting blindly', () => {
-    expect(() => resolvePlaceholders('SELECT * FROM {{nope}}', context, posts))
+    expect(() => pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{nope}}', posts))
       .toThrow(PostgresPlaceholderError)
-    expect(() => resolvePlaceholders('SELECT {{users.nope}}', context, posts))
+    expect(() => pgPlaceholdersOf(context).resolvePlaceholders('SELECT {{users.nope}}', posts))
       .toThrow(PostgresPlaceholderError)
     /** Registered but not yet initialized: the table name genuinely isn't known. */
-    expect(() => resolvePlaceholders('SELECT * FROM {{late}}', contextOf({ late: null }), posts))
+    expect(() => pgPlaceholdersOf(contextOf({ late: null })).resolvePlaceholders('SELECT * FROM {{late}}', posts))
       .toThrow(PostgresPlaceholderError)
   })
 
   test('refuses a self reference in a query that has no owning resource', () => {
-    expect(() => resolvePlaceholders('SELECT * FROM {{}}', context, null))
+    expect(() => pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{}}', null))
       .toThrow(PostgresPlaceholderError)
-    expect(() => resolvePlaceholders('SET search_path = {{$}}', context, null))
+    expect(() => pgPlaceholdersOf(context).resolvePlaceholders('SET search_path = {{$}}', null))
       .toThrow(PostgresPlaceholderError)
     /** Other aliases stay addressable — a service level query is scopeless, not blind. */
-    expect(resolvePlaceholders('SELECT * FROM {{users}}', context, null))
+    expect(pgPlaceholdersOf(context).resolvePlaceholders('SELECT * FROM {{users}}', null))
       .toBe('SELECT * FROM "app"."users"')
   })
 
@@ -91,15 +89,15 @@ describe('@owlmeans/postgres-resource — placeholder resolution', () => {
     const tenantA = contextOf({ users: specOf('users', 'tenant_a', 'users') })
     const tenantB = contextOf({ users: specOf('users', 'tenant_b', 'users') })
 
-    expect(resolvePlaceholders('SELECT * FROM {{users}}', tenantA, null))
+    expect(pgPlaceholdersOf(tenantA).resolvePlaceholders('SELECT * FROM {{users}}', null))
       .toBe('SELECT * FROM "tenant_a"."users"')
-    expect(resolvePlaceholders('SELECT * FROM {{users}}', tenantB, null))
+    expect(pgPlaceholdersOf(tenantB).resolvePlaceholders('SELECT * FROM {{users}}', null))
       .toBe('SELECT * FROM "tenant_b"."users"')
   })
 
   test('refOf answers the same question without any SQL around it', () => {
-    expect(refOf(context, posts)).toBe('"app"."posts"')
-    expect(refOf(context, posts, 'users')).toBe('"app"."users"')
-    expect(() => refOf(context, null)).toThrow(PostgresPlaceholderError)
+    expect(pgPlaceholdersOf(context).refOf(posts)).toBe('"app"."posts"')
+    expect(pgPlaceholdersOf(context).refOf(posts, 'users')).toBe('"app"."users"')
+    expect(() => pgPlaceholdersOf(context).refOf(null)).toThrow(PostgresPlaceholderError)
   })
 })