The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Data from "effect/Data"; |
| 2 | import type * as Effect from "effect/Effect"; |
| 3 | |
| 4 | /** |
| 5 | * `googlesql` is Cloud Spanner's GoogleSQL dialect. Spanner's PostgreSQL |
| 6 | * dialect is `postgres` with `migrationTableId: "spanner"` and |
| 7 | * `defaultSchema: "public"`. |
| 8 | */ |
| 9 | export type MigrationDialect = "postgres" | "mysql" | "sqlite" | "googlesql"; |
| 10 | |
| 11 | /** |
| 12 | * A single migration read from disk, normalized across directory layouts. |
| 13 | */ |
| 14 | export interface MigrationRecord { |
| 15 | /** |
| 16 | * The bookkeeping key used for applied-detection. Layout-dependent: the |
| 17 | * directory name for drizzle-kit/Prisma-layout dirs |
| 18 | * (`20260721033159_init`), the relative file path for flat dirs |
| 19 | * (`0001_users.sql`). |
| 20 | */ |
| 21 | name: string; |
| 22 | /** sha256 hex of the raw file content. */ |
| 23 | hash: string; |
| 24 | /** |
| 25 | * Millis derived from a 14-digit `YYYYMMDDHHMMSS` prefix when present. |
| 26 | */ |
| 27 | createdAtMillis: number | undefined; |
| 28 | /** Raw file content. */ |
| 29 | sql: string; |
| 30 | /** Individual statements (split on `--> statement-breakpoint`). */ |
| 31 | statements: string[]; |
| 32 | } |
| 33 | |
| 34 | /** |
| 35 | * The minimal query surface the migration flow needs from its target |
| 36 | * database. Each database resource adapts its native access path (the D1 |
| 37 | * HTTP API, a `pg.Client` over a Planetscale temp role, a `mysql2` |
| 38 | * connection, the local workerd D1 tunnel) into this shape once. |
| 39 | */ |
| 40 | export interface SqlExecutor { |
| 41 | readonly dialect: MigrationDialect; |
| 42 | /** |
| 43 | * PostgreSQL targets without SERIAL key bookkeeping rows by UUID: |
| 44 | * `uuid` generates a native uuid, `spanner` a varchar from |
| 45 | * `spanner.generate_uuid()` (Spanner has neither SERIAL nor a uuid type). |
| 46 | */ |
| 47 | readonly migrationTableId?: "uuid" | "spanner"; |
| 48 | /** |
| 49 | * Schema to introspect when the target has no `current_schema()` |
| 50 | * (Spanner's PostgreSQL dialect). |
| 51 | */ |
| 52 | readonly defaultSchema?: string; |
| 53 | /** False when DDL cannot commit atomically with history conversion. */ |
| 54 | readonly transactionalDdl?: boolean; |
| 55 | /** Override atomic batches for targets requiring durable statement progress. */ |
| 56 | readonly applyMigration?: ( |
| 57 | record: MigrationRecord, |
| 58 | bookkeeping: string, |
| 59 | ) => Effect.Effect<void, MigrationError>; |
| 60 | /** |
| 61 | * Run a single query and return its rows as objects. `params` bind as |
| 62 | * `?`/`$n` placeholders; adapters without native parameter support inline |
| 63 | * them as SQL literals (see `inlineSqlParams`). |
| 64 | */ |
| 65 | readonly query: ( |
| 66 | sql: string, |
| 67 | params?: ReadonlyArray<unknown>, |
| 68 | ) => Effect.Effect<Array<Record<string, unknown>>, MigrationError>; |
| 69 | /** |
| 70 | * Execute one or more statements as a unit — a transaction where the |
| 71 | * target supports one (pg/mysql), a single batched query on D1 (which has |
| 72 | * no transactions over HTTP). |
| 73 | */ |
| 74 | readonly batch: (statements: ReadonlyArray<string>) => Effect.Effect<void, MigrationError>; |
| 75 | } |
| 76 | |
| 77 | /** A migration failed to read, convert, or apply. */ |
| 78 | export class MigrationError extends Data.TaggedError("MigrationError")<{ |
| 79 | message: string; |
| 80 | cause?: unknown; |
| 81 | /** |
| 82 | * The request may never have reached the database (a 5xx, a timeout, a |
| 83 | * reset socket). A failed batch marked transient is resent if the |
| 84 | * applied-migrations table shows it did not land. |
| 85 | */ |
| 86 | transient?: boolean; |
| 87 | }> {} |
| 88 | |
| 89 | /** |
| 90 | * The migrations directory uses drizzle-kit's pre-v1 layout |
| 91 | * (`meta/_journal.json`). The fix is upstream: `drizzle-kit up`. |
| 92 | */ |
| 93 | export class DrizzleV0LayoutError extends Data.TaggedError("DrizzleV0LayoutError")<{ |
| 94 | dir: string; |
| 95 | message: string; |
| 96 | }> {} |
| 97 | |
| 98 | /** |
| 99 | * A row recorded in an applied-migrations table (ours, or a foreign one |
| 100 | * being converted) matches no local migration file. Guessing would corrupt |
| 101 | * history, so this is a hard error — migrations were applied to the |
| 102 | * database that the local environment does not have. |
| 103 | */ |
| 104 | export class MigrationHistoryConflictError extends Data.TaggedError( |
| 105 | "MigrationHistoryConflictError", |
| 106 | )<{ |
| 107 | table: string; |
| 108 | unmatched: ReadonlyArray<string>; |
| 109 | message: string; |
| 110 | }> {} |
| 111 | |
| 112 | /** |
| 113 | * Already-applied migration files were edited or removed. History is |
| 114 | * forward-only: add a new migration instead of rewriting files that have |
| 115 | * already run. PlanetScale development branches replace rather than |
| 116 | * raising this; production branches (and in-place apply on any target) |
| 117 | * fail with it. |
| 118 | */ |
| 119 | export class RewrittenMigrationHistoryError extends Data.TaggedError( |
| 120 | "RewrittenMigrationHistoryError", |
| 121 | )<{ |
| 122 | changed: ReadonlyArray<string>; |
| 123 | removed: ReadonlyArray<string>; |
| 124 | message: string; |
| 125 | }> {} |
| 126 | |
| 127 | /** Human-readable `changed X; removed Y` fragment for rewritten-history errors. */ |
| 128 | export const describeRewrittenHistory = (options: { |
| 129 | changed: ReadonlyArray<string>; |
| 130 | removed: ReadonlyArray<string>; |
| 131 | }): string => |
| 132 | [ |
| 133 | options.changed.length > 0 ? `changed ${options.changed.join(", ")}` : undefined, |
| 134 | options.removed.length > 0 ? `removed ${options.removed.join(", ")}` : undefined, |
| 135 | ] |
| 136 | .filter((part): part is string => part !== undefined) |
| 137 | .join("; "); |
| 138 | |
| 139 | export type MigrationApplyError = |
| 140 | | MigrationError |
| 141 | | MigrationHistoryConflictError |
| 142 | | RewrittenMigrationHistoryError; |