Function runMigrations

server/src/db/migrate.ts:156–219

(config?: DatabaseConfig)

 * Run all pending migrations
 */
export async function runMigrations(config?: DatabaseConfig): Promise<void> {
  // Initialize database if config provided
  if (config) {
    initializeDatabase(config);
  }

  // Create migrations table
  await createMigrationsTable();

  // Load all migrations
  const migrations = await loadMigrations();
  const appliedMigrations = await getAppliedMigrations();
  const appliedVersions = new Set(appliedMigrations.map((m) => m.version));

  // Detect filename mismatches — a sign that a migration version was
  // claimed by a different file (numbering collision from concurrent PRs).
  // Collisions above MISMATCH_BASELINE block startup; older ones are
  // historical debt that get logged as warnings.
  const MISMATCH_BASELINE = 389;
  const appliedByVersion = new Map(appliedMigrations.map((m) => [m.version, m.filename]));
  const warnings: string[] = [];
  const errors: string[] = [];
  for (const m of migrations) {
    const appliedFilename = appliedByVersion.get(m.version);
    if (appliedFilename && appliedFilename !== m.filename) {
      const msg = `Migration ${m.version} on disk is "${m.filename}" but was applied as "${appliedFilename}"`;
      if (m.version > MISMATCH_BASELINE) {
        errors.push(msg);
      } else {
        warnings.push(msg);
      }
    }
  }
  if (warnings.length > 0) {
    console.warn(
      `⚠ Historical migration filename mismatches (pre-${MISMATCH_BASELINE}):\n${warnings.join("\n")}`
    );
  }
  if (errors.length > 0) {
    throw new Error(
      `Migration filename mismatches detected (possible numbering collision):\n${errors.join("\n")}\n` +
      `Renumber the colliding migration(s) and redeploy.`
    );
  }

  // Find pending migrations
  const pendingMigrations = migrations.filter(
    (m) => !appliedVersions.has(m.version)
  );

  if (pendingMigrations.length === 0) {
    // Quiet startup - no output when nothing to do
    return;
  }

  console.log(`Applying ${pendingMigrations.length} pending migrations...`);

  // Apply each pending migration