@veap/database 0.1.1 → 0.1.3

package/dist/cli/commands/make-migration.d.ts

@@ -0,0 +1,13 @@
+import { Command, type CommandInput, type Output } from "@veap/kernel/cli";
+/**
+ * `veap make:migration {name}` — scaffolds a migration in the host project.
+ *
+ * The file lands in the project the console was started in (by default
+ * `<project>/migrations`) and the directory's `index.ts` is regenerated, so the
+ * new migration is picked up by `.withMigrations(appMigrations)`.
+ */
+export declare class MakeMigrationCommand extends Command {
+    static signature: string;
+    static description: string;
+    handle(input: CommandInput, output: Output): Promise<number>;
+}

package/dist/cli/commands/make-migration.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { Command } from "@veap/kernel/cli";
+import { generateMigration } from "../../migrations/generator.js";
+/**
+ * `veap make:migration {name}` — scaffolds a migration in the host project.
+ *
+ * The file lands in the project the console was started in (by default
+ * `<project>/migrations`) and the directory's `index.ts` is regenerated, so the
+ * new migration is picked up by `.withMigrations(appMigrations)`.
+ */
+export class MakeMigrationCommand extends Command {
+    static signature = "make:migration {name : Name of the migration, e.g. create_posts_table} {--dir=path : Directory relative to the project root (default: migrations)}";
+    static description = "Create a new migration file in the application";
+    async handle(input, output) {
+        const name = input.argument("name") ?? "";
+        const dir = input.option("dir");
+        const directory = path.resolve(this.context.root, typeof dir === "string" && dir.trim() !== "" ? dir.trim() : "migrations");
+        const { filePath } = await generateMigration(name, directory);
+        const relative = path.relative(this.context.root, filePath);
+        output.success(`Created migration: ${relative}`);
+        output.info('Run "veap migrate" to apply the pending migrations.');
+        return 0;
+    }
+}

package/dist/cli/commands/migrate-rollback.d.ts

@@ -0,0 +1,14 @@
+import { Command, type CommandInput, type Output } from "@veap/kernel/cli";
+/**
+ * `veap migrate:rollback` — undoes the last batch of the scope.
+ *
+ * Runs each migration's `down()` in the reverse of the order it was applied, and
+ * deletes the `migrations` rows it undid, so a `veap migrate` afterwards
+ * re-applies exactly what was rolled back. In production the command asks first;
+ * `--force` answers that question for an unattended run.
+ */
+export declare class MigrateRollbackCommand extends Command {
+    static signature: string;
+    static description: string;
+    handle(input: CommandInput, output: Output): Promise<number>;
+}

package/dist/cli/commands/migrate-rollback.js

@@ -0,0 +1,41 @@
+import { Command } from "@veap/kernel/cli";
+import { rollbackMigrations } from "../../migrations/runner.js";
+import { confirmToProceed } from "../confirmation.js";
+import { hasDatabaseConnection, resolveRegisteredMigrations, resolveScope, } from "../migrations.js";
+/**
+ * `veap migrate:rollback` — undoes the last batch of the scope.
+ *
+ * Runs each migration's `down()` in the reverse of the order it was applied, and
+ * deletes the `migrations` rows it undid, so a `veap migrate` afterwards
+ * re-applies exactly what was rolled back. In production the command asks first;
+ * `--force` answers that question for an unattended run.
+ */
+export class MigrateRollbackCommand extends Command {
+    static signature = "migrate:rollback {--scope=app : Migration scope to roll back}";
+    static description = "Roll back the last batch of application migrations";
+    async handle(input, output) {
+        const scope = resolveScope(input);
+        const migrations = await resolveRegisteredMigrations(this.context.container);
+        if (migrations.length === 0) {
+            output.warn("No application migrations are registered. Add them to the application with `.withMigrations(appMigrations)`.");
+            return 0;
+        }
+        if (!hasDatabaseConnection()) {
+            output.error("No database connection is available. Set DATABASE_URL (or register DatabaseServiceProvider) before rolling migrations back.");
+            return 1;
+        }
+        const proceed = await confirmToProceed(this.context, output, "Roll back the last batch of migrations");
+        if (!proceed)
+            return 1;
+        const result = await rollbackMigrations(scope, migrations);
+        if (result.rolledBack.length === 0) {
+            output.info(`Nothing to roll back for scope "${scope}".`);
+            return 0;
+        }
+        for (const name of result.rolledBack) {
+            output.success(`Rolled back: ${name}`);
+        }
+        output.info(`${result.rolledBack.length} migration(s) rolled back (scope "${scope}").`);
+        return 0;
+    }
+}

