sailfork / t3code-github / .repos/ alchemy-effect/ packages/ sql/ src/ Migrations/ Format.ts

import * as Data from "effect/Data";
import type * as Effect from "effect/Effect";

/**
 * `googlesql` is Cloud Spanner's GoogleSQL dialect. Spanner's PostgreSQL
 * dialect is `postgres` with `migrationTableId: "spanner"` and
 * `defaultSchema: "public"`.
 */
export type MigrationDialect = "postgres" | "mysql" | "sqlite" | "googlesql";

/**
 * A single migration read from disk, normalized across directory layouts.
 */
export interface MigrationRecord {
  /**
   * The bookkeeping key used for applied-detection. Layout-dependent: the
   * directory name for drizzle-kit/Prisma-layout dirs
   * (`20260721033159_init`), the relative file path for flat dirs
   * (`0001_users.sql`).
   */
  name: string;
  /** sha256 hex of the raw file content. */
  hash: string;
  /**
   * Millis derived from a 14-digit `YYYYMMDDHHMMSS` prefix when present.
   */
  createdAtMillis: number | undefined;
  /** Raw file content. */
  sql: string;
  /** Individual statements (split on `--> statement-breakpoint`). */
  statements: string[];
}

/**
 * The minimal query surface the migration flow needs from its target
 * database. Each database resource adapts its native access path (the D1
 * HTTP API, a `pg.Client` over a Planetscale temp role, a `mysql2`
 * connection, the local workerd D1 tunnel) into this shape once.
 */
export interface SqlExecutor {
  readonly dialect: MigrationDialect;
  /**
   * PostgreSQL targets without SERIAL key bookkeeping rows by UUID:
   * `uuid` generates a native uuid, `spanner` a varchar from
   * `spanner.generate_uuid()` (Spanner has neither SERIAL nor a uuid type).
   */
  readonly migrationTableId?: "uuid" | "spanner";
  /**
   * Schema to introspect when the target has no `current_schema()`
   * (Spanner's PostgreSQL dialect).
   */
  readonly defaultSchema?: string;
  /** False when DDL cannot commit atomically with history conversion. */
  readonly transactionalDdl?: boolean;
  /** Override atomic batches for targets requiring durable statement progress. */
  readonly applyMigration?: (
    record: MigrationRecord,
    bookkeeping: string,
  ) => Effect.Effect<void, MigrationError>;
  /**
   * Run a single query and return its rows as objects. `params` bind as
   * `?`/`$n` placeholders; adapters without native parameter support inline
   * them as SQL literals (see `inlineSqlParams`).
   */
  readonly query: (
    sql: string,
    params?: ReadonlyArray<unknown>,
  ) => Effect.Effect<Array<Record<string, unknown>>, MigrationError>;
  /**
   * Execute one or more statements as a unit — a transaction where the
   * target supports one (pg/mysql), a single batched query on D1 (which has
   * no transactions over HTTP).
   */
  readonly batch: (statements: ReadonlyArray<string>) => Effect.Effect<void, MigrationError>;
}

/** A migration failed to read, convert, or apply. */
export class MigrationError extends Data.TaggedError("MigrationError")<{
  message: string;
  cause?: unknown;
  /**
   * The request may never have reached the database (a 5xx, a timeout, a
   * reset socket). A failed batch marked transient is resent if the
   * applied-migrations table shows it did not land.
   */
  transient?: boolean;
}> {}

/**
 * The migrations directory uses drizzle-kit's pre-v1 layout
 * (`meta/_journal.json`). The fix is upstream: `drizzle-kit up`.
 */
export class DrizzleV0LayoutError extends Data.TaggedError("DrizzleV0LayoutError")<{
  dir: string;
  message: string;
}> {}

/**
 * A row recorded in an applied-migrations table (ours, or a foreign one
 * being converted) matches no local migration file. Guessing would corrupt
 * history, so this is a hard error — migrations were applied to the
 * database that the local environment does not have.
 */
export class MigrationHistoryConflictError extends Data.TaggedError(
  "MigrationHistoryConflictError",
)<{
  table: string;
  unmatched: ReadonlyArray<string>;
  message: string;
}> {}

/**
 * Already-applied migration files were edited or removed. History is
 * forward-only: add a new migration instead of rewriting files that have
 * already run. PlanetScale development branches replace rather than
 * raising this; production branches (and in-place apply on any target)
 * fail with it.
 */
export class RewrittenMigrationHistoryError extends Data.TaggedError(
  "RewrittenMigrationHistoryError",
)<{
  changed: ReadonlyArray<string>;
  removed: ReadonlyArray<string>;
  message: string;
}> {}

/** Human-readable `changed X; removed Y` fragment for rewritten-history errors. */
export const describeRewrittenHistory = (options: {
  changed: ReadonlyArray<string>;
  removed: ReadonlyArray<string>;
}): string =>
  [
    options.changed.length > 0 ? `changed ${options.changed.join(", ")}` : undefined,
    options.removed.length > 0 ? `removed ${options.removed.join(", ")}` : undefined,
  ]
    .filter((part): part is string => part !== undefined)
    .join("; ");

export type MigrationApplyError =
  | MigrationError
  | MigrationHistoryConflictError
  | RewrittenMigrationHistoryError;