alchemy 2.0.0-beta.41 → 2.0.0-beta.43

package/src/Planetscale/MySQL/MySQLMigrations.ts

@@ -0,0 +1,271 @@
+import * as ops from "@distilled.cloud/planetscale/Operations";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+import { createConnection, type Connection } from "mysql2/promise";
+import { listSqlFiles, readSqlFile, type SqlFile } from "../../Sql/SqlFile.ts";
+
+const MIGRATION_PASSWORD_TTL_SECONDS = 600;
+
+export class MySQLMigrationError extends Data.TaggedError(
+  "Planetscale::MySQLMigrationError",
+)<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+export interface MySQLMigrationTarget {
+  organization: string;
+  database: string;
+  branch: string;
+}
+
+export const runMySQLMigrations = (
+  target: MySQLMigrationTarget,
+  migrationsDir: string,
+  migrationsTable: string,
+) =>
+  Effect.gen(function* () {
+    const files = yield* listSqlFiles(migrationsDir);
+    if (files.length > 0) {
+      yield* applyMySQLMigrations({
+        target,
+        migrationsTable,
+        migrationsFiles: files,
+      });
+    }
+    const hashes: Record<string, string> = {};
+    for (const file of files) hashes[file.id] = file.hash;
+    return hashes;
+  });
+
+export const runMySQLImports = (
+  target: MySQLMigrationTarget,
+  importFiles: ReadonlyArray<string>,
+  rootDir: string,
+  previous: Record<string, string>,
+) =>
+  Effect.gen(function* () {
+    const hashes: Record<string, string> = { ...previous };
+    for (const filePath of importFiles) {
+      const file = yield* readSqlFile(rootDir, filePath);
+      if (previous[filePath] === file.hash) {
+        hashes[filePath] = file.hash;
+        continue;
+      }
+      yield* runMySQLSql(target, file.sql);
+      hashes[filePath] = file.hash;
+    }
+    const tracked = new Set(importFiles);
+    for (const key of Object.keys(hashes)) {
+      if (!tracked.has(key)) delete hashes[key];
+    }
+    return hashes;
+  });
+
+interface ApplyMigrationsOptions {
+  target: MySQLMigrationTarget;
+  migrationsTable: string;
+  migrationsFiles: ReadonlyArray<SqlFile>;
+}
+
+const applyMySQLMigrations = (options: ApplyMigrationsOptions) =>
+  withMySQLConnection(options.target, (connection) =>
+    Effect.gen(function* () {
+      const table = quoteMySQLIdentifier(options.migrationsTable);
+      yield* mysqlQuery(
+        connection,
+        `CREATE TABLE IF NOT EXISTS ${table} (
+           id varchar(255) NOT NULL PRIMARY KEY,
+           name varchar(1024) NOT NULL,
+           applied_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP
+         );`,
+      );
+
+      const applied = yield* mysqlQueryRows<{ name: string }>(
+        connection,
+        `SELECT name FROM ${table};`,
+      ).pipe(Effect.map((rows) => new Set(rows.map((row) => row.name))));
+      let nextSeq = yield* getNextMySQLSeq(connection, table);
+
+      for (const file of options.migrationsFiles) {
+        if (applied.has(file.id)) continue;
+        const migrationId = nextSeq.toString().padStart(5, "0");
+        nextSeq += 1;
+        yield* Effect.gen(function* () {
+          yield* mysqlQuery(connection, "START TRANSACTION");
+          for (const statement of splitMySQLStatements(file.sql)) {
+            yield* mysqlQuery(connection, statement);
+          }
+          yield* mysqlExecute(
+            connection,
+            `INSERT INTO ${table} (id, name) VALUES (?, ?);`,
+            [migrationId, file.id],
+          );
+          yield* mysqlQuery(connection, "COMMIT");
+        }).pipe(
+          Effect.catch((error) =>
+            mysqlQuery(connection, "ROLLBACK").pipe(
+              Effect.catch(() => Effect.void),
+              Effect.andThen(Effect.fail(error)),
+            ),
+          ),
+        );
+      }
+    }),
+  );
+
+const runMySQLSql = (target: MySQLMigrationTarget, sql: string) =>
+  withMySQLConnection(target, (connection) =>
+    Effect.gen(function* () {
+      for (const statement of splitMySQLStatements(sql)) {
+        yield* mysqlQuery(connection, statement);
+      }
+    }),
+  );
+
+// Drizzle (and other migration tools) emit `--> statement-breakpoint` as a
+// separator between statements. PlanetScale's Vitess parser rejects the `-->`
+// token ("syntax error at position 2") because MySQL line comments require
+// whitespace after `--`. Split on the marker and run each statement
+// individually so the connector never sees the breakpoint comment.
+const STATEMENT_BREAKPOINT = /\r?\n\s*-->\s*statement-breakpoint\s*\r?\n?/g;
+
+const splitMySQLStatements = (sql: string): string[] =>
+  sql
+    .split(STATEMENT_BREAKPOINT)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+const getNextMySQLSeq = (connection: Connection, table: string) =>
+  mysqlQueryRows<{ id: string }>(connection, `SELECT id FROM ${table};`).pipe(
+    Effect.map((rows) => {
+      let max = 0;
+      for (const { id } of rows) {
+        if (/^\d+$/.test(String(id))) {
+          max = Math.max(max, Number.parseInt(String(id), 10));
+        }
+      }
+      return max + 1;
+    }),
+  );
+
+const withMySQLConnection = <A, E, R>(
+  target: MySQLMigrationTarget,
+  use: (connection: Connection) => Effect.Effect<A, E, R>,
+) =>
+  withTemporaryMySQLPassword(target, (password) =>
+    Effect.acquireUseRelease(
+      Effect.tryPromise({
+        try: () =>
+          createConnection({
+            host: password.host,
+            user: password.username,
+            password: Redacted.value(password.password),
+            database: target.database,
+            multipleStatements: true,
+            ssl: { rejectUnauthorized: true },
+          }),
+        catch: toMigrationError,
+      }),
+      use,
+      (connection) =>
+        Effect.tryPromise({
+          try: () => connection.end(),
+          catch: toMigrationError,
+        }).pipe(Effect.catch(() => Effect.void)),
+    ),
+  );
+
+const withTemporaryMySQLPassword = <A, E, R>(
+  target: MySQLMigrationTarget,
+  use: (password: {
+    id: string;
+    host: string;
+    username: string;
+    password: Redacted.Redacted<string>;
+  }) => Effect.Effect<A, E, R>,
+) =>
+  Effect.acquireUseRelease(
+    Effect.gen(function* () {
+      const created = yield* ops.createPassword({
+        organization: target.organization,
+        database: target.database,
+        branch: target.branch,
+        role: "admin",
+        ttl: MIGRATION_PASSWORD_TTL_SECONDS,
+      });
+
+      return {
+        id: created.id,
+        host: created.access_host_url,
+        username: created.username,
+        password: created.plain_text,
+      };
+    }),
+    use,
+    (password) =>
+      ops
+        .deletePassword({
+          organization: target.organization,
+          database: target.database,
+          branch: target.branch,
+          id: password.id,
+        })
+        .pipe(
+          // Already-deleted passwords are a success: nothing to clean up.
+          Effect.catchTag("NotFound", () => Effect.void),
+          Effect.retry({
+            schedule: Schedule.exponential("500 millis").pipe(
+              Schedule.both(Schedule.recurs(5)),
+            ),
+          }),
+          // Migrations succeeded; don't fail the parent over a release-step
+          // hiccup. The password's TTL bounds the orphan window; log loudly
+          // so an operator can clean it up manually if needed.
+          Effect.catch((cause: unknown) =>
+            Effect.logWarning(
+              `Failed to delete temporary Planetscale migration password after retries. ` +
+                `It will expire via TTL (~${MIGRATION_PASSWORD_TTL_SECONDS}s). ` +
+                `organization=${target.organization} database=${target.database} ` +
+                `branch=${target.branch} id=${password.id}`,
+              cause,
+            ),
+          ),
+        ),
+  );
+
+const mysqlQuery = (connection: Connection, sql: string) =>
+  Effect.tryPromise({
+    try: () => connection.query(sql).then(() => undefined),
+    catch: toMigrationError,
+  });
+
+const mysqlExecute = (
+  connection: Connection,
+  sql: string,
+  values?: ReadonlyArray<string>,
+) =>
+  Effect.tryPromise({
+    try: () =>
+      connection
+        .execute(sql, values ? [...values] : undefined)
+        .then(() => undefined),
+    catch: toMigrationError,
+  });
+
+const mysqlQueryRows = <A>(connection: Connection, sql: string) =>
+  Effect.tryPromise({
+    try: () => connection.query(sql).then(([rows]) => rows as A[]),
+    catch: toMigrationError,
+  });
+
+const toMigrationError = (cause: unknown) =>
+  new MySQLMigrationError({
+    message: cause instanceof Error ? cause.message : String(cause),
+    cause,
+  });
+
+const quoteMySQLIdentifier = (identifier: string) =>
+  `\`${identifier.replaceAll("`", "``")}\``;

