pipework 0.251.0 → 0.252.1

package/src/data/migrate/snapshot.ts

@@ -0,0 +1,368 @@
+import { randomUUID } from 'node:crypto'
+import { is } from '../query/entity.js'
+import { SQL } from '../query/sql/sql.js'
+import { isExternal } from '../domain/external-registry.js'
+import { PgTable } from '../query/pg-core/table.js'
+import { Table, Schema } from '../query/table.js'
+import { getTableConfig } from '../query/pg-core/utils.js'
+import { CasingCache } from '../query/casing.js'
+import { Column } from '../query/column.js'
+import type { IndexedColumn } from '../query/pg-core/columns/common.js'
+import { camelToSnake } from '../domain/naming.js'
+import type { DefineOptions } from '../domain/types.js'
+
+export interface PwSnapshot {
+  version: 'pw1'
+  id: string
+  prevId: string
+  tables: Record<string, PwTableSnapshot>
+  /** Cross-tenant read doors with a generated policy; absent in snapshots written before doors existed. */
+  doors?: Record<string, { table: string; role: string; ops?: readonly ('select' | 'update' | 'delete')[] }>
+}
+
+export interface PwTableSnapshot {
+  name: string
+  schema: string
+  columns: Record<string, PwColumnSnapshot>
+  indexes: Record<string, PwIndexSnapshot>
+  foreignKeys: Record<string, PwForeignKeySnapshot>
+  checks: Record<string, PwCheckSnapshot>
+  uniqueConstraints: Record<string, PwUniqueSnapshot>
+  compositePrimaryKeys: Record<string, PwCompositePKSnapshot>
+  partitionBy: PwPartitionSnapshot | undefined
+}
+
+export interface PwPartitionSnapshot {
+  strategy: 'range'
+  /** Column name (snake_case), already projected from the field key. */
+  column: string
+}
+
+export interface PwColumnSnapshot {
+  name: string
+  type: string
+  primaryKey: boolean
+  notNull: boolean
+  default: string | undefined
+  isUnique: boolean
+  uniqueName: string | undefined
+  generated: { as: string; type: 'always' } | undefined
+  /** Quoted SQL text (`"C"`); absent when the column uses the database default collation. */
+  collation?: string | undefined
+  identity: { type: 'always' | 'byDefault'; name: string | undefined; options: PwSequenceOptions | undefined } | undefined
+}
+
+export interface PwSequenceOptions {
+  increment: string | undefined
+  minValue: string | undefined
+  maxValue: string | undefined
+  startWith: string | undefined
+  cache: string | undefined
+  cycle: boolean | undefined
+}
+
+export interface PwIndexSnapshot {
+  name: string
+  columns: PwIndexColumnSnapshot[]
+  unique: boolean
+  method: string
+  where: string | undefined
+  concurrently: boolean
+  with: Record<string, unknown> | undefined
+  /** Present (true) only for a NULLS NOT DISTINCT unique index, so stored snapshots stay unchanged. */
+  nullsNotDistinct?: boolean
+  /** Covering (INCLUDE) column names in order; absent when none, so stored snapshots stay unchanged. */
+  include?: string[]
+}
+
+export interface PwIndexColumnSnapshot {
+  expression: string
+  isExpression: boolean
+  order: string | undefined
+  nulls: string | undefined
+  opClass: string | undefined
+  /** Quoted SQL text; absent when the column uses the default collation. */
+  collation?: string | undefined
+}
+
+export interface PwForeignKeySnapshot {
+  name: string
+  columns: string[]
+  foreignTable: string
+  foreignSchema: string
+  foreignColumns: string[]
+  onUpdate: string | undefined
+  onDelete: string | undefined
+  /** Database names cleared by ON DELETE SET NULL / SET DEFAULT (Postgres 15+); absent for the whole key. */
+  onDeleteColumns?: string[]
+}
+
+export interface PwCheckSnapshot {
+  name: string
+  value: string
+}
+
+export interface PwUniqueSnapshot {
+  name: string
+  columns: string[]
+  nullsNotDistinct: boolean
+}
+
+export interface PwCompositePKSnapshot {
+  name: string
+  columns: string[]
+}
+
+export const EMPTY_SNAPSHOT: PwSnapshot = {
+  version: 'pw1',
+  id: '00000000-0000-0000-0000-000000000000',
+  prevId: '',
+  tables: {},
+}
+
+const sqlBuildConfig = {
+  casing: new CasingCache(),
+  escapeName: (name: string) => `"${name}"`,
+  escapeParam: (_num: number, value: unknown) => `${typeof value === 'string' ? `'${value}'` : value}`,
+  escapeString: (str: string) => `'${str.replace(/'/g, "''")}'`,
+  inlineParams: true,
+}
+
+export function serializeSQL(value: SQL): string {
+  return value.toQuery(sqlBuildConfig).sql
+}
+
+export function serializeDefault(column: Column): string | undefined {
+  if (column.default === undefined) return undefined
+  if (is(column.default, SQL)) {
+    return serializeSQL(column.default as SQL)
+  }
+  if (typeof column.default === 'string') return `'${column.default.replace(/'/g, "''")}'`
+  if (typeof column.default === 'number' || typeof column.default === 'bigint') return String(column.default)
+  if (typeof column.default === 'boolean') return column.default ? 'true' : 'false'
+  if (typeof column.default === 'object' && column.default !== null) {
+    const jsonStr = JSON.stringify(column.default).replace(/'/g, "''")
+    const sqlType = column.getSQLType()
+    if (sqlType === 'jsonb' || sqlType === 'json') {
+      return `'${jsonStr}'::${sqlType}`
+    }
+    return `'${jsonStr}'`
+  }
+  return String(column.default)
+}
+
+function tableKey(schema: string, name: string): string {
+  return `${schema}.${name}`
+}
+
+function indexName(tableName: string, columns: PwIndexColumnSnapshot[], unique: boolean): string {
+  const colPart = columns.map(c => c.expression).join('_')
+  const suffix = unique ? '_unique' : '_index'
+  return `${tableName}_${colPart}${suffix}`
+}
+
+export function buildSnapshot(
+  imports: Record<string, unknown>,
+  prevId: string,
+): PwSnapshot {
+  const tables: Record<string, PwTableSnapshot> = {}
+
+  for (const value of Object.values(imports)) {
+    if (!is(value, PgTable)) continue
+    if (isExternal(value)) continue
+
+    const config = getTableConfig(value)
+    const schema = config.schema ?? 'public'
+    const key = tableKey(schema, config.name)
+
+    const columns: Record<string, PwColumnSnapshot> = {}
+    for (const col of config.columns) {
+      columns[col.name] = {
+        name: col.name,
+        type: col.getSQLType(),
+        primaryKey: col.primary,
+        notNull: col.notNull,
+        default: serializeDefault(col),
+        isUnique: col.isUnique,
+        uniqueName: col.uniqueName,
+        ...(col.collation !== undefined ? { collation: col.collation } : {}),
+        generated: col.generated !== undefined
+          ? { as: serializeGenerated(col.generated.as), type: 'always' }
+          : undefined,
+        identity: col.generatedIdentity !== undefined
+          ? {
+            type: col.generatedIdentity.type,
+            name: col.generatedIdentity.sequenceName,
+            options: col.generatedIdentity.sequenceOptions !== undefined
+              ? serializeSequenceOptions(col.generatedIdentity.sequenceOptions)
+              : undefined,
+          }
+          : undefined,
+      }
+    }
+
+    const indexes: Record<string, PwIndexSnapshot> = {}
+    for (const idx of config.indexes) {
+      const method = idx.config.method ?? 'btree'
+      const idxColumns = serializeIndexColumns(idx.config.columns, method)
+      const name = idx.config.name ?? indexName(config.name, idxColumns, idx.config.unique)
+      indexes[name] = {
+        name,
+        columns: idxColumns,
+        unique: idx.config.unique,
+        method,
+        where: idx.config.where !== undefined ? serializeSQL(idx.config.where) : undefined,
+        concurrently: idx.config.concurrently ?? false,
+        with: idx.config.with,
+        ...(idx.config.nullsNotDistinct === true ? { nullsNotDistinct: true } : {}),
+        ...(idx.config.include !== undefined && idx.config.include.length > 0 ? { include: idx.config.include } : {}),
+      }
+    }
+
+    const foreignKeys: Record<string, PwForeignKeySnapshot> = {}
+    for (const fk of config.foreignKeys) {
+      const ref = fk.reference()
+      const name = fk.getName()
+      const fkSchema = ref.foreignTable[Schema as typeof Table.Symbol.Schema] ?? 'public'
+      foreignKeys[name] = {
+        name,
+        columns: ref.columns.map(c => c.name),
+        foreignTable: ref.foreignTable[Table.Symbol.Name],
+        foreignSchema: fkSchema as string,
+        foreignColumns: ref.foreignColumns.map(c => c.name),
+        onUpdate: fk.onUpdate,
+        onDelete: fk.onDelete,
+        ...(fk.onDeleteColumns !== undefined ? { onDeleteColumns: [...fk.onDeleteColumns] } : {}),
+      }
+    }
+
+    const checks: Record<string, PwCheckSnapshot> = {}
+    for (const chk of config.checks) {
+      checks[chk.name] = {
+        name: chk.name,
+        value: serializeSQL(chk.value),
+      }
+    }
+
+    const uniqueConstraints: Record<string, PwUniqueSnapshot> = {}
+    for (const uc of config.uniqueConstraints) {
+      const ucName = uc.name ?? `${config.name}_${uc.columns.map(c => c.name).join('_')}_unique`
+      uniqueConstraints[ucName] = {
+        name: ucName,
+        columns: uc.columns.map(c => c.name),
+        nullsNotDistinct: uc.nullsNotDistinct,
+      }
+    }
+
+    const compositePrimaryKeys: Record<string, PwCompositePKSnapshot> = {}
+    for (const pk of config.primaryKeys) {
+      const name = pk.getName()
+      compositePrimaryKeys[name] = {
+        name,
+        columns: pk.columns.map(c => c.name),
+      }
+    }
+
+    tables[key] = {
+      name: config.name,
+      schema,
+      columns,
+      indexes,
+      foreignKeys,
+      checks,
+      uniqueConstraints,
+      compositePrimaryKeys,
+      partitionBy: readPartition(value),
+    }
+  }
+
+  return {
+    version: 'pw1',
+    id: randomUUID(),
+    prevId,
+    tables,
+  }
+}
+
+/**
+ * Reads partition metadata off a definition. Partitioning is a `pipe.define()`
+ * concept Drizzle has no model for, so it rides on the DefinedTable's `$options`
+ * rather than the Drizzle table config.
+ */
+function readPartition(value: unknown): PwPartitionSnapshot | undefined {
+  const options = (value as { $options?: DefineOptions }).$options
+  if (options?.partitionBy === undefined) return undefined
+  return {
+    strategy: options.partitionBy.strategy,
+    column: camelToSnake(options.partitionBy.column),
+  }
+}
+
+function serializeGenerated(as: unknown): string {
+  if (is(as, SQL)) return serializeSQL(as)
+  if (typeof as === 'function') {
+    const result: unknown = as()
+    if (is(result, SQL)) return serializeSQL(result)
+    return String(result)
+  }
+  return String(as)
+}
+
+function serializeSequenceOptions(opts: {
+  increment?: number | string | undefined
+  minValue?: number | string | undefined
+  maxValue?: number | string | undefined
+  startWith?: number | string | undefined
+  cache?: number | string | undefined
+  cycle?: boolean | undefined
+}): PwSequenceOptions {
+  return {
+    increment: opts.increment !== undefined ? String(opts.increment) : undefined,
+    minValue: opts.minValue !== undefined ? String(opts.minValue) : undefined,
+    maxValue: opts.maxValue !== undefined ? String(opts.maxValue) : undefined,
+    startWith: opts.startWith !== undefined ? String(opts.startWith) : undefined,
+    cache: opts.cache !== undefined ? String(opts.cache) : undefined,
+    cycle: opts.cycle,
+  }
+}
+
+const vectorOpClassDefaults: Record<string, string> = {
+  PgVector: 'vector_cosine_ops',
+  PgHalfVector: 'halfvec_cosine_ops',
+  PgBinaryVector: 'bit_hamming_ops',
+  PgSparseVector: 'sparsevec_cosine_ops',
+}
+
+function serializeIndexColumns(columns: Partial<IndexedColumn | SQL>[], method: string): PwIndexColumnSnapshot[] {
+  const needsOpClass = method === 'hnsw' || method === 'ivfflat'
+
+  return columns.map(col => {
+    if (is(col, SQL)) {
+      return {
+        expression: serializeSQL(col),
+        isExpression: true,
+        order: undefined,
+        nulls: undefined,
+        opClass: undefined,
+      }
+    }
+    const indexed = col as IndexedColumn
+    let opClass = indexed.indexConfig.opClass
+    if (opClass === undefined && needsOpClass) {
+      opClass = vectorOpClassDefaults[indexed.type]
+    }
+    // Only btree supports ASC/DESC/NULLS ordering — on every other access
+    // method (gin, gist, hash, brin, hnsw, ...) it is a syntax error. Drizzle
+    // defaults every index column to order 'asc' / nulls 'last', so non-btree
+    // indexes must drop them explicitly.
+    const ordered = method === 'btree'
+    return {
+      expression: indexed.name ?? '',
+      isExpression: false,
+      order: ordered ? indexed.indexConfig.order : undefined,
+      nulls: ordered ? indexed.indexConfig.nulls : undefined,
+      opClass,
+      ...(indexed.indexConfig.collation !== undefined ? { collation: indexed.indexConfig.collation } : {}),
+    }
+  })
+}