package/dist/cli/commands/migrate-status.d.ts

@@ -0,0 +1,16 @@
+import { Command, type CommandInput, type Output } from "@veap/kernel/cli";
+/**
+ * `veap migrate:status` — what is applied and what is still pending.
+ *
+ * Compares the migrations the application registered against the rows recorded
+ * in the `migrations` table for the scope, so the answer is about *this*
+ * application, not about the whole database. Rows recorded under the scope that
+ * the application no longer declares are reported separately: they are the
+ * signature of a renamed or deleted migration file, which `migrate` would
+ * otherwise never mention again.
+ */
+export declare class MigrateStatusCommand extends Command {
+    static signature: string;
+    static description: string;
+    handle(input: CommandInput, output: Output): Promise<number>;
+}

package/dist/cli/commands/migrate-status.js

@@ -0,0 +1,79 @@
+import { Command } from "@veap/kernel/cli";
+import { getKnex } from "../../connection.js";
+import { hasDatabaseConnection, resolveRegisteredMigrations, resolveScope, } from "../migrations.js";
+/** `executed_at` comes back as a Date, an epoch number or a string, per driver. */
+function formatRanAt(value) {
+    if (value === null || value === undefined)
+        return "—";
+    const date = value instanceof Date
+        ? value
+        : typeof value === "number"
+            ? new Date(value)
+            : undefined;
+    if (date && !Number.isNaN(date.getTime())) {
+        return date.toISOString().replace("T", " ").slice(0, 19);
+    }
+    const text = String(value).trim();
+    return text === "" ? "—" : text.replace("T", " ").slice(0, 19);
+}
+/**
+ * `veap migrate:status` — what is applied and what is still pending.
+ *
+ * Compares the migrations the application registered against the rows recorded
+ * in the `migrations` table for the scope, so the answer is about *this*
+ * application, not about the whole database. Rows recorded under the scope that
+ * the application no longer declares are reported separately: they are the
+ * signature of a renamed or deleted migration file, which `migrate` would
+ * otherwise never mention again.
+ */
+export class MigrateStatusCommand extends Command {
+    static signature = "migrate:status {--scope=app : Migration scope to inspect}";
+    static description = "Show the status of the application migrations";
+    async handle(input, output) {
+        const scope = resolveScope(input);
+        const migrations = await resolveRegisteredMigrations(this.context.container);
+        if (!hasDatabaseConnection()) {
+            output.error("No database connection is available. Set DATABASE_URL (or register DatabaseServiceProvider) before reading the migration status.");
+            return 1;
+        }
+        const knex = getKnex();
+        const recorded = (await knex.schema.hasTable("migrations"))
+            ? await knex("migrations")
+                .select("name", "batch", "executed_at")
+                .where("scope", scope)
+            : [];
+        const byName = new Map(recorded.map((row) => [row.name, row]));
+        const rows = [];
+        let ran = 0;
+        let pending = 0;
+        for (const migration of migrations) {
+            const row = byName.get(migration.name);
+            if (row) {
+                ran += 1;
+                rows.push([
+                    migration.name,
+                    "Ran",
+                    String(row.batch),
+                    formatRanAt(row.executed_at),
+                ]);
+                continue;
+            }
+            pending += 1;
+            rows.push([migration.name, "Pending", "—", "—"]);
+        }
+        if (rows.length === 0) {
+            output.info(`No application migrations are registered for scope "${scope}".`);
+        }
+        else {
+            output.table(["Migration", "Status", "Batch", "Ran at"], rows);
+            output.info(`${ran} ran, ${pending} pending (scope "${scope}").`);
+        }
+        const unknown = recorded.filter((row) => !migrations.some((migration) => migration.name === row.name));
+        if (unknown.length > 0) {
+            output.warn(`${unknown.length} migration(s) recorded for scope "${scope}" are not part of this application: ${unknown
+                .map((row) => row.name)
+                .join(", ")}.`);
+        }
+        return 0;
+    }
+}

