pipework 0.252.0 → 0.252.1

package/src/data/migrate/sql-emit.ts

@@ -0,0 +1,392 @@
+import type {
+  DiffOp,
+} from './diff.js'
+import type {
+  PwTableSnapshot,
+  PwColumnSnapshot,
+  PwIndexSnapshot,
+  PwForeignKeySnapshot,
+  PwUniqueSnapshot,
+  PwCompositePKSnapshot,
+  PwSequenceOptions,
+} from './snapshot.js'
+
+function q(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+function qualifiedTable(schema: string, name: string): string {
+  if (schema === 'public') return q(name)
+  return `${q(schema)}.${q(name)}`
+}
+
+/**
+ * Every op type except the two `emitSQL` routes itself: `create_table` (whose
+ * foreign keys are hoisted out) and `add_foreign_key`. Issue #312.
+ */
+type InlineOp = Exclude<DiffOp, { type: 'create_table' } | { type: 'add_foreign_key' }>
+
+export function emitSQL(ops: DiffOp[]): string[] {
+  // Foreign keys are hoisted to run after every CREATE TABLE. A from-scratch
+  // baseline creates many tables in one migration; an FK ALTER emitted next to
+  // its own CREATE TABLE fails when it references a table created further down.
+  // Collecting every FK statement and appending them keeps all referenced
+  // tables in place before any constraint is added. Issue #312.
+  const tables: string[] = []
+  const foreignKeys: string[] = []
+  for (const op of ops) {
+    if (op.type === 'create_table') {
+      tables.push(...emitCreateTable(op.table))
+      const partitioned = op.table.partitionBy !== undefined
+      for (const fk of Object.values(op.table.foreignKeys)) {
+        foreignKeys.push(...emitAddForeignKey(op.table.name, op.table.schema, fk, partitioned))
+      }
+    } else if (op.type === 'add_foreign_key') {
+      foreignKeys.push(...emitAddForeignKey(op.tableName, op.tableSchema, op.fk, op.tablePartitioned))
+    } else {
+      tables.push(...emitOp(op))
+    }
+  }
+  return [...tables, ...foreignKeys]
+}
+
+function emitOp(op: InlineOp): string[] {
+  switch (op.type) {
+    case 'drop_table': return emitDropTable(op.table)
+    case 'add_column': return [emitAddColumn(op.tableName, op.tableSchema, op.column)]
+    case 'drop_column': return [emitDropColumn(op.tableName, op.tableSchema, op.column.name)]
+    case 'alter_column_type': return [emitAlterColumnType(op.tableName, op.tableSchema, op.column, op.to, op.collation)]
+    case 'alter_column_set_not_null': return [emitAlterColumnSetNotNull(op.tableName, op.tableSchema, op.column)]
+    case 'alter_column_drop_not_null': return [emitAlterColumnDropNotNull(op.tableName, op.tableSchema, op.column)]
+    case 'alter_column_set_default': return [emitAlterColumnSetDefault(op.tableName, op.tableSchema, op.column, op.value)]
+    case 'alter_column_drop_default': return [emitAlterColumnDropDefault(op.tableName, op.tableSchema, op.column)]
+    case 'alter_column_set_generated': return emitAlterColumnSetGenerated(op.tableName, op.tableSchema, op.column)
+    case 'alter_column_drop_generated': return [emitAlterColumnDropGenerated(op.tableName, op.tableSchema, op.column)]
+    case 'alter_column_set_identity': return [emitAlterColumnSetIdentity(op.tableName, op.tableSchema, op.column)]
+    case 'alter_column_drop_identity': return [emitAlterColumnDropIdentity(op.tableName, op.tableSchema, op.column)]
+    case 'create_index': return [emitCreateIndex(op.tableName, op.tableSchema, op.index)]
+    case 'drop_index': return [emitDropIndex(op.tableSchema, op.index)]
+    case 'replace_index': return emitReplaceIndex(op.tableName, op.tableSchema, op.from, op.to)
+    case 'drop_foreign_key': return [emitDropForeignKey(op.tableName, op.tableSchema, op.fk.name)]
+    case 'add_check': return [emitAddCheck(op.tableName, op.tableSchema, op.check.name, op.check.value)]
+    case 'drop_check': return [emitDropConstraint(op.tableName, op.tableSchema, op.check.name)]
+    case 'add_unique': return emitAddUnique(op.tableName, op.tableSchema, op.unique, op.tablePartitioned)
+    case 'replace_unique': return emitReplaceUnique(op.tableName, op.tableSchema, op.from, op.to, op.tablePartitioned)
+    case 'drop_unique': return [emitDropConstraint(op.tableName, op.tableSchema, op.unique.name)]
+    case 'add_composite_pk': return emitAddCompositePK(op.tableName, op.tableSchema, op.pk, op.tablePartitioned)
+    case 'replace_composite_pk': return emitReplaceCompositePK(op.tableName, op.tableSchema, op.from, op.to, op.tablePartitioned)
+    case 'drop_composite_pk': return [emitDropConstraint(op.tableName, op.tableSchema, op.pk.name)]
+  }
+}
+
+function emitCreateTable(table: PwTableSnapshot): string[] {
+  const tbl = qualifiedTable(table.schema, table.name)
+  const colDefs: string[] = []
+
+  for (const col of Object.values(table.columns)) {
+    colDefs.push(columnDef(col))
+  }
+
+  for (const pk of Object.values(table.compositePrimaryKeys)) {
+    colDefs.push(`CONSTRAINT ${q(pk.name)} PRIMARY KEY(${pk.columns.map(q).join(', ')})`)
+  }
+
+  for (const uc of Object.values(table.uniqueConstraints)) {
+    const nd = uc.nullsNotDistinct ? ' NULLS NOT DISTINCT' : ''
+    colDefs.push(`CONSTRAINT ${q(uc.name)} UNIQUE${nd}(${uc.columns.map(q).join(', ')})`)
+  }
+
+  for (const chk of Object.values(table.checks)) {
+    colDefs.push(`CONSTRAINT ${q(chk.name)} CHECK (${chk.value})`)
+  }
+
+  const partitionClause = table.partitionBy !== undefined
+    ? ` PARTITION BY ${table.partitionBy.strategy.toUpperCase()} (${q(table.partitionBy.column)})`
+    : ''
+
+  const statements = [`CREATE TABLE ${tbl} (\n\t${colDefs.join(',\n\t')}\n)${partitionClause}`]
+
+  for (const idx of Object.values(table.indexes)) {
+    statements.push(emitCreateIndex(table.name, table.schema, idx))
+  }
+
+  // Foreign keys are not emitted here — `emitSQL` hoists them after every
+  // CREATE TABLE so forward references resolve. Issue #312.
+  return statements
+}
+
+function columnDef(col: PwColumnSnapshot): string {
+  const parts: string[] = [q(col.name)]
+
+  if (col.identity !== undefined) {
+    const baseType = col.type === 'bigserial' ? 'bigint' : col.type === 'smallserial' ? 'smallint' : col.type === 'serial' ? 'integer' : col.type
+    parts.push(baseType)
+  } else if (col.generated !== undefined) {
+    parts.push(col.type)
+  } else {
+    parts.push(col.type)
+  }
+
+  if (col.collation !== undefined) {
+    parts.push(`COLLATE ${col.collation}`)
+  }
+
+  if (col.primaryKey) {
+    parts.push('PRIMARY KEY')
+  }
+
+  if (col.notNull) {
+    parts.push('NOT NULL')
+  }
+
+  if (col.generated !== undefined) {
+    parts.push(`GENERATED ALWAYS AS (${col.generated.as}) STORED`)
+  } else if (col.identity !== undefined) {
+    const keyword = col.identity.type === 'always' ? 'ALWAYS' : 'BY DEFAULT'
+    const seqOpts = col.identity.options !== undefined ? ` (${formatSequenceOptions(col.identity.options)})` : ''
+    parts.push(`GENERATED ${keyword} AS IDENTITY${seqOpts}`)
+  } else if (col.default !== undefined) {
+    parts.push(`DEFAULT ${col.default}`)
+  }
+
+  if (col.isUnique && col.uniqueName !== undefined) {
+    parts.push(`CONSTRAINT ${q(col.uniqueName)} UNIQUE`)
+  } else if (col.isUnique) {
+    parts.push('UNIQUE')
+  }
+
+  return parts.join(' ')
+}
+
+function formatSequenceOptions(opts: PwSequenceOptions): string {
+  const parts: string[] = []
+  if (opts.increment !== undefined) parts.push(`INCREMENT BY ${opts.increment}`)
+  if (opts.minValue !== undefined) parts.push(`MINVALUE ${opts.minValue}`)
+  if (opts.maxValue !== undefined) parts.push(`MAXVALUE ${opts.maxValue}`)
+  if (opts.startWith !== undefined) parts.push(`START WITH ${opts.startWith}`)
+  if (opts.cache !== undefined) parts.push(`CACHE ${opts.cache}`)
+  if (opts.cycle === true) parts.push('CYCLE')
+  if (opts.cycle === false) parts.push('NO CYCLE')
+  return parts.join(' ')
+}
+
+function emitDropTable(table: PwTableSnapshot): string[] {
+  return [`DROP TABLE ${qualifiedTable(table.schema, table.name)}`]
+}
+
+function emitAddColumn(tableName: string, tableSchema: string, col: PwColumnSnapshot): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ADD COLUMN ${columnDef(col)}`
+}
+
+function emitDropColumn(tableName: string, tableSchema: string, colName: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} DROP COLUMN ${q(colName)}`
+}
+
+function emitAlterColumnType(tableName: string, tableSchema: string, column: string, toType: string, collation?: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} SET DATA TYPE ${toType}${collation !== undefined ? ` COLLATE ${collation}` : ''}`
+}
+
+function emitAlterColumnSetNotNull(tableName: string, tableSchema: string, column: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} SET NOT NULL`
+}
+
+function emitAlterColumnDropNotNull(tableName: string, tableSchema: string, column: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} DROP NOT NULL`
+}
+
+function emitAlterColumnSetDefault(tableName: string, tableSchema: string, column: string, value: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} SET DEFAULT ${value}`
+}
+
+function emitAlterColumnDropDefault(tableName: string, tableSchema: string, column: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} DROP DEFAULT`
+}
+
+function emitAlterColumnSetGenerated(tableName: string, tableSchema: string, col: PwColumnSnapshot): string[] {
+  const tbl = qualifiedTable(tableSchema, tableName)
+  return [
+    `ALTER TABLE ${tbl} ALTER COLUMN ${q(col.name)} ADD GENERATED ALWAYS AS (${col.generated!.as}) STORED`,
+  ]
+}
+
+function emitAlterColumnDropGenerated(tableName: string, tableSchema: string, column: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} DROP EXPRESSION`
+}
+
+function emitAlterColumnSetIdentity(tableName: string, tableSchema: string, col: PwColumnSnapshot): string {
+  const tbl = qualifiedTable(tableSchema, tableName)
+  const keyword = col.identity!.type === 'always' ? 'ALWAYS' : 'BY DEFAULT'
+  const seqOpts = col.identity!.options !== undefined ? ` (${formatSequenceOptions(col.identity!.options)})` : ''
+  return `ALTER TABLE ${tbl} ALTER COLUMN ${q(col.name)} ADD GENERATED ${keyword} AS IDENTITY${seqOpts}`
+}
+
+function emitAlterColumnDropIdentity(tableName: string, tableSchema: string, column: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ALTER COLUMN ${q(column)} DROP IDENTITY`
+}
+
+function emitCreateIndex(tableName: string, tableSchema: string, idx: PwIndexSnapshot): string {
+  const unique = idx.unique ? 'UNIQUE ' : ''
+  const concurrent = idx.concurrently ? 'CONCURRENTLY ' : ''
+  const method = idx.method !== 'btree' ? ` USING ${idx.method}` : ''
+  const tbl = qualifiedTable(tableSchema, tableName)
+
+  const colExprs = idx.columns.map(col => {
+    if (col.isExpression) return col.expression
+    let expr = q(col.expression)
+    if (col.collation !== undefined) expr += ` COLLATE ${col.collation}`
+    // Postgres order: column, COLLATE, operator class, ASC/DESC, NULLS.
+    if (col.opClass !== undefined) expr += ` ${col.opClass}`
+    if (col.order !== undefined) expr += ` ${col.order.toUpperCase()}`
+    if (col.nulls !== undefined) expr += ` NULLS ${col.nulls.toUpperCase()}`
+    return expr
+  })
+
+  // Postgres order: (columns), INCLUDE, NULLS NOT DISTINCT, WITH, WHERE.
+  const include = idx.include !== undefined && idx.include.length > 0
+    ? ` INCLUDE (${idx.include.map(q).join(', ')})`
+    : ''
+  const nullsNotDistinct = idx.nullsNotDistinct === true ? ' NULLS NOT DISTINCT' : ''
+  const withOpts = idx.with !== undefined && Object.keys(idx.with).length > 0
+    ? ` WITH (${Object.entries(idx.with).map(([k, v]) => `${k} = ${String(v)}`).join(', ')})`
+    : ''
+  const where = idx.where !== undefined ? ` WHERE ${idx.where}` : ''
+
+  return `CREATE ${unique}INDEX ${concurrent}${q(idx.name)} ON ${tbl}${method} (${colExprs.join(', ')})${include}${nullsNotDistinct}${withOpts}${where}`
+}
+
+function qualifiedIndex(tableSchema: string, name: string): string {
+  return tableSchema === 'public' ? q(name) : `${q(tableSchema)}.${q(name)}`
+}
+
+function emitDropIndex(tableSchema: string, idx: PwIndexSnapshot): string {
+  return `DROP INDEX ${qualifiedIndex(tableSchema, idx.name)}`
+}
+
+/** Builds the changed index beside the old one, drops the old, renames the new into its place. */
+function emitReplaceIndex(
+  tableName: string,
+  tableSchema: string,
+  from: PwIndexSnapshot,
+  to: PwIndexSnapshot,
+): string[] {
+  const tmp = tempIndexName(to.name)
+  return [
+    dropLeftoverIndex(tableSchema, tmp),
+    emitCreateIndex(tableName, tableSchema, { ...to, name: tmp, concurrently: true }),
+    `DROP INDEX CONCURRENTLY IF EXISTS ${qualifiedIndex(tableSchema, from.name)}`,
+    `ALTER INDEX ${qualifiedIndex(tableSchema, tmp)} RENAME TO ${q(to.name)}`,
+  ]
+}
+
+/** A failed CONCURRENTLY build leaves an INVALID index; clear it so a rerun can build again. */
+function dropLeftoverIndex(tableSchema: string, name: string): string {
+  return `DROP INDEX CONCURRENTLY IF EXISTS ${qualifiedIndex(tableSchema, name)}`
+}
+
+function emitAddForeignKey(
+  tableName: string,
+  tableSchema: string,
+  fk: PwForeignKeySnapshot,
+  tablePartitioned: boolean,
+): string[] {
+  const tbl = qualifiedTable(tableSchema, tableName)
+  const cols = fk.columns.map(q).join(', ')
+  const refTbl = qualifiedTable(fk.foreignSchema, fk.foreignTable)
+  const refCols = fk.foreignColumns.map(q).join(', ')
+  let stmt = `ALTER TABLE ${tbl} ADD CONSTRAINT ${q(fk.name)} FOREIGN KEY (${cols}) REFERENCES ${refTbl}(${refCols})`
+  if (fk.onUpdate !== undefined && fk.onUpdate !== 'no action') {
+    stmt += ` ON UPDATE ${fk.onUpdate.toUpperCase()}`
+  }
+  if (fk.onDelete !== undefined && fk.onDelete !== 'no action') {
+    stmt += ` ON DELETE ${fk.onDelete.toUpperCase()}`
+    if (fk.onDeleteColumns !== undefined) stmt += ` (${fk.onDeleteColumns.map(q).join(', ')})`
+  }
+  // A partitioned table rejects NOT VALID foreign keys — Postgres requires the
+  // constraint be created already valid. For an ordinary table, ADD ... NOT
+  // VALID paired with VALIDATE CONSTRAINT keeps neither statement holding a
+  // lock while it scans a populated table. Issue #312.
+  if (tablePartitioned) return [stmt]
+  return [
+    `${stmt} NOT VALID`,
+    `ALTER TABLE ${tbl} VALIDATE CONSTRAINT ${q(fk.name)}`,
+  ]
+}
+
+function emitDropForeignKey(tableName: string, tableSchema: string, fkName: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} DROP CONSTRAINT ${q(fkName)}`
+}
+
+function emitAddCheck(tableName: string, tableSchema: string, checkName: string, value: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} ADD CONSTRAINT ${q(checkName)} CHECK (${value})`
+}
+
+function emitDropConstraint(tableName: string, tableSchema: string, constraintName: string): string {
+  return `ALTER TABLE ${qualifiedTable(tableSchema, tableName)} DROP CONSTRAINT ${q(constraintName)}`
+}
+
+function tempIndexName(name: string): string {
+  let stem = name
+  while (Buffer.byteLength(stem) > 59) stem = stem.slice(0, -1)
+  return `${stem}_new`
+}
+
+function keyIndex(name: string, columns: string[], nullsNotDistinct: boolean): PwIndexSnapshot {
+  return {
+    name,
+    columns: columns.map(c => ({ expression: c, isExpression: false, order: undefined, nulls: undefined, opClass: undefined })),
+    unique: true,
+    method: 'btree',
+    where: undefined,
+    concurrently: true,
+    with: undefined,
+    ...(nullsNotDistinct ? { nullsNotDistinct: true } : {}),
+  }
+}
+
+/**
+ * A key constraint on a populated table is built as a unique index
+ * CONCURRENTLY, then attached with USING INDEX (a brief lock, no build under
+ * ACCESS EXCLUSIVE). `replaceOld` swaps an existing constraint in the same
+ * statement so uniqueness is never absent. A partitioned table cannot build
+ * concurrently on its parent, so it keeps the plain ADD CONSTRAINT.
+ */
+function emitKeyConstraint(
+  tableName: string,
+  tableSchema: string,
+  kind: 'UNIQUE' | 'PRIMARY KEY',
+  key: { name: string; columns: string[]; nullsNotDistinct?: boolean | undefined },
+  partitioned: boolean,
+  replaceOld: string | undefined,
+): string[] {
+  const tbl = qualifiedTable(tableSchema, tableName)
+  const drop = replaceOld !== undefined ? `DROP CONSTRAINT ${q(replaceOld)}, ` : ''
+  if (partitioned) {
+    const nd = key.nullsNotDistinct === true ? ' NULLS NOT DISTINCT' : ''
+    const add = `ADD CONSTRAINT ${q(key.name)} ${kind}${nd} (${key.columns.map(q).join(', ')})`
+    return replaceOld !== undefined
+      ? [`ALTER TABLE ${tbl} DROP CONSTRAINT ${q(replaceOld)}`, `ALTER TABLE ${tbl} ${add}`]
+      : [`ALTER TABLE ${tbl} ${add}`]
+  }
+  const indexName = replaceOld !== undefined ? tempIndexName(key.name) : key.name
+  return [
+    dropLeftoverIndex(tableSchema, indexName),
+    emitCreateIndex(tableName, tableSchema, keyIndex(indexName, key.columns, key.nullsNotDistinct === true)),
+    `ALTER TABLE ${tbl} ${drop}ADD CONSTRAINT ${q(key.name)} ${kind} USING INDEX ${q(indexName)}`,
+  ]
+}
+
+function emitAddUnique(tableName: string, tableSchema: string, uc: PwUniqueSnapshot, partitioned: boolean): string[] {
+  return emitKeyConstraint(tableName, tableSchema, 'UNIQUE', uc, partitioned, undefined)
+}
+
+function emitReplaceUnique(tableName: string, tableSchema: string, from: PwUniqueSnapshot, to: PwUniqueSnapshot, partitioned: boolean): string[] {
+  return emitKeyConstraint(tableName, tableSchema, 'UNIQUE', to, partitioned, from.name)
+}
+
+function emitAddCompositePK(tableName: string, tableSchema: string, pk: PwCompositePKSnapshot, partitioned: boolean): string[] {
+  return emitKeyConstraint(tableName, tableSchema, 'PRIMARY KEY', pk, partitioned, undefined)
+}
+
+function emitReplaceCompositePK(tableName: string, tableSchema: string, from: PwCompositePKSnapshot, to: PwCompositePKSnapshot, partitioned: boolean): string[] {
+  return emitKeyConstraint(tableName, tableSchema, 'PRIMARY KEY', to, partitioned, from.name)
+}