@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/templates/backend/db/connection.ts

@@ -1,99 +1,224 @@
 import path from 'node:path';
 import { mkdirSync } from 'node:fs';
 
+import { resolveWorkspaceRoot } from '../env.js';
+
 export interface DatabaseClient {
   query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
   execute(sql: string, params?: unknown[]): Promise<void>;
   close(): Promise<void>;
 }
 
-export async function createDatabaseClient(url = process.env.DATABASE_URL ?? 'file:./data/dev.sqlite'): Promise<DatabaseClient> {
-  if (isSqlite(url)) {
-    return createSqliteClient(url);
-  }
-  if (isPostgres(url)) {
-    return createPostgresClient(url);
-  }
-  throw new Error(
-    `[db] Unsupported DATABASE_URL '${url}'. Use file:./path/to.sqlite or postgres://...`
-  );
-}
+type BunSqlClient = {
+  unsafe<T = unknown>(query: string, params?: unknown[]): Promise<T[]>;
+  close(options?: { timeout?: number }): Promise<void>;
+};
 
-function isSqlite(url: string): boolean {
-  return url.startsWith('file:') || url.endsWith('.sqlite') || url.endsWith('.db');
-}
+type BunSqlConstructor = new (url?: string) => BunSqlClient;
 
-function isPostgres(url: string): boolean {
-  return url.startsWith('postgres://') || url.startsWith('postgresql://');
-}
+type BunRuntime = {
+  SQL?: BunSqlConstructor;
+};
 