package/dist/cli/commands/migrate.d.ts

@@ -0,0 +1,13 @@
+import { Command, type CommandInput, type Output } from "@veap/kernel/cli";
+/**
+ * `veap migrate` — applies every pending application migration, in one batch.
+ *
+ * In production the command asks before touching the database; `--force` answers
+ * that question for an unattended run, and `--no-interaction` without `--force`
+ * resolves it to "no" instead of hanging.
+ */
+export declare class MigrateCommand extends Command {
+    static signature: string;
+    static description: string;
+    handle(input: CommandInput, output: Output): Promise<number>;
+}

package/dist/cli/commands/migrate.js

@@ -0,0 +1,40 @@
+import { Command } from "@veap/kernel/cli";
+import { runMigrations } from "../../migrations/runner.js";
+import { confirmToProceed } from "../confirmation.js";
+import { hasDatabaseConnection, resolveRegisteredMigrations, resolveScope, } from "../migrations.js";
+/**
+ * `veap migrate` — applies every pending application migration, in one batch.
+ *
+ * In production the command asks before touching the database; `--force` answers
+ * that question for an unattended run, and `--no-interaction` without `--force`
+ * resolves it to "no" instead of hanging.
+ */
+export class MigrateCommand extends Command {
+    static signature = "migrate {--scope=app : Migration scope to run}";
+    static description = "Run the pending application migrations";
+    async handle(input, output) {
+        const scope = resolveScope(input);
+        const migrations = await resolveRegisteredMigrations(this.context.container);
+        if (migrations.length === 0) {
+            output.warn("No application migrations are registered. Add them to the application with `.withMigrations(appMigrations)`.");
+            return 0;
+        }
+        if (!hasDatabaseConnection()) {
+            output.error("No database connection is available. Set DATABASE_URL (or register DatabaseServiceProvider) before running migrations.");
+            return 1;
+        }
+        const proceed = await confirmToProceed(this.context, output, "Run the pending migrations");
+        if (!proceed)
+            return 1;
+        const result = await runMigrations(scope, migrations);
+        if (result.ran.length === 0) {
+            output.info(`Nothing to migrate for scope "${scope}".`);
+            return 0;
+        }
+        for (const name of result.ran) {
+            output.success(`Migrated: ${name}`);
+        }
+        output.info(`${result.ran.length} migration(s) applied in batch ${result.batch} (scope "${scope}").`);
+        return 0;
+    }
+}

package/dist/cli/confirmation.d.ts

@@ -0,0 +1,14 @@
+import type { CommandContext, Output } from "@veap/kernel/cli";
+/**
+ * The gate every command that changes the database goes through.
+ *
+ * Outside production it stays silent: `veap migrate` on a developer machine is a
+ * routine step and should not need a confirmation. Inside production the command
+ * asks first, and `--force` is how an unattended run says yes — a pipeline runs
+ * `veap migrate --force`. Passing `--no-interaction` without `--force` resolves
+ * the prompt to its default ("no"), so an unattended run can never touch
+ * production data by accident, and it can never hang waiting for input either.
+ */
+export declare function confirmToProceed(context: CommandContext, output: Output, 
+/** Sentence describing the action, e.g. "Run the pending migrations". */
+action: string): Promise<boolean>;

package/dist/cli/confirmation.js