package/src/Planetscale/MySQL/MySQLOrigin.ts

@@ -0,0 +1,15 @@
+import * as Redacted from "effect/Redacted";
+
+/**
+ * The shape `Cloudflare.Hyperdrive` and other MySQL consumers accept as an
+ * origin. Materialized on `Planetscale.MySQLPassword` so callers can wire
+ * password credentials into Hyperdrive directly.
+ */
+export type MySQLOrigin = {
+  scheme: "mysql";
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: Redacted.Redacted<string>;
+};

package/src/Planetscale/MySQL/MySQLPassword.ts

@@ -0,0 +1,387 @@
+import { Credentials } from "@distilled.cloud/planetscale/Credentials";
+import * as ops from "@distilled.cloud/planetscale/Operations";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { deepEqual, isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+import type { MySQLBranch } from "./MySQLBranch.ts";
+import type { MySQLDatabase } from "./MySQLDatabase.ts";
+import type { MySQLOrigin } from "./MySQLOrigin.ts";
+
+/**
+ * Properties for creating or updating a PlanetScale MySQL password.
+ *
+ * Passwords are only meant for MySQL databases. For PostgreSQL,
+ * use {@link PostgresRole} instead.
+ */
+export interface MySQLPasswordProps {
+  /**
+   * Password name. If omitted, a unique name is generated from
+   * `${app}-${stage}-${id}`.
+   */
+  name?: string;
+
+  /**
+   * MySQL database — string name or {@link MySQLDatabase} resource.
+   */
+  database: string | MySQLDatabase;
+
+  /**
+   * Branch — string name or {@link MySQLBranch} resource.
+   * @default "main"
+   */
+  branch?: string | MySQLBranch;
+
+  /**
+   * The MySQL role granted to the password.
+   */
+  role: "reader" | "writer" | "admin" | "readwriter";
+
+  /**
+   * Whether the password is for a read replica.
+   */
+  replica?: boolean;
+
+  /**
+   * Time to live (seconds). The password is invalidated after this period.
+   */
+  ttl?: number;
+
+  /**
+   * IP CIDR ranges allowed to use this password.
+   */
+  cidrs?: string[];
+}
+
+/**
+ * Output attributes of a deployed PlanetScale password.
+ */
+export interface MySQLPasswordAttributes {
+  /** Unique identifier for the password (stable). */
+  id: string;
+  /** Password name. If omitted, a unique name is generated from `${app}-${stage}-${id}`. */
+  name: string;
+  /** ISO 8601 timestamp at which the password expires. `null` if no TTL. */
+  expiresAt: string | null;
+  /** Hostname for the database connection. */
+  host: string;
+  /** Username for database authentication. */
+  username: string;
+  /** Password for database authentication (Redacted). */
+  password: Redacted.Redacted<string>;
+  /** Parsed connection components ready to feed into Cloudflare Hyperdrive. */
+  origin: MySQLOrigin;
+  /** Resolved organization slug. */
+  organization: string;
+  /** Resolved database name. */
+  database: string;
+  /** Resolved branch name. */
+  branch: string;
+  /** The role granted. */
+  role: "reader" | "writer" | "admin" | "readwriter";
+  /** Whether this password is for a read replica. */
+  replica: boolean | undefined;
+  /** TTL in seconds (if set). */
+  ttl: number | undefined;
+  /** IP CIDR ranges allowed to use this password. */
+  cidrs: readonly string[] | undefined;
+}
+
+/**
+ * A PlanetScale password for accessing a MySQL database branch.
+ *
+ * For PostgreSQL databases, use {@link PostgresRole} instead.
+ *
+ * @section Creating a Password
+ * @example Reader password
+ * ```typescript
+ * const reader = yield* Planetscale.MySQLPassword("AppReader", {
+ *   database: "my-db",
+ *   role: "reader",
+ * });
+ * ```
+ *
+ * @example Writer password with TTL
+ * ```typescript
+ * const writer = yield* Planetscale.MySQLPassword("AppWriter", {
+ *   database: "my-db",
+ *   role: "writer",
+ *   ttl: 86400,
+ * });
+ * ```
+ *
+ * @example Admin password with IP allowlist
+ * ```typescript
+ * const admin = yield* Planetscale.MySQLPassword("Admin", {
+ *   database: "my-db",
+ *   role: "admin",
+ *   cidrs: ["203.0.113.0/24", "198.51.100.0/24"],
+ * });
+ * ```
+ */
+export type MySQLPassword = Resource<
+  "Planetscale.MySQLPassword",
+  MySQLPasswordProps,
+  MySQLPasswordAttributes,
+  never,
+  Providers
+>;
+
+export const MySQLPassword = Resource<MySQLPassword>(
+  "Planetscale.MySQLPassword",
+);
+
+// At runtime, Resource references in props are resolved to their full
+// attributes — so `news.database` (when a Database resource was passed)
+// is `{ name: string; organization: string; ... }` rather than the
+// statically-typed Resource (whose attributes are `Output<...>`). We
+// cast through structural shapes here.
+type DatabaseRef = string | { name: string; organization?: string };
+type BranchRef = string | { name: string };
+
+const resolveDatabaseName = (database: string | MySQLDatabase): string => {
+  const ref = database as unknown as DatabaseRef;
+  return typeof ref === "string" ? ref : ref.name;
+};
+
+const resolveDatabaseOrg = (
+  database: string | MySQLDatabase,
+): string | undefined => {
+  const ref = database as unknown as DatabaseRef;
+  return typeof ref === "string" ? undefined : ref.organization;
+};
+
+const resolveBranchName = (
+  branch: string | MySQLBranch | undefined,
+): string => {
+  const ref = branch as unknown as BranchRef | undefined;
+  return !ref ? "main" : typeof ref === "string" ? ref : ref.name;
+};
+
+const createPasswordName = (id: string, name: string | undefined) =>
+  Effect.gen(function* () {
+    return (
+      name ??
+      (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }))
+    );
+  });
+
+// Normalize the API's nullable `cidrs` field into the `string[] | undefined`
+// shape we persist so downstream comparisons line up regardless of the
+// API returning `null` vs `[]` vs an actual list.
+const normalizeCidrs = (
+  cidrs: readonly string[] | null | undefined,
+): readonly string[] | undefined =>
+  cidrs == null || cidrs.length === 0 ? undefined : cidrs;
+
+const buildAttributes = (
+  password: {
+    id: string;
+    name: string;
+    expires_at: string | null;
+    access_host_url: string;
+    username: string;
+    role: "reader" | "writer" | "admin" | "readwriter";
+    replica: boolean;
+    ttl_seconds: number | null;
+    cidrs: readonly string[] | null;
+  },
+  plaintext: Redacted.Redacted<string>,
+  context: {
+    organization: string;
+    database: string;
+    branch: string;
+  },
+): MySQLPasswordAttributes => ({
+  id: password.id,
+  name: password.name,
+  expiresAt: password.expires_at,
+  host: password.access_host_url,
+  username: password.username,
+  password: plaintext,
+  origin: {
+    scheme: "mysql",
+    host: password.access_host_url,
+    port: 3306,
+    database: context.database,
+    user: password.username,
+    password: plaintext,
+  },
+  organization: context.organization,
+  database: context.database,
+  branch: context.branch,
+  role: password.role,
+  replica: password.replica,
+  ttl: password.ttl_seconds ?? undefined,
+  cidrs: normalizeCidrs(password.cidrs),
+});
+
+export const MySQLPasswordProvider = () =>
+  Provider.effect(
+    MySQLPassword,
+    Effect.gen(function* () {
+      const createPwd = yield* ops.createPassword;
+      const getPwd = yield* ops.getPassword;
+      const updatePwd = yield* ops.updatePassword;
+      const deletePwd = yield* ops.deletePassword;
+
+      return {
+        stables: ["id"],
+
+        diff: Effect.fn(function* ({ olds = {}, news }) {
+          if (!isResolved(news)) return undefined;
+
+          // Replace on any immutable-in-place change; engine falls through
+          // to reconcile for everything else (which authoritatively diffs
+          // against observed cloud state).
+          if (news.role !== olds.role) return { action: "replace" } as const;
+          if (news.replica !== olds.replica) {
+            return { action: "replace" } as const;
+          }
+          if (news.ttl !== olds.ttl) return { action: "replace" } as const;
+
+          const newDb = resolveDatabaseName(news.database);
+          const oldDb = olds.database
+            ? resolveDatabaseName(olds.database)
+            : undefined;
+          if (oldDb && newDb !== oldDb) {
+            return { action: "replace" } as const;
+          }
+          const newBranch = resolveBranchName(news.branch);
+          const oldBranch = resolveBranchName(olds.branch);
+          if (newBranch !== oldBranch) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+
+        read: Effect.fn(function* ({ output }) {
+          // Adoption (no cached output) is impossible: the PlanetScale API
+          // never re-issues plaintext, so even if we found a matching live
+          // password by listing+name we couldn't deliver the `password`
+          // attribute. Fall through to greenfield create in `reconcile`.
+          if (!output) return undefined;
+
+          // Refresh — verify the cached password still exists and
+          // re-emit the persisted output (with plaintext intact).
+          // If it's gone, return undefined so the engine routes to
+          // reconcile, which will surface the unrecoverable-rotation
+          // condition explicitly.
+          return yield* getPwd({
+            organization: output.organization,
+            database: output.database,
+            branch: output.branch,
+            id: output.id,
+          }).pipe(
+            Effect.map((password) =>
+              buildAttributes(password, output.password, {
+                organization: output.organization,
+                database: output.database,
+                branch: output.branch,
+              }),
+            ),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+          const newName = yield* createPasswordName(id, news.name);
+
+          // Identifiers — stable across update (diff replaces on
+          // database/branch changes), so we can pull from `output` first
+          // and fall back to `news` for greenfield.
+          const { organization: envOrg } = yield* Credentials;
+          const organization =
+            output?.organization ?? resolveDatabaseOrg(news.database) ?? envOrg;
+          const databaseName =
+            output?.database ?? resolveDatabaseName(news.database);
+          const branchName = output?.branch ?? resolveBranchName(news.branch);
+
+          // 1. Observe — read live state. The PlanetScale API has no
+          //    "lookup by name" path (names aren't unique within a branch)
+          //    so the only way to find the live password is by id. Without
+          //    a cached output we cannot observe and fall straight through
+          //    to ensure (greenfield create).
+          const observed = output
+            ? yield* getPwd({
+                organization,
+                database: databaseName,
+                branch: branchName,
+                id: output.id,
+              }).pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              )
+            : undefined;
+
+          // 2. Ensure — create the password if it doesn't exist live.
+          //    This single branch covers greenfield (no output) AND the
+          //    out-of-band-deletion case (output cached but cloud lost it).
+          //    The latter is structurally a rotation: the new password
+          //    has a fresh id/host/username/plaintext that propagate
+          //    downstream through the dependency graph. There is no path
+          //    to recover the original plaintext, so recreating is the
+          //    only way to converge.
+          let live: ops.GetPasswordOutput;
+          let plaintext: Redacted.Redacted<string>;
+          if (observed) {
+            live = observed;
+            // We re-use the cached plaintext: the API never re-issues it.
+            plaintext = output!.password;
+          } else {
+            const created = yield* createPwd({
+              organization,
+              database: databaseName,
+              branch: branchName,
+              name: newName,
+              role: news.role,
+              replica: news.replica,
+              ttl: news.ttl,
+              cidrs: news.cidrs,
+            });
+            plaintext = created.plain_text;
+            live = created;
+          }
+
+          // 3. Sync — diff observed cloud state against desired and patch
+          //    only what changed. Only `name` and `cidrs` are mutable in
+          //    place; everything else triggers a replace via diff().
+          //    Skip the API entirely when there's no delta.
+          const wantsRename = newName !== live.name;
+          const observedCidrs = normalizeCidrs(live.cidrs);
+          const desiredCidrs = normalizeCidrs(news.cidrs);
+          const wantsCidrs = !deepEqual(desiredCidrs, observedCidrs);
+
+          if (wantsRename || wantsCidrs) {
+            live = yield* updatePwd({
+              organization,
+              database: databaseName,
+              branch: branchName,
+              id: live.id,
+              name: wantsRename ? newName : undefined,
+              cidrs: wantsCidrs ? news.cidrs : undefined,
+            });
+          }
+
+          // 4. Return — fresh attrs sourced from observed cloud state,
+          //    re-using cached plaintext when we didn't just create.
+          return buildAttributes(live, plaintext, {
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          yield* deletePwd({
+            organization: output.organization,
+            database: output.database,
+            branch: output.branch,
+            id: output.id,
+          }).pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/Planetscale/MySQL/index.ts

@@ -0,0 +1,5 @@
+export * from "./MySQLClusterSize.ts";
+export * from "./MySQLBranch.ts";
+export * from "./MySQLDatabase.ts";
+export * from "./MySQLOrigin.ts";
+export * from "./MySQLPassword.ts";