@stravigor/core 0.1.0

package/src/database/migration/sql_generator.ts

@@ -0,0 +1,378 @@
+import type { ColumnDefinition, DefaultValue } from '../../schema/database_representation.ts'
+import type { PostgreSQLType } from '../../schema/postgres.ts'
+import type {
+  SchemaDiff,
+  GeneratedSql,
+  EnumDiff,
+  TableDiff,
+  ColumnDiff,
+  ConstraintDiff,
+  IndexDiff,
+} from './types.ts'
+
+/**
+ * Generates SQL migration statements from a {@link SchemaDiff}.
+ *
+ * Output is split into four categories matching the migration file structure:
+ * enums, tables, constraints, indexes — each with up and down SQL.
+ */
+export default class SqlGenerator {
+  generate(diff: SchemaDiff): GeneratedSql {
+    return {
+      enumsUp: this.generateEnumsUp(diff.enums),
+      enumsDown: this.generateEnumsDown(diff.enums),
+      tables: this.generateTables(diff.tables),
+      constraintsUp: this.generateConstraintsUp(diff.constraints),
+      constraintsDown: this.generateConstraintsDown(diff.constraints),
+      indexesUp: this.generateIndexesUp(diff.indexes),
+      indexesDown: this.generateIndexesDown(diff.indexes),
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Enums
+  // ---------------------------------------------------------------------------
+
+  private generateEnumsUp(diffs: EnumDiff[]): string {
+    const lines: string[] = []
+    for (const d of diffs) {
+      if (d.kind === 'create') {
+        const vals = d.values.map(v => `'${v}'`).join(', ')
+        lines.push(`-- Create enum: ${d.name}`)
+        lines.push(`CREATE TYPE "${d.name}" AS ENUM (${vals});\n`)
+      } else if (d.kind === 'modify') {
+        lines.push(`-- Add values to enum: ${d.name}`)
+        for (const v of d.addedValues) {
+          lines.push(`ALTER TYPE "${d.name}" ADD VALUE '${v}';`)
+        }
+        lines.push('')
+      } else if (d.kind === 'drop') {
+        lines.push(`-- Drop enum: ${d.name}`)
+        lines.push(`DROP TYPE IF EXISTS "${d.name}";\n`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+
+  private generateEnumsDown(diffs: EnumDiff[]): string {
+    const lines: string[] = []
+    for (const d of diffs) {
+      if (d.kind === 'create') {
+        lines.push(`-- Reverse: drop enum ${d.name}`)
+        lines.push(`DROP TYPE IF EXISTS "${d.name}";\n`)
+      } else if (d.kind === 'modify') {
+        lines.push(`-- Reverse: cannot remove enum values for ${d.name}`)
+        lines.push(
+          `-- Manual intervention required to remove values: ${d.addedValues.join(', ')}\n`
+        )
+      } else if (d.kind === 'drop') {
+        const vals = d.values.map(v => `'${v}'`).join(', ')
+        lines.push(`-- Reverse: recreate enum ${d.name}`)
+        lines.push(`CREATE TYPE "${d.name}" AS ENUM (${vals});\n`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tables
+  // ---------------------------------------------------------------------------
+
+  private generateTables(diffs: TableDiff[]): Map<string, { up: string; down: string }> {
+    const result = new Map<string, { up: string; down: string }>()
+
+    for (const d of diffs) {
+      if (d.kind === 'create') {
+        result.set(d.table.name, {
+          up: this.generateCreateTable(
+            d.table.name,
+            d.table.columns,
+            d.table.primaryKey?.columns ?? []
+          ),
+          down: `-- Drop table: ${d.table.name}\nDROP TABLE IF EXISTS "${d.table.name}" CASCADE;`,
+        })
+      } else if (d.kind === 'drop') {
+        result.set(d.table.name, {
+          up: `-- Drop table: ${d.table.name}\nDROP TABLE IF EXISTS "${d.table.name}" CASCADE;`,
+          down: this.generateCreateTable(
+            d.table.name,
+            d.table.columns,
+            d.table.primaryKey?.columns ?? []
+          ),
+        })
+      } else if (d.kind === 'modify') {
+        result.set(d.tableName, {
+          up: this.generateAlterUp(d.tableName, d.columns),
+          down: this.generateAlterDown(d.tableName, d.columns),
+        })
+      }
+    }
+
+    return result
+  }
+
+  private generateCreateTable(
+    name: string,
+    columns: ColumnDefinition[],
+    pkColumns: string[]
+  ): string {
+    const lines: string[] = []
+    lines.push(`-- Create table: ${name}`)
+    lines.push(`CREATE TABLE IF NOT EXISTS "${name}" (`)
+
+    const colDefs: string[] = []
+    for (const c of columns) {
+      colDefs.push(`  ${columnToSql(c)}`)
+    }
+    if (pkColumns.length > 0) {
+      const pkCols = pkColumns.map(c => `"${c}"`).join(', ')
+      colDefs.push(`  CONSTRAINT "pk_${name}" PRIMARY KEY (${pkCols})`)
+    }
+    lines.push(colDefs.join(',\n'))
+    lines.push(');')
+    return lines.join('\n')
+  }
+
+  private generateAlterUp(tableName: string, columns: ColumnDiff[]): string {
+    const lines: string[] = []
+    lines.push(`-- Modify table: ${tableName}`)
+
+    for (const c of columns) {
+      if (c.kind === 'add') {
+        lines.push(`ALTER TABLE "${tableName}" ADD COLUMN ${columnToSql(c.column)};`)
+      } else if (c.kind === 'drop') {
+        lines.push(`ALTER TABLE "${tableName}" DROP COLUMN IF EXISTS "${c.column.name}";`)
+      } else if (c.kind === 'alter') {
+        if (c.typeChange) {
+          const newType = pgTypeToSql(c.typeChange.to)
+          lines.push(
+            `ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" TYPE ${newType} USING "${c.columnName}"::${newType};`
+          )
+        }
+        if (c.nullableChange) {
+          if (c.nullableChange.to) {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" SET NOT NULL;`)
+          } else {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" DROP NOT NULL;`)
+          }
+        }
+        if (c.defaultChange) {
+          if (c.defaultChange.to !== undefined) {
+            lines.push(
+              `ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" SET DEFAULT ${defaultValueToSql(c.defaultChange.to)};`
+            )
+          } else {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" DROP DEFAULT;`)
+          }
+        }
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  private generateAlterDown(tableName: string, columns: ColumnDiff[]): string {
+    const lines: string[] = []
+    lines.push(`-- Reverse modify table: ${tableName}`)
+
+    // Reverse in opposite order
+    for (const c of [...columns].reverse()) {
+      if (c.kind === 'add') {
+        // Reverse of add is drop
+        lines.push(`ALTER TABLE "${tableName}" DROP COLUMN IF EXISTS "${c.column.name}";`)
+      } else if (c.kind === 'drop') {
+        // Reverse of drop is add
+        lines.push(`ALTER TABLE "${tableName}" ADD COLUMN ${columnToSql(c.column)};`)
+      } else if (c.kind === 'alter') {
+        // Reverse each change
+        if (c.defaultChange) {
+          if (c.defaultChange.from !== undefined) {
+            lines.push(
+              `ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" SET DEFAULT ${defaultValueToSql(c.defaultChange.from)};`
+            )
+          } else {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" DROP DEFAULT;`)
+          }
+        }
+        if (c.nullableChange) {
+          if (c.nullableChange.from) {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" SET NOT NULL;`)
+          } else {
+            lines.push(`ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" DROP NOT NULL;`)
+          }
+        }
+        if (c.typeChange) {
+          const oldType = pgTypeToSql(c.typeChange.from)
+          lines.push(
+            `ALTER TABLE "${tableName}" ALTER COLUMN "${c.columnName}" TYPE ${oldType} USING "${c.columnName}"::${oldType};`
+          )
+        }
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Constraints
+  // ---------------------------------------------------------------------------
+
+  private generateConstraintsUp(diffs: ConstraintDiff[]): string {
+    const lines: string[] = []
+    for (const d of diffs) {
+      if (d.kind === 'add_fk') {
+        const name = `fk_${d.tableName}_${d.constraint.columns.join('_')}`
+        const cols = d.constraint.columns.map(c => `"${c}"`).join(', ')
+        const refCols = d.constraint.referencedColumns.map(c => `"${c}"`).join(', ')
+        lines.push(
+          `ALTER TABLE "${d.tableName}" ADD CONSTRAINT "${name}" FOREIGN KEY (${cols}) REFERENCES "${d.constraint.referencedTable}" (${refCols}) ON DELETE ${d.constraint.onDelete} ON UPDATE ${d.constraint.onUpdate};`
+        )
+      } else if (d.kind === 'drop_fk') {
+        const name = `fk_${d.tableName}_${d.constraint.columns.join('_')}`
+        lines.push(`ALTER TABLE "${d.tableName}" DROP CONSTRAINT IF EXISTS "${name}";`)
+      } else if (d.kind === 'add_unique') {
+        const name = `uq_${d.tableName}_${d.constraint.columns.join('_')}`
+        const cols = d.constraint.columns.map(c => `"${c}"`).join(', ')
+        lines.push(`ALTER TABLE "${d.tableName}" ADD CONSTRAINT "${name}" UNIQUE (${cols});`)
+      } else if (d.kind === 'drop_unique') {
+        const name = `uq_${d.tableName}_${d.constraint.columns.join('_')}`
+        lines.push(`ALTER TABLE "${d.tableName}" DROP CONSTRAINT IF EXISTS "${name}";`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+
+  private generateConstraintsDown(diffs: ConstraintDiff[]): string {
+    const lines: string[] = []
+    // Reverse: adds become drops, drops become adds
+    for (const d of [...diffs].reverse()) {
+      if (d.kind === 'add_fk') {
+        const name = `fk_${d.tableName}_${d.constraint.columns.join('_')}`
+        lines.push(`ALTER TABLE "${d.tableName}" DROP CONSTRAINT IF EXISTS "${name}";`)
+      } else if (d.kind === 'drop_fk') {
+        const name = `fk_${d.tableName}_${d.constraint.columns.join('_')}`
+        const cols = d.constraint.columns.map(c => `"${c}"`).join(', ')
+        const refCols = d.constraint.referencedColumns.map(c => `"${c}"`).join(', ')
+        lines.push(
+          `ALTER TABLE "${d.tableName}" ADD CONSTRAINT "${name}" FOREIGN KEY (${cols}) REFERENCES "${d.constraint.referencedTable}" (${refCols}) ON DELETE ${d.constraint.onDelete} ON UPDATE ${d.constraint.onUpdate};`
+        )
+      } else if (d.kind === 'add_unique') {
+        const name = `uq_${d.tableName}_${d.constraint.columns.join('_')}`
+        lines.push(`ALTER TABLE "${d.tableName}" DROP CONSTRAINT IF EXISTS "${name}";`)
+      } else if (d.kind === 'drop_unique') {
+        const name = `uq_${d.tableName}_${d.constraint.columns.join('_')}`
+        const cols = d.constraint.columns.map(c => `"${c}"`).join(', ')
+        lines.push(`ALTER TABLE "${d.tableName}" ADD CONSTRAINT "${name}" UNIQUE (${cols});`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Indexes
+  // ---------------------------------------------------------------------------
+
+  private generateIndexesUp(diffs: IndexDiff[]): string {
+    const lines: string[] = []
+    for (const d of diffs) {
+      if (d.kind === 'add') {
+        const name = indexName(d.tableName, d.index)
+        const cols = d.index.columns.map(c => `"${c}"`).join(', ')
+        const unique = d.index.unique ? 'UNIQUE ' : ''
+        lines.push(`CREATE ${unique}INDEX IF NOT EXISTS "${name}" ON "${d.tableName}" (${cols});`)
+      } else if (d.kind === 'drop') {
+        const name = indexName(d.tableName, d.index)
+        lines.push(`DROP INDEX IF EXISTS "${name}";`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+
+  private generateIndexesDown(diffs: IndexDiff[]): string {
+    const lines: string[] = []
+    for (const d of [...diffs].reverse()) {
+      if (d.kind === 'add') {
+        const name = indexName(d.tableName, d.index)
+        lines.push(`DROP INDEX IF EXISTS "${name}";`)
+      } else if (d.kind === 'drop') {
+        const name = indexName(d.tableName, d.index)
+        const cols = d.index.columns.map(c => `"${c}"`).join(', ')
+        const unique = d.index.unique ? 'UNIQUE ' : ''
+        lines.push(`CREATE ${unique}INDEX IF NOT EXISTS "${name}" ON "${d.tableName}" (${cols});`)
+      }
+    }
+    return lines.join('\n').trim()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (exported for testing)
+// ---------------------------------------------------------------------------
+
+function indexName(tableName: string, idx: { columns: string[]; unique: boolean }): string {
+  const suffix = idx.unique ? '_unique' : ''
+  return `idx_${tableName}_${idx.columns.join('_')}${suffix}`
+}
+
+/** Render a column definition as a SQL fragment (no trailing comma). */
+export function columnToSql(c: ColumnDefinition): string {
+  const typeSql = pgTypeToSql(c.pgType, c)
+  const parts = [`"${c.name}" ${typeSql}`]
+
+  // Serial types handle NOT NULL and default implicitly
+  if (!isSerial(c.pgType)) {
+    if (c.notNull) parts.push('NOT NULL')
+    if (c.defaultValue !== undefined) parts.push(`DEFAULT ${defaultValueToSql(c.defaultValue)}`)
+  }
+
+  return parts.join(' ')
+}
+
+/** Convert a PostgreSQLType (+ optional column metadata) to a SQL type string. */
+export function pgTypeToSql(pgType: PostgreSQLType, col?: ColumnDefinition): string {
+  if (typeof pgType === 'object') {
+    if (pgType.type === 'custom') return `"${pgType.name}"`
+    if (pgType.type === 'array') return `${pgTypeToSql(pgType.element as PostgreSQLType)}[]`
+  }
+
+  // Multi-word types
+  const multiWord: Record<string, string> = {
+    double_precision: 'DOUBLE PRECISION',
+    character_varying: 'CHARACTER VARYING',
+    bit_varying: 'BIT VARYING',
+  }
+  if (typeof pgType === 'string' && pgType in multiWord) {
+    return multiWord[pgType]!
+  }
+
+  const upper = (pgType as string).toUpperCase()
+
+  // Types with parameters
+  if (col) {
+    if ((pgType === 'varchar' || pgType === 'character_varying') && col.length) {
+      return `VARCHAR(${col.length})`
+    }
+    if ((pgType === 'char' || pgType === 'character') && col.length) {
+      return `CHAR(${col.length})`
+    }
+    if ((pgType === 'numeric' || pgType === 'decimal') && col.precision !== undefined) {
+      if (col.scale !== undefined) return `${upper}(${col.precision},${col.scale})`
+      return `${upper}(${col.precision})`
+    }
+  }
+
+  return upper
+}
+
+/** Convert a DefaultValue to its SQL representation. */
+export function defaultValueToSql(dv: DefaultValue): string {
+  if (dv.kind === 'expression') return dv.sql
+  if (dv.value === null) return 'NULL'
+  if (typeof dv.value === 'boolean') return dv.value ? 'true' : 'false'
+  if (typeof dv.value === 'number') return String(dv.value)
+  return `'${dv.value}'`
+}
+
+function isSerial(pgType: PostgreSQLType): boolean {
+  return pgType === 'serial' || pgType === 'bigserial' || pgType === 'smallserial'
+}

package/src/database/migration/tracker.ts

@@ -0,0 +1,76 @@
+import type Database from '../database.ts'
+import type { MigrationRecord } from './types.ts'
+
+const TABLE_NAME = '_strav_migrations'
+
+/**
+ * Manages the `_strav_migrations` tracking table.
+ *
+ * Keeps track of which migration versions have been applied and
+ * groups them into batches so rollbacks can undo an entire batch at once.
+ */
+export default class MigrationTracker {
+  constructor(private db: Database) {}
+
+  /** Create the tracking table if it does not exist. */
+  async ensureTable(): Promise<void> {
+    await this.db.sql.unsafe(`
+      CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (
+        id SERIAL PRIMARY KEY,
+        version VARCHAR(255) NOT NULL,
+        batch INTEGER NOT NULL,
+        executed_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+      )
+    `)
+  }
+
+  /** Return all applied migration records ordered by version. */
+  async getAppliedMigrations(): Promise<MigrationRecord[]> {
+    return (await this.db.sql.unsafe(
+      `SELECT id, version, batch, executed_at FROM ${TABLE_NAME} ORDER BY version`
+    )) as MigrationRecord[]
+  }
+
+  /** Given a list of all known versions, return those not yet applied. */
+  async getPendingVersions(allVersions: string[]): Promise<string[]> {
+    const applied = await this.getAppliedMigrations()
+    const appliedSet = new Set(applied.map(r => r.version))
+    return allVersions.filter(v => !appliedSet.has(v))
+  }
+
+  /** Return the highest batch number, or 0 if no migrations exist. */
+  async getLastBatch(): Promise<number> {
+    const rows = await this.db.sql.unsafe(
+      `SELECT COALESCE(MAX(batch), 0) AS max_batch FROM ${TABLE_NAME}`
+    )
+    return (rows[0] as any).max_batch
+  }
+
+  /** Record a migration as applied. */
+  async recordMigration(version: string, batch: number): Promise<void> {
+    await this.db.sql.unsafe(`INSERT INTO ${TABLE_NAME} (version, batch) VALUES ($1, $2)`, [
+      version,
+      batch,
+    ])
+  }
+
+  /** Remove a migration record by version. */
+  async removeMigration(version: string): Promise<void> {
+    await this.db.sql.unsafe(`DELETE FROM ${TABLE_NAME} WHERE version = $1`, [version])
+  }
+
+  /** Return all migrations for a specific batch. */
+  async getMigrationsByBatch(batch: number): Promise<MigrationRecord[]> {
+    return (await this.db.sql.unsafe(
+      `SELECT id, version, batch, executed_at FROM ${TABLE_NAME} WHERE batch = $1 ORDER BY version DESC`,
+      [batch]
+    )) as MigrationRecord[]
+  }
+
+  /** Return migrations from the latest batch (most recent run). */
+  async getLatestBatchMigrations(): Promise<MigrationRecord[]> {
+    const lastBatch = await this.getLastBatch()
+    if (lastBatch === 0) return []
+    return this.getMigrationsByBatch(lastBatch)
+  }
+}

package/src/database/migration/types.ts

@@ -0,0 +1,189 @@
+import type {
+  ColumnDefinition,
+  ForeignKeyConstraint,
+  UniqueConstraint,
+  IndexDefinition,
+  TableDefinition,
+} from '../../schema/database_representation.ts'
+import type { PostgreSQLType } from '../../schema/postgres.ts'
+
+// ---------------------------------------------------------------------------
+// Enum diffs
+// ---------------------------------------------------------------------------
+
+export interface EnumCreate {
+  kind: 'create'
+  name: string
+  values: string[]
+}
+
+export interface EnumDrop {
+  kind: 'drop'
+  name: string
+  values: string[]
+}
+
+export interface EnumModify {
+  kind: 'modify'
+  name: string
+  addedValues: string[]
+}
+
+export type EnumDiff = EnumCreate | EnumDrop | EnumModify
+
+// ---------------------------------------------------------------------------
+// Column diffs
+// ---------------------------------------------------------------------------
+
+export interface ColumnAdd {
+  kind: 'add'
+  column: ColumnDefinition
+}
+
+export interface ColumnDrop {
+  kind: 'drop'
+  column: ColumnDefinition
+}
+
+export interface ColumnAlter {
+  kind: 'alter'
+  columnName: string
+  typeChange?: { from: PostgreSQLType; to: PostgreSQLType }
+  nullableChange?: { from: boolean; to: boolean }
+  defaultChange?: {
+    from: ColumnDefinition['defaultValue']
+    to: ColumnDefinition['defaultValue']
+  }
+}
+
+export type ColumnDiff = ColumnAdd | ColumnDrop | ColumnAlter
+
+// ---------------------------------------------------------------------------
+// Table diffs
+// ---------------------------------------------------------------------------
+
+export interface TableCreate {
+  kind: 'create'
+  table: TableDefinition
+}
+
+export interface TableDrop {
+  kind: 'drop'
+  table: TableDefinition
+}
+
+export interface TableModify {
+  kind: 'modify'
+  tableName: string
+  columns: ColumnDiff[]
+}
+
+export type TableDiff = TableCreate | TableDrop | TableModify
+
+// ---------------------------------------------------------------------------
+// Constraint diffs
+// ---------------------------------------------------------------------------
+
+export interface ForeignKeyAdd {
+  kind: 'add_fk'
+  tableName: string
+  constraint: ForeignKeyConstraint
+}
+
+export interface ForeignKeyDrop {
+  kind: 'drop_fk'
+  tableName: string
+  constraint: ForeignKeyConstraint
+}
+
+export interface UniqueAdd {
+  kind: 'add_unique'
+  tableName: string
+  constraint: UniqueConstraint
+}
+
+export interface UniqueDrop {
+  kind: 'drop_unique'
+  tableName: string
+  constraint: UniqueConstraint
+}
+
+export type ConstraintDiff = ForeignKeyAdd | ForeignKeyDrop | UniqueAdd | UniqueDrop
+
+// ---------------------------------------------------------------------------
+// Index diffs
+// ---------------------------------------------------------------------------
+
+export interface IndexAdd {
+  kind: 'add'
+  tableName: string
+  index: IndexDefinition
+}
+
+export interface IndexDrop {
+  kind: 'drop'
+  tableName: string
+  index: IndexDefinition
+}
+
+export type IndexDiff = IndexAdd | IndexDrop
+
+// ---------------------------------------------------------------------------
+// Top-level schema diff
+// ---------------------------------------------------------------------------
+
+export interface SchemaDiff {
+  enums: EnumDiff[]
+  tables: TableDiff[]
+  constraints: ConstraintDiff[]
+  indexes: IndexDiff[]
+}
+
+// ---------------------------------------------------------------------------
+// Generated SQL output
+// ---------------------------------------------------------------------------
+
+export interface GeneratedSql {
+  enumsUp: string
+  enumsDown: string
+  tables: Map<string, { up: string; down: string }>
+  constraintsUp: string
+  constraintsDown: string
+  indexesUp: string
+  indexesDown: string
+}
+
+// ---------------------------------------------------------------------------
+// Migration manifest (stored as manifest.json)
+// ---------------------------------------------------------------------------
+
+export interface MigrationSummary {
+  tablesToCreate: number
+  tablesToDrop: number
+  tablesToModify: number
+  enumsToCreate: number
+  enumsToModify: number
+  enumsToDrop: number
+}
+
+export interface MigrationManifest {
+  version: string
+  message: string
+  generatedAt: string
+  summary: MigrationSummary
+  executionOrder: {
+    up: string[]
+    down: string[]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Migration tracking record (from _strav_migrations table)
+// ---------------------------------------------------------------------------
+
+export interface MigrationRecord {
+  id: number
+  version: string
+  batch: number
+  executed_at: Date
+}