@@ -0,0 +1,26 @@
+/** Environments in which changing the database asks for a confirmation first. */
+const GUARDED_ENVIRONMENTS = new Set(["production", "prod"]);
+/**
+ * The gate every command that changes the database goes through.
+ *
+ * Outside production it stays silent: `veap migrate` on a developer machine is a
+ * routine step and should not need a confirmation. Inside production the command
+ * asks first, and `--force` is how an unattended run says yes — a pipeline runs
+ * `veap migrate --force`. Passing `--no-interaction` without `--force` resolves
+ * the prompt to its default ("no"), so an unattended run can never touch
+ * production data by accident, and it can never hang waiting for input either.
+ */
+export async function confirmToProceed(context, output, 
+/** Sentence describing the action, e.g. "Run the pending migrations". */
+action) {
+    if (context.flags.force)
+        return true;
+    if (!GUARDED_ENVIRONMENTS.has(context.env))
+        return true;
+    // No quotes around the environment name on purpose: this question is also
+    // rendered inside the non-TTY error message, where nested quotes read badly.
+    const confirmed = await output.confirm(`The application is running in ${context.env}. ${action}?`, { default: false });
+    if (!confirmed)
+        output.warn("Cancelled.");
+    return confirmed;
+}

package/dist/cli/migrations.d.ts

@@ -0,0 +1,20 @@
+import type { Container } from "@veap/kernel";
+import type { CommandInput } from "@veap/kernel/cli";
+/**
+ * Tokens a host application publishes its migration list under: the explicit
+ * `APP_MIGRATIONS` symbol or the string alias used by older scaffolds.
+ */
+export declare const MIGRATION_TOKENS: readonly [import("@veap/kernel").Token<any[]>, "AppMigrations"];
+/** Default scope every migration command operates on. */
+export declare const DEFAULT_MIGRATION_SCOPE = "app";
+/** The scope a migration command was asked for (`--scope`, default `app`). */
+export declare function resolveScope(input: CommandInput): string;
+/**
+ * The migration list the host application registered, if any.
+ *
+ * Read from the container, which is where `.withMigrations(appMigrations)` puts
+ * it, so no command has to guess how a project declares its migrations.
+ */
+export declare function resolveRegisteredMigrations(container: Container): Promise<any[]>;
+/** `true` when `DatabaseServiceProvider` booted and a Knex instance exists. */
+export declare function hasDatabaseConnection(): boolean;

package/dist/cli/migrations.js

@@ -0,0 +1,41 @@
+import { getKnex } from "../connection.js";
+import { APP_MIGRATIONS } from "../tokens.js";
+/**
+ * Tokens a host application publishes its migration list under: the explicit
+ * `APP_MIGRATIONS` symbol or the string alias used by older scaffolds.
+ */
+export const MIGRATION_TOKENS = [APP_MIGRATIONS, "AppMigrations"];
+/** Default scope every migration command operates on. */
+export const DEFAULT_MIGRATION_SCOPE = "app";
+/** The scope a migration command was asked for (`--scope`, default `app`). */
+export function resolveScope(input) {
+    const scope = input.option("scope");
+    return typeof scope === "string" && scope.trim() !== ""
+        ? scope.trim()
+        : DEFAULT_MIGRATION_SCOPE;
+}
+/**
+ * The migration list the host application registered, if any.
+ *
+ * Read from the container, which is where `.withMigrations(appMigrations)` puts
+ * it, so no command has to guess how a project declares its migrations.
+ */
+export async function resolveRegisteredMigrations(container) {
+    for (const token of MIGRATION_TOKENS) {
+        if (!container.has(token))
+            continue;
+        const migrations = await container.resolve(token);
+        if (Array.isArray(migrations) && migrations.length > 0)
+            return migrations;
+    }
+    return [];
+}
+/** `true` when `DatabaseServiceProvider` booted and a Knex instance exists. */
+export function hasDatabaseConnection() {
+    try {
+        return Boolean(getKnex());
+    }
+    catch {
+        return false;
+    }
+}

package/dist/migration-provider.d.ts

@@ -1,7 +1,15 @@
 import { ServiceProvider } from "@veap/kernel";