-async function createSqliteClient(url: string): Promise<DatabaseClient> {
-  let Database: typeof import('better-sqlite3');
-  try {
-    const sqliteModule = await import('better-sqlite3');
-    Database = sqliteModule.default ?? (sqliteModule as unknown as typeof import('better-sqlite3'));
-  } catch (error) {
-    throw new Error(
-      `[db] Failed to load better-sqlite3. Install it in your workspace with "npm install better-sqlite3". (${(error as Error).message})`
-    );
+export async function createDatabaseClient(
+  url = process.env.DATABASE_URL ?? 'file:./data/dev.sqlite',
+): Promise<DatabaseClient> {
+  const driver = detectDatabaseDriver(url);
+  const SQL = loadBunSql();
+  const normalizedUrl = driver === 'sqlite' ? normalizeSqliteUrl(url) : url;
+
+  if (driver === 'sqlite') {
+    ensureSqliteDirectory(normalizedUrl);
   }
 
-  const target = normalizeSqlitePath(url);
-  mkdirSync(path.dirname(target), { recursive: true });
-  const db = new Database(target);
+  const client = new SQL(normalizedUrl);
+  return createBunSqlClient(client, driver);
+}
 
+function detectDatabaseDriver(url: string): 'sqlite' | 'postgres' {
+  const trimmed = url.trim();
+  if (
+    trimmed === ':memory:' ||
+    trimmed.startsWith('file:') ||
+    trimmed.startsWith('file://') ||
+    trimmed.startsWith('sqlite:') ||
+    trimmed.startsWith('sqlite://') ||
+    trimmed.endsWith('.sqlite') ||
+    trimmed.endsWith('.db')
+  ) {
+    return 'sqlite';
+  }
+  if (trimmed.startsWith('postgres://') || trimmed.startsWith('postgresql://')) {
+    return 'postgres';
+  }
+  throw new Error(
+    `[db] Unsupported DATABASE_URL '${url}'. Use file:./path/to.sqlite, sqlite:./path/to.sqlite, :memory:, or postgres://...`,
+  );
+}
+
+function createBunSqlClient(client: BunSqlClient, driver: 'sqlite' | 'postgres'): DatabaseClient {
   return {
-    async query(sql, params) {
-      const statement = db.prepare(sql);
-      return statement.all(params ?? []);
+    async query<T = unknown>(query: string, params?: unknown[]): Promise<T[]> {
+      const prepared = prepareQuery(query, params, driver);
+      return await client.unsafe<T>(prepared.query, prepared.params);
     },
-    async execute(sql, params) {
-      const statement = db.prepare(sql);
-      statement.run(params ?? []);
+    async execute(query: string, params?: unknown[]): Promise<void> {
+      const prepared = prepareQuery(query, params, driver);
+      await client.unsafe(prepared.query, prepared.params);
     },
     async close() {
-      db.close();
-    }
+      await client.close();
+    },
   };
 }
 
-async function createPostgresClient(url: string): Promise<DatabaseClient> {
-  type PgClientCtor = new (...args: any[]) => {
-    query: (text: string, params?: unknown[]) => Promise<{ rows: any[] }>;
-    connect: () => Promise<void>;
-    end: () => Promise<void>;
+function prepareQuery(
+  query: string,
+  params: unknown[] | undefined,
+  driver: 'sqlite' | 'postgres',
+): {
+  query: string;
+  params: unknown[] | undefined;
+} {
+  if (!params || params.length === 0 || driver !== 'postgres' || !query.includes('?')) {
+    return { query, params };
+  }
+
+  return {
+    query: convertQuestionMarksToDollarParams(query),
+    params,
   };
+}
 
-  let ClientCtor: PgClientCtor;
+function loadBunSql(): BunSqlConstructor {
+  const bunRuntime = (globalThis as typeof globalThis & { Bun?: BunRuntime }).Bun;
+  const SQL = bunRuntime?.SQL;
+  if (SQL) {
+    return SQL;
+  }
+
+  let reason = 'missing Bun.SQL runtime';
   try {
-    const pgModule = await import('pg');
-    ClientCtor = (pgModule as unknown as { Client: PgClientCtor }).Client;
+    reason = String(Bun.version);
   } catch (error) {
-    throw new Error(
-      `[db] Failed to load pg. Install it in your workspace with "npm install pg". (${(error as Error).message})`
-    );
+    reason = (error as Error).message;
   }
 
-  const client = new ClientCtor({ connectionString: url });
-  await client.connect();
+  throw new Error(`[db] Failed to load Bun.SQL. Run database helpers with Bun. (${reason})`);
+}
 
-  return {
-    async query(sql, params) {
-      const result = await client.query(sql, params);
-      return result.rows;
-    },
-    async execute(sql, params) {
-      await client.query(sql, params);
-    },
-    async close() {
-      await client.end();
-    }
-  };
+function normalizeSqliteUrl(url: string): string {
+  if (url.trim() === ':memory:') {
+    return ':memory:';
+  }
+
+  const workspaceRoot = resolveWorkspaceRoot();
+  const target = stripSqlitePrefix(url.trim());
+  const resolved = path.isAbsolute(target)
+    ? path.resolve(target)
+    : path.resolve(workspaceRoot, target);
+  return `file:${resolved}`;
+}
+
+function ensureSqliteDirectory(url: string): void {
+  if (url === ':memory:') {
+    return;
+  }
+
+  const filename = stripSqlitePrefix(url);
+  mkdirSync(path.dirname(filename), { recursive: true });
 }
 
-function normalizeSqlitePath(url: string): string {
+function stripSqlitePrefix(url: string): string {
+  if (url.startsWith('file://')) {
+    return url.slice('file://'.length);
+  }
   if (url.startsWith('file:')) {
-    return path.resolve(url.slice('file:'.length));
+    return url.slice('file:'.length);
+  }
+  if (url.startsWith('sqlite://')) {
+    return url.slice('sqlite://'.length);
   }
-  return path.resolve(url);
+  if (url.startsWith('sqlite:')) {
+    return url.slice('sqlite:'.length);
+  }
+  return url;
+}
+
+function convertQuestionMarksToDollarParams(query: string): string {
+  let result = '';
+  let placeholderIndex = 0;
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let index = 0; index < query.length; index += 1) {
+    const character = query[index];
+    const next = query[index + 1];
+
+    if (inLineComment) {
+      result += character;
+      if (character === '\n') {
+        inLineComment = false;
+      }
+      continue;
+    }
+
+    if (inBlockComment) {
+      result += character;
+      if (character === '*' && next === '/') {
+        result += next;
+        index += 1;
+        inBlockComment = false;
+      }
+      continue;
+    }
+
+    if (!inSingleQuote && !inDoubleQuote && character === '-' && next === '-') {
+      result += character + next;
+      index += 1;
+      inLineComment = true;
+      continue;
+    }
+
+    if (!inSingleQuote && !inDoubleQuote && character === '/' && next === '*') {
+      result += character + next;
+      index += 1;
+      inBlockComment = true;
+      continue;
+    }
+
+    if (character === "'" && !inDoubleQuote) {
+      result += character;
+      if (inSingleQuote && next === "'") {
+        result += next;
+        index += 1;
+      } else {
+        inSingleQuote = !inSingleQuote;
+      }
+      continue;
+    }
+
+    if (character === '"' && !inSingleQuote) {
+      result += character;
+      if (inDoubleQuote && next === '"') {
+        result += next;
+        index += 1;
+      } else {
+        inDoubleQuote = !inDoubleQuote;
+      }
+      continue;
+    }
+
+    if (!inSingleQuote && !inDoubleQuote && character === '?') {
+      placeholderIndex += 1;
+      result += `$${placeholderIndex}`;
+      continue;
+    }
+
+    result += character;
+  }
+
+  return result;
 }

package/templates/backend/db/migrate.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -8,6 +8,7 @@ import type { DatabaseClient } from './connection.js';
 
 const args = process.argv.slice(2);
 const MIGRATIONS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'migrations');
+const DEFAULT_MIGRATIONS_TABLE = '_webstir_migrations';
 
 export type MigrationFn = (ctx: MigrationContext) => Promise<void> | void;
 
@@ -29,34 +30,41 @@ async function main() {
   }
 
   const migrations = await loadMigrations();
+  validateMigrationIds(migrations);
+
   if (args.includes('--list')) {
     printMigrations(migrations);
     return;
   }
 
-  if (migrations.length === 0) {
-    console.warn('[migrate] No migrations found under src/backend/db/migrations');
-    return;
-  }
-
   const direction: 'up' | 'down' = args.includes('--down') ? 'down' : 'up';
   const steps = parseSteps();
 
   const client = await createDatabaseClient();
   try {
-    await ensureMigrationsTable(client);
-    if (direction === 'down') {
-      await runDown(client, migrations, steps);
+    const table = getMigrationsTable();
+    await ensureMigrationsTable(client, table);
+    if (args.includes('--status')) {
+      await printStatus(client, table, migrations);
+    } else if (migrations.length === 0) {
+      console.warn('[migrate] No migrations found under src/backend/db/migrations');
+    } else if (direction === 'down') {
+      await runDown(client, table, migrations, steps);
     } else {
-      await runUp(client, migrations, steps);
+      await runUp(client, table, migrations, steps);
     }
   } finally {
     await client.close();
   }
 }
 
-async function runUp(client: DatabaseClient, migrations: MigrationModule[], steps: number | undefined) {
-  const applied = await getAppliedMigrations(client);
+async function runUp(
+  client: DatabaseClient,
+  table: string,
+  migrations: MigrationModule[],
+  steps: number | undefined,
+) {
+  const applied = await getAppliedMigrations(client, table);
   const pending = migrations.filter((migration) => !applied.includes(migration.id));
   if (pending.length === 0) {
     console.info('[migrate] Database is up to date.');
@@ -66,13 +74,27 @@ async function runUp(client: DatabaseClient, migrations: MigrationModule[], step
   const toRun = typeof steps === 'number' ? pending.slice(0, steps) : pending;
   for (const migration of toRun) {
     console.info(`[migrate] Applying ${migration.id}`);
-    await migration.up(createMigrationContext(client));
-    await recordMigration(client, migration.id);
+    try {
+      await runInTransaction(client, async () => {
+        await migration.up(createMigrationContext(client));
+        await recordMigration(client, table, migration.id);
+      });
+    } catch (error) {
+      throw new Error(
+        `[migrate] Migration ${migration.id} failed while applying. The migration was rolled back and was not recorded as applied.`,
+        { cause: error },
+      );
+    }
   }
 }
 
-async function runDown(client: DatabaseClient, migrations: MigrationModule[], steps: number | undefined) {
-  const applied = await getAppliedMigrations(client);
+async function runDown(
+  client: DatabaseClient,
+  table: string,
+  migrations: MigrationModule[],
+  steps: number | undefined,
+) {
+  const applied = await getAppliedMigrations(client, table);
   if (applied.length === 0) {
     console.info('[migrate] No applied migrations to roll back.');
     return;
@@ -88,53 +110,96 @@ async function runDown(client: DatabaseClient, migrations: MigrationModule[], st
       continue;
     }
     console.info(`[migrate] Reverting ${id}`);
-    await migration.down(createMigrationContext(client));
-    await deleteMigrationRecord(client, id);
+    try {
+      await runInTransaction(client, async () => {
+        await migration.down?.(createMigrationContext(client));
+        await deleteMigrationRecord(client, table, id);
+      });
+    } catch (error) {
+      throw new Error(
+        `[migrate] Migration ${id} failed while reverting. The migration record was kept so it can be retried.`,
+        { cause: error },
+      );
+    }
+  }
+}
+
+async function printStatus(client: DatabaseClient, table: string, migrations: MigrationModule[]) {
+  const applied = await getAppliedMigrations(client, table);
+  const knownIds = new Set(migrations.map((migration) => migration.id));
+  const appliedIds = new Set(applied);
+  const pending = migrations.filter((migration) => !appliedIds.has(migration.id));
+  const missing = applied.filter((id) => !knownIds.has(id));
+
+  console.info(`[migrate] Status for ${table}:`);
+  console.info(`[migrate] Applied: ${applied.length}`);
+  console.info(`[migrate] Pending: ${pending.length}`);
+  if (pending.length > 0) {
+    for (const migration of pending) {
+      console.info(`- pending ${migration.id}`);
+    }
+  }
+  if (missing.length > 0) {
+    console.warn('[migrate] Applied records without local migration files:');
+    for (const id of missing) {
+      console.warn(`- missing ${id}`);
+    }
   }
 }
 
-async function ensureMigrationsTable(client: DatabaseClient) {
-  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+async function ensureMigrationsTable(client: DatabaseClient, table: string) {
   await client.execute(
     `CREATE TABLE IF NOT EXISTS ${table} (
       id TEXT PRIMARY KEY,
       applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
-    )`
+    )`,
   );
 }
 
-async function getAppliedMigrations(client: DatabaseClient): Promise<string[]> {
-  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+async function getAppliedMigrations(client: DatabaseClient, table: string): Promise<string[]> {
   const rows = await client.query<{ id: string }>(`SELECT id FROM ${table} ORDER BY applied_at`);
   return rows.map((row) => row.id);
 }
 
-async function recordMigration(client: DatabaseClient, id: string) {
-  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+async function recordMigration(client: DatabaseClient, table: string, id: string) {
   await client.execute(`INSERT INTO ${table} (id) VALUES (?)`, [id]);
 }
 
-async function deleteMigrationRecord(client: DatabaseClient, id: string) {
-  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+async function deleteMigrationRecord(client: DatabaseClient, table: string, id: string) {
   await client.execute(`DELETE FROM ${table} WHERE id = ?`, [id]);
 }
 
+async function runInTransaction(client: DatabaseClient, action: () => Promise<void>) {
+  await client.execute('BEGIN');
+  try {
+    await action();
+    await client.execute('COMMIT');
+  } catch (error) {
+    try {
+      await client.execute('ROLLBACK');
+    } catch (rollbackError) {
+      throw new Error('[migrate] Failed to roll back failed migration transaction.', {
+        cause: rollbackError,
+      });
+    }
+    throw error;
+  }
+}
+
 function createMigrationContext(client: DatabaseClient): MigrationContext {
   return {
     sql: (query, params) => client.execute(query, params),
-    query: (query, params) => client.query(query, params)
+    query: (query, params) => client.query(query, params),
   };
 }
 
 async function loadMigrations(): Promise<MigrationModule[]> {
   try {
     const files = await fs.readdir(MIGRATIONS_DIR);
-    const scriptFiles = files
-      .filter((file) => /\.[cm]?[jt]s$/.test(file))
-      .sort();
+    const scriptFiles = files.filter((file) => /\.[cm]?[jt]s$/.test(file)).sort();
     const modules: MigrationModule[] = [];
     for (const file of scriptFiles) {
-      const moduleUrl = pathToFileURL(path.join(MIGRATIONS_DIR, file)).href + `?t=${Date.now()}`;
+      const moduleUrl = `${pathToFileURL(path.join(MIGRATIONS_DIR, file)).href}?t=${Date.now()}`;
       const imported = (await import(moduleUrl)) as Record<string, unknown>;
       const migration = normalizeMigrationModule(imported, file);
       if (migration) {
@@ -148,18 +213,25 @@ async function loadMigrations(): Promise<MigrationModule[]> {
   }
 }
 
-function normalizeMigrationModule(exports: Record<string, unknown>, file: string): MigrationModule | undefined {
+function normalizeMigrationModule(
+  exports: Record<string, unknown>,
+  file: string,
+): MigrationModule | undefined {
+  const defaultExport =
+    typeof exports.default === 'object' && exports.default !== null
+      ? (exports.default as Record<string, unknown>)
+      : undefined;
   const id =
     typeof exports.id === 'string'
       ? exports.id
-      : typeof exports.default === 'object' && exports.default && typeof (exports.default as any).id === 'string'
-        ? (exports.default as any).id
+      : typeof defaultExport?.id === 'string'
+        ? defaultExport.id
         : path.basename(file).replace(/\.[cm]?[jt]s$/, '');
   const up: MigrationFn | undefined =
     typeof exports.up === 'function'
       ? (exports.up as MigrationFn)
-      : exports.default && typeof (exports.default as any).up === 'function'
-        ? ((exports.default as any).up as MigrationFn)
+      : typeof defaultExport?.up === 'function'
+        ? (defaultExport.up as MigrationFn)
         : undefined;
   if (!up) {
     console.warn(`[migrate] ${file} does not export an up() function. Skipping.`);
@@ -168,12 +240,41 @@ function normalizeMigrationModule(exports: Record<string, unknown>, file: string
   const down: MigrationFn | undefined =
     typeof exports.down === 'function'
       ? (exports.down as MigrationFn)
-      : exports.default && typeof (exports.default as any).down === 'function'
-        ? ((exports.default as any).down as MigrationFn)
+      : typeof defaultExport?.down === 'function'
+        ? (defaultExport.down as MigrationFn)
         : undefined;
   return { id, up, down };
 }
 
+function validateMigrationIds(migrations: MigrationModule[]) {
+  const seen = new Map<string, number>();
+  const duplicates = new Set<string>();
+
+  for (const migration of migrations) {
+    const count = seen.get(migration.id) ?? 0;
+    seen.set(migration.id, count + 1);
+    if (count > 0) {
+      duplicates.add(migration.id);
+    }
+  }
+
+  if (duplicates.size > 0) {
+    throw new Error(
+      `[migrate] Duplicate migration id(s): ${Array.from(duplicates).sort().join(', ')}`,
+    );
+  }
+}
+
+function getMigrationsTable(): string {
+  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? DEFAULT_MIGRATIONS_TABLE;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new Error(
+      `[migrate] DATABASE_MIGRATIONS_TABLE must be a single SQL identifier using letters, numbers, and underscores, and must not start with a number (received "${table}").`,
+    );
+  }
+  return table;
+}
+
 function parseSteps(): number | undefined {
   const value = parseOption('--steps');
   if (!value) return undefined;
@@ -210,19 +311,24 @@ function printMigrations(migrations: MigrationModule[]) {
 
 function printHelp() {
   console.info(`Usage:
-  npx tsx src/backend/db/migrate.ts [--list]
-  npx tsx src/backend/db/migrate.ts --down [--steps 1]
+  bun src/backend/db/migrate.ts [--list]
+  bun src/backend/db/migrate.ts --status
+  bun src/backend/db/migrate.ts --down [--steps 1]
 
 Options:
-  --list        Show migrations and exit
+  --list        Show local migrations and exit
+  --status      Show applied, pending, and missing migration records
   --down        Roll back migrations instead of applying new ones
   --steps <n>   Limit how many migrations to run in the current direction
   --help        Show this message
 
 Notes:
   - Defaults to reading migration files from src/backend/db/migrations.
+  - DATABASE_MIGRATIONS_TABLE must be a single SQL identifier; it is validated before use.
+  - Each migration runs in a transaction. Failed up() migrations are rolled back and not recorded.
+  - For repeatable tests, use a throwaway DATABASE_URL and --down without --steps to run every available down() migration.
   - DATABASE_URL controls the target database (file:./dev.sqlite by default).
-  - Install 'better-sqlite3' for SQLite or 'pg' for Postgres before running.`);
+  - SQLite uses Bun's built-in bun:sqlite runtime; install 'pg' only for Postgres.`);
 }
 
 main().catch((error) => {

package/templates/backend/db/types.d.ts

@@ -1,2 +1,2 @@
-declare module 'better-sqlite3';
+declare module 'bun:sqlite';
 declare module 'pg';