@owlmeans/postgres-resource 0.1.18-rc.42 → 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,94 +1,88 @@
 import { logger } from '@owlmeans/log'
 import type { PoolClient } from 'pg'
 
-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'
 
 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) {
-        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' })
+      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/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',

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