+import type { CommandEntry } from "@veap/kernel/cli";
 export declare class MigrationServiceProvider extends ServiceProvider {
     private migrations?;
     constructor(container: any, migrations?: any[]);
+    /**
+     * Migration commands, harvested by the console for the host application:
+     * `veap make:migration` scaffolds one, `veap migrate` applies the pending
+     * ones, `veap migrate:status` reports them and `veap migrate:rollback` undoes
+     * the last batch.
+     */
+    commands(): CommandEntry[];
     register(): void;
     boot(): Promise<void>;
 }

package/dist/migration-provider.js

@@ -1,4 +1,8 @@
 import { ServiceProvider } from "@veap/kernel";
+import { MakeMigrationCommand } from "./cli/commands/make-migration.js";
+import { MigrateCommand } from "./cli/commands/migrate.js";
+import { MigrateRollbackCommand } from "./cli/commands/migrate-rollback.js";
+import { MigrateStatusCommand } from "./cli/commands/migrate-status.js";
 import { runMigrations } from "./migrations/runner.js";
 import { APP_MIGRATIONS } from "./tokens.js";
 export class MigrationServiceProvider extends ServiceProvider {
@@ -7,6 +11,20 @@ export class MigrationServiceProvider extends ServiceProvider {
         super(container);
         this.migrations = migrations;
     }
+    /**
+     * Migration commands, harvested by the console for the host application:
+     * `veap make:migration` scaffolds one, `veap migrate` applies the pending
+     * ones, `veap migrate:status` reports them and `veap migrate:rollback` undoes
+     * the last batch.
+     */
+    commands() {
+        return [
+            MakeMigrationCommand,
+            MigrateCommand,
+            MigrateStatusCommand,
+            MigrateRollbackCommand,
+        ];
+    }
     register() {
         if (this.migrations?.length) {
             this.container.register({
@@ -20,6 +38,11 @@ export class MigrationServiceProvider extends ServiceProvider {
         }
     }
     async boot() {
+        // Under the console (`VEAP_CLI=1`) migrations are an explicit action: the
+        // `veap migrate` command runs them, and every other command — `list`
+        // included — must leave the database untouched.
+        if (process.env.VEAP_CLI === "1")
+            return;
         let appMigrations = this.migrations;
         if (!appMigrations?.length) {
             if (this.container.has(APP_MIGRATIONS)) {

package/dist/migrations/generator.d.ts

@@ -1,4 +1,13 @@
-export declare function generateMigration(name: string, targetDir?: string): Promise<{
+export interface GeneratedMigration {
+    /** Timestamped file name without the extension, e.g. `20261014120000_create_posts_table`. */
     fileName: string;
+    /** Absolute path of the written migration file. */
     filePath: string;
-}>;
+}
+/**
+ * Writes a new migration file and regenerates the directory's `index.ts`.
+ *
+ * Used by the `veap make:migration` command; kept free of the console so it can
+ * be called from anywhere (tests, generators, plugins).
+ */
+export declare function generateMigration(name: string, targetDir?: string): Promise<GeneratedMigration>;

package/dist/migrations/generator.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { AppError } from "@veap/kernel";
 const stub = `import type { Schema } from "@veap/database";
 
 export default {
@@ -16,6 +17,8 @@ export default {
   },
 };
 `;
+/** Migration names end up in a file name and in a table name, so keep them boring. */
+const NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
 async function updateIndexFile(migrationsDir) {
     const indexFile = path.join(migrationsDir, "index.ts");
     const files = await fs.readdir(migrationsDir);
@@ -23,28 +26,50 @@ async function updateIndexFile(migrationsDir) {
         .filter((f) => f.endsWith(".ts") && f !== "index.ts")
         .sort();
     const imports = [];
+    const normalisers = [];
     const exports = [];
     for (const file of migrationFiles) {
         const name = file.replace(".ts", "");
         const varName = `m${name.replace(/[^a-zA-Z0-9]/g, "_")}`;
-        imports.push(`import { default as ${varName} } from "./${name}";`);
+        // A migration is either the scaffolded `export default { … }` object or a
+        // module with named `name`/`up`/`down` exports (every hand-written migration
+        // in the shipped apps). Importing the namespace and unwrapping `default`
+        // keeps both working, so regenerating the index never silently breaks a
+        // migration that was written by hand.
+        imports.push(`import * as ${varName}Raw from "./${name}";`);
+        normalisers.push(`const ${varName} = (${varName}Raw as { default?: unknown }).default ?? ${varName}Raw;`);
         exports.push(varName);
     }
     const content = `// This file is auto-generated by Veap CLI. Do not edit manually.
 ${imports.join("\n")}
 
+${normalisers.join("\n")}
+
 export const appMigrations = [
   ${exports.join(",\n  ")}
 ];
 `;
     await fs.writeFile(indexFile, content, "utf-8");
 }
+/**
+ * Writes a new migration file and regenerates the directory's `index.ts`.
+ *
+ * Used by the `veap make:migration` command; kept free of the console so it can
+ * be called from anywhere (tests, generators, plugins).
+ */
 export async function generateMigration(name, targetDir) {
+    const trimmed = (name ?? "").trim();
+    if (!trimmed) {
+        throw AppError.BadRequest("A migration name is required.");
+    }
+    if (!NAME_PATTERN.test(trimmed)) {
+        throw AppError.BadRequest(`The migration name "${trimmed}" may only contain letters, digits and underscores.`);
+    }
     const timestamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
-    const fileName = `${timestamp}_${name}`;
-    let tableName = name;
-    if (name.startsWith("create_") && name.endsWith("_table")) {
-        tableName = name.replace("create_", "").replace("_table", "");
+    const fileName = `${timestamp}_${trimmed}`;
+    let tableName = trimmed;
+    if (trimmed.startsWith("create_") && trimmed.endsWith("_table")) {
+        tableName = trimmed.replace("create_", "").replace("_table", "");
     }
     const content = stub
         .replace(/{{name}}/g, fileName)
@@ -52,6 +77,16 @@ export async function generateMigration(name, targetDir) {
     const migrationsDir = targetDir || path.join(process.cwd(), "migrations");
     await fs.mkdir(migrationsDir, { recursive: true });
     const filePath = path.join(migrationsDir, `${fileName}.ts`);
+    // Two runs inside the same second would otherwise overwrite the first file.
+    try {
+        await fs.access(filePath);
+        throw AppError.Conflict(`The migration "${fileName}" already exists at ${filePath}.`);
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        // ENOENT: nothing to overwrite, keep going.
+    }
     await fs.writeFile(filePath, content, "utf-8");
     await updateIndexFile(migrationsDir);
     return { fileName, filePath };

package/dist/migrations/runner.d.ts

@@ -4,9 +4,34 @@ export interface Migration {
     up: (db: any, schema: Schema) => Promise<void>;
     down?: (db: any, schema: Schema) => Promise<void>;
 }
-export declare function runMigrations(scope: string, migrations: Migration[]): Promise<void>;
+/**
+ * What one `runMigrations()` call actually did.
+ *
+ * Returned instead of a bare `void` so a caller — `veap migrate` above all —
+ * can report the run instead of guessing: an empty `ran` means nothing was
+ * pending, and `batch` is only set when migrations were applied.
+ */
+export interface MigrationRunResult {
+    scope: string;
+    /** Names of the migrations applied by this call, in execution order. */
+    ran: string[];
+    /** Batch the migrations of this call were recorded under. */
+    batch?: number;
+}
+export declare function runMigrations(scope: string, migrations: Migration[]): Promise<MigrationRunResult>;
+/**
+ * What one `rollbackMigrations()` call actually undid.
+ *
+ * Mirrors {@link MigrationRunResult} so `veap migrate:rollback` can report the
+ * reversed migrations instead of claiming a rollback that never happened.
+ */
+export interface MigrationRollbackResult {
+    scope: string;
+    /** Names of the migrations rolled back, in the order their `down()` ran. */
+    rolledBack: string[];
+}
 /**
  * Modern static migration rollback runner.
  * Reverts migrations in reverse order.
  */
-export declare function rollbackMigrations(scope: string, migrations: Migration[]): Promise<void>;
+export declare function rollbackMigrations(scope: string, migrations: Migration[]): Promise<MigrationRollbackResult>;

package/dist/migrations/runner.js

@@ -67,17 +67,18 @@ function createMigrationDbAdapter(trx) {
     });
 }
 export async function runMigrations(scope, migrations) {
+    let result = { scope, ran: [] };
     if (migrations.length === 0)
-        return;
+        return result;
     let knex;
     try {
         knex = getKnex();
     }
     catch {
-        return;
+        return result;
     }
     if (!knex)
-        return;
+        return result;
     await ensureMigrationsTable(knex);
     await knex.transaction(async (tx) => {
         // Acquire advisory lock only if running on PostgreSQL
@@ -118,33 +119,42 @@ export async function runMigrations(scope, migrations) {
                 throw error; // Rollback the whole batch on error
             }
         }
+        // Reported only once the whole batch is in: an error above rolls the
+        // transaction back, so nothing was applied and `ran` stays empty.
+        result = { scope, ran: pending.map((migration) => migration.name), batch };
     });
+    return result;
 }
 /**
  * Modern static migration rollback runner.
  * Reverts migrations in reverse order.
  */
 export async function rollbackMigrations(scope, migrations) {
+    let result = { scope, rolledBack: [] };
     if (migrations.length === 0)
-        return;
+        return result;
     let knex;
     try {
         knex = getKnex();
     }
     catch {
-        return;
+        return result;
     }
     if (!knex)
-        return;
+        return result;
     await ensureMigrationsTable(knex);
     await knex.transaction(async (tx) => {
         // Acquire advisory lock only if running on PostgreSQL
         await acquireAdvisoryLockIfPostgres(tx, knex);
-        // 1. Get executed migrations for this scope ordered by batch desc
+        // 1. The last batch first, and inside it the most recently executed
+        // migration first: a rollback has to walk the batch backwards, otherwise a
+        // table added to an existing one would be dropped before its own foreign
+        // keys, or after a table that depends on it.
         const executed = await tx("migrations")
-            .select("name", "batch")
+            .select("name", "batch", "executed_at")
             .where("scope", scope)
-            .orderBy("batch", "desc");
+            .orderBy("batch", "desc")
+            .orderBy("executed_at", "desc");
         if (executed.length === 0) {
             debug("veap:migration", `No migrations to rollback for ${scope}.`);
             return;
@@ -156,7 +166,7 @@ export async function rollbackMigrations(scope, migrations) {
             .map((m) => m.name);
         const dbAdapter = createMigrationDbAdapter(tx);
         const schema = new Schema(tx);
-        // Rollback in reverse order
+        const rolledBack = [];
         for (const name of toRollbackNames) {
             const migration = migrations.find((m) => m.name === name);
             if (migration && migration.down) {
@@ -167,6 +177,7 @@ export async function rollbackMigrations(scope, migrations) {
                         .where("name", name)
                         .where("scope", scope)
                         .delete();
+                    rolledBack.push(name);
                     debug("veap:migration", `[${scope}] Rolled back ${name}.`);
                 }
                 catch (error) {
@@ -175,5 +186,9 @@ export async function rollbackMigrations(scope, migrations) {
                 }
             }
         }
+        // Only reported once the transaction committed: an error above rolls it
+        // back, so nothing was undone.
+        result = { scope, rolledBack };
     });
+    return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veap/database",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Eloquent-like Active Record ORM powered by Knex with AsyncLocalStorage transactions",
   "bugs": "https://github.com/veapjs/veap-database/issues",
   "repository": {
@@ -36,7 +36,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@veap/kernel": "^0.1.1",
+    "@veap/kernel": "^0.1.4",
     "better-sqlite3": "^13.0.3",
     "knex": "^3.3.0"
   },