ref(migrations): Inject the database adapter

Expose the exact host database adapter through MigrationContextV1 instead of reconstructing a partial SQL capability.

Rebuild the SQL-heavy frozen migrations without connection setup and driver implementations so migrations retain transformation logic without duplicating database infrastructure.

Co-Authored-By: GPT-5.6 Codex <noreply@openai.com>

Author: dcramer

packages/junior-migrations/README.md

@@ -30,7 +30,9 @@ then replaces the empty SQL file with a `MigrationV1` TypeScript scaffold.
 Drizzle Kit remains the supported authoring tool. Drizzle ORM's stock
 `migrate()` function is not a supported executor for mixed journals because it
 requires every entry to have a SQL file. Call `runMigrationJournal` instead and
-provide the SQL, state, loader, and locking capabilities owned by the host.
+provide the host database adapter, state adapter, and TypeScript loader. The
+same database adapter drives the journal ledger and is exposed as
+`context.database`, so migration files never own connection or driver setup.
 
 The runner rejects runtime imports of application source, relative modules,
 and `@sentry/junior`. External package imports are allowed when the migration

packages/junior-migrations/src/index.ts

@@ -5,13 +5,13 @@ export type { GenerateTypeScriptMigrationOptions } from "./generate";
 export type { RunMigrationJournalOptions } from "./runner";
 export type {
   MigrationContextV1,
+  MigrationDatabaseAdapter,
   MigrationJsonValue,
   MigrationJournalEntry,
   MigrationLockV1,
   MigrationProgressV1,
   MigrationRedisV1,
   MigrationRunResult,
-  MigrationSqlExecutor,
   MigrationStateV1,
   MigrationV1,
   ResolvedMigration,

packages/junior-migrations/src/runner.ts

@@ -1,7 +1,7 @@
 import type {
   MigrationContextV1,
+  MigrationDatabaseAdapter,
   MigrationRunResult,
-  MigrationSqlExecutor,
   MigrationV1,
   ResolvedMigration,
   TypeScriptMigrationLoader,
@@ -17,7 +17,7 @@ interface MigrationRow {
 
 interface RunMigrationJournalBaseOptions {
   beforeRun?: () => Promise<void>;
-  executor: MigrationSqlExecutor;
+  executor: MigrationDatabaseAdapter;
   migrationsFolder: string;
   migrationsTable: string;
 }
@@ -54,7 +54,7 @@ function qualifiedTable(table: string): string {
 }
 
 async function ensureMigrationTable(
-  executor: MigrationSqlExecutor,
+  executor: MigrationDatabaseAdapter,
   table: string,
 ): Promise<void> {
   const qualified = qualifiedTable(table);
@@ -90,7 +90,7 @@ CREATE TABLE IF NOT EXISTS ${qualified} (
 }
 
 async function migrationRows(
-  executor: MigrationSqlExecutor,
+  executor: MigrationDatabaseAdapter,
   table: string,
 ): Promise<Map<number, MigrationRow>> {
   const rows = await executor.query<MigrationRow>(`
@@ -107,7 +107,7 @@ ORDER BY created_at ASC, id ASC
 }
 
 async function adoptLegacySqlPrefix(args: {
-  executor: MigrationSqlExecutor;
+  executor: MigrationDatabaseAdapter;
   migrations: readonly ResolvedMigration[];
   rows: Map<number, MigrationRow>;
   table: string;
@@ -160,7 +160,7 @@ function migrationV1(value: unknown, tag: string): MigrationV1 {
 }
 
 async function runSqlMigration(args: {
-  executor: MigrationSqlExecutor;
+  executor: MigrationDatabaseAdapter;
   migration: ResolvedMigration;
   table: string;
 }): Promise<void> {
@@ -179,7 +179,7 @@ async function runSqlMigration(args: {
 
 async function runTypeScriptMigration(args: {
   createContext: RunAllMigrationJournalOptions["createContext"];
-  executor: MigrationSqlExecutor;
+  executor: MigrationDatabaseAdapter;
   loadTypeScript: TypeScriptMigrationLoader;
   migration: ResolvedMigration;
   row: MigrationRow | undefined;

packages/junior-migrations/src/types.ts

@@ -1,11 +1,13 @@
-/** SQL capabilities available to the mixed migration runner. */
-export interface MigrationSqlExecutor {
+/** Database adapter used by the mixed migration runner and TypeScript entries. */
+export interface MigrationDatabaseAdapter {
+  db(): unknown;
   execute(statement: string, parameters?: readonly unknown[]): Promise<void>;
   query<T = unknown>(
     statement: string,
     parameters?: readonly unknown[],
   ): Promise<T[]>;
   transaction<T>(callback: () => Promise<T>): Promise<T>;
+  withLock<T>(lockName: string, callback: () => Promise<T>): Promise<T>;
   withMigrationLock<T>(
     migrationTable: string,
     callback: () => Promise<T>,
@@ -58,12 +60,10 @@ export type MigrationJsonValue =
 
 /** Permanent capability contract for apiVersion 1 migrations. */
 export interface MigrationContextV1 {
+  database: MigrationDatabaseAdapter;
   log(message: string): void;
   progress: MigrationProgressV1;
   redis?: MigrationRedisV1;
-  sql: Pick<MigrationSqlExecutor, "execute" | "query" | "transaction"> & {
-    db(): unknown;
-  };
   state: MigrationStateV1;
 }
 

packages/junior-migrations/tests/runner.test.ts

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { runMigrationJournal } from "../src/runner";
 import type {
   MigrationContextV1,
-  MigrationSqlExecutor,
+  MigrationDatabaseAdapter,
   MigrationV1,
 } from "../src/types";
 
@@ -16,7 +16,7 @@ interface StoredRow {
   status: string | null;
 }
 
-class FakeExecutor implements MigrationSqlExecutor {
+class FakeExecutor implements MigrationDatabaseAdapter {
   readonly rows = new Map<number, StoredRow>();
   readonly statements: string[] = [];
 
@@ -89,6 +89,10 @@ class FakeExecutor implements MigrationSqlExecutor {
   ): Promise<T> {
     return await callback();
   }
+
+  async withLock<T>(_lockName: string, callback: () => Promise<T>): Promise<T> {
+    return await callback();
+  }
 }
 
 function fakeMigrationState(): MigrationContextV1["state"] {
@@ -166,7 +170,7 @@ describe("runMigrationJournal", () => {
         createContext: ({ progress }) => ({
           log: () => {},
           progress,
-          sql: executor,
+          database: executor,
           state: fakeMigrationState(),
         }),
       }),
@@ -186,7 +190,7 @@ describe("runMigrationJournal", () => {
         createContext: ({ progress }) => ({
           log: () => {},
           progress,
-          sql: executor,
+          database: executor,
           state: fakeMigrationState(),
         }),
       }),
@@ -236,7 +240,7 @@ describe("runMigrationJournal", () => {
       }) => ({
         log: () => {},
         progress,
-        sql: executor,
+        database: executor,
         state: fakeMigrationState(),
       }),
     };

packages/junior-scheduler/migrations/0002_scheduler_state_to_sql.ts

@@ -121,7 +121,7 @@ const migration = {
         continue;
       }
       tasks.push(task);
-      const [stored] = await context.sql.query<{ id: string }>(
+      const [stored] = await context.database.query<{ id: string }>(
         "SELECT id FROM junior_scheduler_tasks WHERE id = $1 LIMIT 1",
         [id],
       );
@@ -130,7 +130,7 @@ const migration = {
         continue;
       }
       const destination = record(task.destination)!;
-      await context.sql.execute(
+      await context.database.execute(
         `INSERT INTO junior_scheduler_tasks
          (id, team_id, status, next_run_at_ms, run_now_at_ms, created_at_ms, record)
          VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)
@@ -171,15 +171,15 @@ const migration = {
     }
 
     for (const run of runs) {
-      const [stored] = await context.sql.query<{ id: string }>(
+      const [stored] = await context.database.query<{ id: string }>(
         "SELECT id FROM junior_scheduler_runs WHERE id = $1 LIMIT 1",
         [run.id],
       );
       if (stored) {
         existing += 1;
         continue;
       }
-      await context.sql.execute(
+      await context.database.execute(
         `INSERT INTO junior_scheduler_runs
          (id, task_id, status, scheduled_for_ms, record)
          VALUES ($1, $2, $3, $4, $5::jsonb)