pipework 0.279.0 → 0.281.0

package/src/async/jobs/serialize-error.ts

@@ -18,7 +18,8 @@ const DROPPED_KEYS = new Set(['params', 'parameters', 'args', 'types'])
 const MAX_QUERY_CHARS = 2_000
 const MAX_STRING_CHARS = 4_000
 
-function cut(text: string, max: number): string {
+/** Cuts `text` to `max` characters, ending `…[truncated N chars]` when it was longer. */
+export function cutText(text: string, max: number): string {
   return text.length <= max ? text : `${text.slice(0, max)}…[truncated ${String(text.length - max)} chars]`
 }
 
@@ -33,13 +34,13 @@ function serialize(value: unknown, seen: Set<Error>): unknown {
   const stack = typeof value.stack === 'string' && paramsAt !== -1 ? value.stack.replace(value.message, message) : value.stack
   const out: Record<string, unknown> = {
     name: value.name,
-    message: cut(message, MAX_STRING_CHARS),
-    stack: typeof stack === 'string' ? cut(stack, MAX_STRING_CHARS) : stack,
+    message: cutText(message, MAX_STRING_CHARS),
+    stack: typeof stack === 'string' ? cutText(stack, MAX_STRING_CHARS) : stack,
   }
   for (const key of Object.keys(value)) {
     if (key === 'name' || key === 'message' || key === 'stack' || key === 'cause' || DROPPED_KEYS.has(key)) continue
     const v = (value as unknown as Record<string, unknown>)[key]
-    out[key] = typeof v === 'string' ? cut(v, key === 'query' ? MAX_QUERY_CHARS : MAX_STRING_CHARS) : v
+    out[key] = typeof v === 'string' ? cutText(v, key === 'query' ? MAX_QUERY_CHARS : MAX_STRING_CHARS) : v
   }
   if (value.cause !== undefined) {
     out['cause'] = serialize(value.cause, seen)

package/src/cli/commands/migrate.ts

@@ -1,5 +1,5 @@
-import { info, success, error as logError, warn } from '../output.js'
-import type { MigrateResult } from '../../data/migrate/run.js'
+import { info, success, error as logError, warn, yellow, cyan } from '../output.js'
+import type { MigrateResult, MigrateNotice } from '../../data/migrate/run.js'
 import { frameworkTablesChanged } from '../../data/migrate/provision-framework.js'
 
 export interface MigrateCommandOptions {
@@ -44,7 +44,7 @@ export async function migrate(options: MigrateCommandOptions): Promise<void> {
     warn('Running migrations against PRODUCTION database.')
   }
 
-  const migrateOptions = {}
+  const migrateOptions = { onNotice: printNotice }
 
   try {
     if (options.db !== undefined) {
@@ -130,3 +130,18 @@ function reportFrameworkTables(result: MigrateResult): void {
     `${f.partitionsCreated.length} day partitions created`,
   )
 }
+
+/** One notice or warning a migration statement raised, indented under its database. Issue #970. */
+export function formatNotice(n: MigrateNotice): string {
+  const label = n.severity === 'NOTICE' || n.severity === 'INFO' || n.severity === 'LOG' || n.severity === 'DEBUG'
+    ? cyan(n.severity)
+    : yellow(n.severity)
+  let out = `  ${label}  ${n.tag} (statement ${n.statement}/${n.statements}): ${n.message}\n`
+  if (n.detail !== undefined) out += `    DETAIL: ${n.detail}\n`
+  if (n.hint !== undefined) out += `    HINT: ${n.hint}\n`
+  return out
+}
+
+export function printNotice(n: MigrateNotice): void {
+  process.stderr.write(formatNotice(n))
+}

package/src/data/migrate/apply.ts

@@ -7,6 +7,14 @@ import { listMigrations } from './history.js'
 
 const NO_TRANSACTION_PRAGMA = '-- pipework:no-transaction'
 
+/** A NOTICE or WARNING (or other non-error message) a migration statement raised. */
+export interface MigrationNotice {
+  severity: string
+  message: string
+  detail?: string
+  hint?: string
+}
+
 export interface ApplyOptions {
   migrationsFolder: string
   migrationsTable: string
@@ -44,6 +52,12 @@ export interface ApplyOptions {
    * Issue #378.
    */
   onResume?: (tag: string, fromStatement: number, total: number) => void
+  /**
+   * Called for each notice or warning a migration file's own statement raises,
+   * with the file's tag, the 1-based statement and the file's statement count.
+   * The runner's own bookkeeping statements never reach it. Issue #970.
+   */
+  onNotice?: (tag: string, statement: number, statements: number, notice: MigrationNotice) => void
 }
 
 export interface Migration {
@@ -60,7 +74,28 @@ export async function applyMigrations(options: ApplyOptions): Promise<number> {
   const migrations = readMigrations(options)
   if (migrations.length === 0) return 0
 
-  const client = postgres(options.connectionUrl, { max: 1, onnotice: () => {} })
+  // Set only while a statement from a migration file runs; the runner's own
+  // bookkeeping raises "already exists, skipping" notices that are not the
+  // migration's and are dropped.
+  let current: { tag: string; statement: number; statements: number } | undefined
+  const client = postgres(options.connectionUrl, {
+    max: 1,
+    onnotice: (n) => {
+      if (current === undefined || options.onNotice === undefined) return
+      const notice: MigrationNotice = { severity: String(n['severity']), message: String(n['message']) }
+      if (typeof n['detail'] === 'string') notice.detail = n['detail']
+      if (typeof n['hint'] === 'string') notice.hint = n['hint']
+      options.onNotice(current.tag, current.statement, current.statements, notice)
+    },
+  })
+  const inStatement = async <T>(tag: string, statement: number, statements: number, run: () => Promise<T>): Promise<T> => {
+    current = { tag, statement, statements }
+    try {
+      return await run()
+    } finally {
+      current = undefined
+    }
+  }
 
   try {
     const table = quoteIdent(options.migrationsTable)
@@ -158,7 +193,7 @@ export async function applyMigrations(options: ApplyOptions): Promise<number> {
         if (from > 0) options.onResume?.(migration.tag, from + 1, migration.statements.length)
 
         for (let i = from; i < migration.statements.length; i++) {
-          await client.unsafe(migration.statements[i]!)
+          await inStatement(migration.tag, i + 1, migration.statements.length, () => client.unsafe(migration.statements[i]!))
           // Recorded AFTER the statement it describes: marking first would let
           // a death between the mark and the statement skip work silently,
           // which is worse than replaying one statement. The window that
@@ -179,7 +214,7 @@ export async function applyMigrations(options: ApplyOptions): Promise<number> {
       } else {
         await client.begin(async (tx) => {
           for (const [i, stmt] of migration.statements.entries()) {
-            await tx.unsafe(stmt)
+            await inStatement(migration.tag, i + 1, migration.statements.length, () => tx.unsafe(stmt))
             options.onStatement?.(migration.tag, i + 1, migration.statements.length, applied + 1, migrations.length)
           }
           await tx.unsafe(

package/src/data/migrate/run.ts

@@ -5,14 +5,17 @@ import { quoteIdentifier } from '../db/identifiers.js'
 import { OWNER_LABEL_MIGRATE } from '../db/owner-labels.js'
 import { checkMigrations, type MigrationCheckResult } from './check.js'
 import { readAppliedState } from './applied.js'
-import { applyMigrations } from './apply.js'
+import { applyMigrations, type MigrationNotice } from './apply.js'
 import { provisionFrameworkTables, type FrameworkTablesResult } from './provision-framework.js'
 
 // Deliberately empty of hazard switches. Authorization for a hazardous
 // migration is declared in that migration's own file (see pragma.ts) — an
 // option here would be an invocation-level approval, which is exactly the
 // thing that gets written into a deploy workflow once and never revisited.
-export interface MigrateOptions {}
+export interface MigrateOptions {
+  /** Called as each notice or warning a migration statement raises arrives. Issue #970. */
+  onNotice?: (notice: MigrateNotice) => void
+}
 
 export interface MigrateResult {
   database: string
@@ -21,6 +24,8 @@ export interface MigrateResult {
   safetyCheck: MigrationCheckResult
   /** No-transaction files picked up half applied and finished. Issue #378. */
   resumed: ResumedMigration[]
+  /** Notices and warnings raised by migration statements, in arrival order. Issue #970. */
+  notices: MigrateNotice[]
   /** Trace/audit tables, columns and day partitions this run provisioned. */
   frameworkTables: FrameworkTablesResult
 }
@@ -32,6 +37,13 @@ export interface ResumedMigration {
   totalStatements: number
 }
 
+export interface MigrateNotice extends MigrationNotice {
+  tag: string
+  /** 1-based statement within the file. */
+  statement: number
+  statements: number
+}
+
 export class UnsafeMigrationError extends Error {
   override readonly name = 'UnsafeMigrationError'
   constructor(
@@ -54,7 +66,7 @@ export async function migrateAll(instance: Manifold, options: MigrateOptions = {
   return results
 }
 
-export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase, _options: MigrateOptions = {}): Promise<MigrateResult> {
+export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase, options: MigrateOptions = {}): Promise<MigrateResult> {
   const conn = instance.pool.getOrCreate(dbConfig, 'owner', OWNER_LABEL_MIGRATE)
 
   // Scope the safety gate to pending migrations only — hazards in already-applied
@@ -87,11 +99,17 @@ export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase,
   }
 
   const resumed: ResumedMigration[] = []
+  const notices: MigrateNotice[] = []
   const migrationsRun = await applyMigrations({
     migrationsFolder: dbConfig.migrations!,
     migrationsTable: dbConfig.migrationTable,
     connectionUrl: dbConfig.url,
     onResume: (tag, fromStatement, totalStatements) => resumed.push({ tag, fromStatement, totalStatements }),
+    onNotice: (tag, statement, statements, notice) => {
+      const full: MigrateNotice = { tag, statement, statements, ...notice }
+      notices.push(full)
+      options.onNotice?.(full)
+    },
   })
 
   // Trace and audit storage rides the default database; their partitioned
@@ -115,6 +133,7 @@ export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase,
     extensions: extensionsCreated,
     safetyCheck,
     resumed,
+    notices,
     frameworkTables,
   }
 }

package/src/index.ts

@@ -83,7 +83,7 @@ export type { AuditChainHead, AuditChainBreak, AuditChainBreakReason, AuditVerif
 export { jobs } from './async/jobs/namespace.js'
 export { JobAbortedError, JobLaterError, JobPermanentError } from './async/jobs/index.js'
 export { serializeError } from './async/jobs/serialize-error.js'
-export type { ExecuteJobOptions, Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobClaim, JobClaimReason, ReapedJob, FailedAttempt, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig,
+export type { ExecuteJobOptions, Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobClaim, JobClaimReason, ReapedJob, FailedAttempt, FailOptions, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig,
   WaitOptions, WaitResult, ListenClient, ListenHandle, CronSchedule, ScheduleSpec,
   ScheduleInfo, SchedulerOptions } from './async/jobs/index.js'