@alchemy.run/planetscale 0.0.0 → 2.0.0-beta.85

package/src/MySQL/MySQLDatabase.ts

@@ -0,0 +1,521 @@
+import {
+  diffMigrations,
+  migrationsAttrs,
+  migrationsInputOf,
+  stampedOf,
+} from "@alchemy.run/sql/Migrations";
+import { hashImports } from "@alchemy.run/sql/SqlFile";
+import * as planetscale from "@distilled.cloud/planetscale";
+import { Credentials } from "@distilled.cloud/planetscale/Credentials";
+import { havePropsChanged, isResolved } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { recordsEqual } from "alchemy/Util/equal";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import type { BaseDatabaseAttributes, BaseDatabaseProps } from "../Database.ts";
+import type { Providers } from "../Providers.ts";
+import {
+  deleteUnprotectedDatabase,
+  PlanetscaleConflict,
+  replaceDatabase,
+  waitForBranchReady,
+  waitForDatabaseReady,
+} from "../Util.ts";
+import {
+  ensureMySQLProductionBranchClusterSize,
+  observeDefaultKeyspaceReplicas,
+  type MySQLClusterSize,
+} from "./MySQLClusterSize.ts";
+import { runMySQLImports, runMySQLMigrations } from "./MySQLMigrations.ts";
+
+/**
+ * Properties for creating or updating a MySQL PlanetScale database.
+ */
+export interface MySQLDatabaseProps extends BaseDatabaseProps {
+  /**
+   * The MySQL database cluster size. Required.
+   * @see https://planetscale.com/docs/concepts/cluster-size
+   */
+  clusterSize: MySQLClusterSize;
+
+  /**
+   * Desired total number of replicas for the database's default keyspace.
+   * Each cluster size includes a fixed number of replicas (2 for
+   * production `PS_*` sizes); higher values add extra replicas. Changes
+   * are reconciled in place via PlanetScale's keyspace resize lifecycle —
+   * never by replacing the database.
+   * @see https://planetscale.com/docs/vitess/sharding/keyspaces
+   */
+  replicas?: number;
+
+  /**
+   * Whether to copy migration data to new branches and in deploy requests.
+   */
+  automaticMigrations?: boolean;
+
+  /**
+   * Migration framework to use on the database.
+   */
+  migrationFramework?: string;
+
+  /**
+   * Name of the migration table.
+   */
+  migrationTableName?: string;
+
+  /**
+   * Whether data branching is allowed on the database.
+   */
+  allowDataBranching?: boolean;
+
+  /**
+   * Whether foreign key constraints are allowed on the database.
+   */
+  allowForeignKeyConstraints?: boolean;
+
+  /**
+   * Whether full queries should be collected from the database.
+   */
+  insightsRawQueries?: boolean;
+}
+
+/**
+ * Output attributes of a deployed MySQL PlanetScale database.
+ */
+export interface MySQLDatabaseAttributes extends BaseDatabaseAttributes {
+  /**
+   * Observed total replica count of the default keyspace on the default
+   * branch, or `undefined` while the keyspace is still provisioning.
+   */
+  replicas: number | undefined;
+
+  /**
+   * Whether to copy migration data to new branches and in deploy requests.
+   */
+  automaticMigrations: boolean;
+
+  /**
+   * Migration framework to use on the database.
+   */
+  migrationFramework?: string;
+
+  /**
+   * Name of the migration table.
+   */
+  migrationTableName?: string;
+
+  /**
+   * Whether data branching is allowed on the database.
+   */
+  allowDataBranching: boolean;
+
+  /**
+   * Whether foreign key constraints are allowed on the database.
+   */
+  allowForeignKeyConstraints: boolean;
+
+  /**
+   * Whether full queries should be collected from the database.
+   */
+  insightsRawQueries: boolean;
+}
+
+/**
+ * A MySQL PlanetScale database (powered by Vitess). For PostgreSQL use
+ * {@link PostgresDatabase} instead.
+ *
+ * ### Creating a MySQL Database
+ * **Example:** Basic MySQL database
+ * ```typescript
+ * const db = yield* Planetscale.MySQLDatabase("MyDb", {
+ *   clusterSize: "PS_10",
+ * });
+ * ```
+ *
+ * **Example:** MySQL with Vitess migration tooling
+ * ```typescript
+ * const db = yield* Planetscale.MySQLDatabase("MyDb", {
+ *   clusterSize: "PS_10",
+ *   automaticMigrations: true,
+ *   migrationFramework: "rails",
+ *   migrationTableName: "schema_migrations",
+ *   allowDataBranching: true,
+ * });
+ * ```
+ *
+ * ### Migrations and seed data
+ * **Example:** Apply migrations and seed files
+ * ```typescript
+ * const db = yield* Planetscale.MySQLDatabase("MyDb", {
+ *   clusterSize: "PS_10",
+ *   migrationsDir: "./migrations/mysql",
+ *   importFiles: ["./seed/mysql.sql"],
+ * });
+ * ```
+ *
+ * ### Deletion protection
+ * **Example:** Refuse deletes of a production database
+ * ```typescript
+ * const db = yield* Planetscale.MySQLDatabase("MyDb", {
+ *   clusterSize: "PS_10",
+ *   deletionProtection: true,
+ * });
+ * ```
+ *
+ * ### Adoption
+ * **Example:** Adopting an existing database
+ * ```typescript
+ * import { adopt } from "alchemy/AdoptPolicy";
+ *
+ * const db = yield* Planetscale.MySQLDatabase("Existing", {
+ *   name: "existing-db",
+ *   clusterSize: "PS_10",
+ * }).pipe(adopt());
+ * ```
+ */
+export type MySQLDatabase = Resource<
+  "Planetscale.MySQLDatabase",
+  MySQLDatabaseProps,
+  MySQLDatabaseAttributes,
+  never,
+  Providers
+>;
+
+/** @resource */
+export const MySQLDatabase = Resource<MySQLDatabase>("Planetscale.MySQLDatabase");
+
+export const MySQLDatabaseProvider = () =>
+  Provider.succeed(MySQLDatabase, {
+    stables: ["id", "organization", "region"],
+    diff: Effect.fn(function* ({ news, olds, output }) {
+      if (!isResolved(news)) return undefined;
+
+      // Database names are rename-mutable (reconcile folds `new_name`
+      // into the settings sync), so `name` cannot live in the
+      // provider-level stables. Almost no update is a rename though —
+      // for those, advertise `name` as stable on the update so
+      // downstream consumers (branches, passwords) still resolve
+      // `database.name` at plan time instead of seeing `undefined` and
+      // falsely planning a replacement. The name only changes when the
+      // `name` prop itself changes: an explicit name renames iff it
+      // differs from the observed name, and an omitted name is
+      // engine-generated deterministically (stable across updates).
+      const nameIsStable =
+        output?.name !== undefined &&
+        (news.name !== undefined ? news.name === output.name : olds?.name === undefined);
+      const stables = nameIsStable ? ["id", "organization", "region", "name"] : undefined;
+
+      if (
+        news.region?.slug !== undefined &&
+        output?.region?.slug !== undefined &&
+        news.region.slug !== output.region.slug
+      ) {
+        return yield* replaceDatabase(news, output, "region");
+      }
+      // Replicas reconcile in place via a keyspace resize — never a
+      // replacement. Diff against the observed keyspace replica count so
+      // an adopted database whose live state already matches plans no-op.
+      if (news.replicas !== undefined && news.replicas !== (output?.replicas ?? olds.replicas)) {
+        return { action: "update", stables } as const;
+      }
+      if (yield* diffMigrations({ news, output })) {
+        return { action: "update", stables } as const;
+      }
+      if (news.importFiles?.length) {
+        const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
+        if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
+          return { action: "update", stables } as const;
+        }
+      }
+      // Remaining prop changes (rename, settings, clusterSize, …) are
+      // in-place updates. Decide them here instead of falling back to
+      // the engine's default deep-compare so the conditional `name`
+      // stable above is attached — the default path uses the
+      // provider-level stables, which strip `name` from downstream plan
+      // resolution.
+      if (havePropsChanged(olds, news)) {
+        return { action: "update", stables } as const;
+      }
+
+      // Nothing changed. Still advertise the conditional `name` stable so
+      // a `--force` deploy (which upgrades this noop to an update) keeps
+      // `name` resolvable downstream instead of falsely replacing
+      // consumers such as roles and passwords (#1832).
+      return stables ? ({ action: "noop", stables } as const) : undefined;
+    }),
+
+    read: Effect.fn(function* ({ id, output, olds }) {
+      const { organization } = yield* yield* Credentials;
+      const databaseName = output?.name ?? (yield* createDatabaseName(id, olds?.name));
+      return yield* planetscale
+        .getDatabase({
+          organization,
+          database: databaseName,
+        })
+        .pipe(
+          Effect.flatMap(
+            Effect.fn(function* (data) {
+              if (data.kind !== "mysql") {
+                return yield* new PlanetscaleConflict({
+                  message:
+                    `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
+                    `is a MySQLDatabase. Use Planetscale.${data.kind === "postgresql" ? "PostgresDatabase" : data.kind}() instead, ` +
+                    `or delete the existing database and retry.`,
+                });
+              }
+              // Observe the default keyspace's live replica configuration
+              // so adopted databases diff against reality.
+              const replicas = yield* observeDefaultKeyspaceReplicas(
+                organization,
+                data.name,
+                data.default_branch ?? "main",
+              );
+              return {
+                id: data.id,
+                name: data.name,
+                organization,
+                state: data.state,
+                defaultBranch: data.default_branch ?? "main",
+                replicas,
+                plan: data.plan ?? "hobby",
+                createdAt: data.created_at,
+                updatedAt: data.updated_at,
+                htmlUrl: data.html_url,
+                region: { slug: data.region.slug },
+                migrationsDir: output?.migrationsDir ?? (olds && migrationsInputOf(olds))?.dir,
+                migrationsTable:
+                  output?.migrationsTable ?? (olds && migrationsInputOf(olds))?.table,
+                migrationsHashes: output?.migrationsHashes ?? {},
+                importHashes: output?.importHashes ?? {},
+                clusterSize: output?.clusterSize ?? "",
+                requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
+                restrictBranchRegion: data.restrict_branch_region ?? false,
+                insightsRawQueries: data.insights_raw_queries ?? false,
+                productionBranchWebConsole: data.production_branch_web_console ?? false,
+                deletionProtection: data.deletion_protected ?? false,
+                automaticMigrations: data.automatic_migrations ?? false,
+                migrationFramework: data.migration_framework ?? undefined,
+                migrationTableName: data.migration_table_name ?? undefined,
+                allowDataBranching: data.allow_data_branching ?? false,
+                allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
+              };
+            }),
+          ),
+          Effect.catchTag("NotFound", () => Effect.undefined),
+        );
+    }),
+
+    reconcile: Effect.fn(function* ({ id, news, output, session }) {
+      const { organization } = yield* yield* Credentials;
+      const newName = yield* createDatabaseName(id, news.name);
+      const clusterSize = news.clusterSize;
+
+      // Observe — read live state under either the cached name (rename
+      // / refresh) or the freshly-derived name (greenfield). Observing
+      // unconditionally absorbs the race between `read` and `reconcile`
+      // — if a foreign actor (or a previously-failed-to-persist
+      // create) produced a database under the desired name in the
+      // meantime, we'll find it here and skip the duplicate create.
+      // Adoption routing has already been gated by `read` returning
+      // `Unowned`, so by the time we reach reconcile any observed
+      // database is fair game.
+      const observedName = output?.name ?? newName;
+      let observed = yield* planetscale
+        .getDatabase({
+          organization,
+          database: observedName,
+        })
+        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
+
+      // Ensure — if missing, create.
+      if (!observed) {
+        yield* session.note("Creating database...");
+        // Note: the API rejects the `replicas` param for mysql databases;
+        // replicas are converged below via the keyspace resize lifecycle.
+        observed = yield* planetscale.createDatabase({
+          organization,
+          name: newName,
+          region: news.region?.slug,
+          kind: "mysql",
+          cluster_size: clusterSize,
+        });
+      }
+
+      // Wait for the database to finish provisioning before any
+      // downstream sync runs. PlanetScale reports `state: "pending"`
+      // for a while after createDatabase returns, during which branch
+      // operations on this database (including our own settings PATCH)
+      // race against the provisioning fiber.
+      yield* waitForDatabaseReady(organization, observed.name, session);
+
+      if (observed.kind !== "mysql") {
+        return yield* new PlanetscaleConflict({
+          message:
+            `Planetscale database "${observed.name}" has kind "${observed.kind}" but this resource ` +
+            `is a MySQLDatabase. Use Planetscale.${observed.kind === "postgresql" ? "PostgresDatabase" : observed.kind}() instead, ` +
+            `or delete the existing database and retry.`,
+        });
+      }
+
+      // Sync — ensure a non-`main` default branch exists before
+      // referencing it via `default_branch`. The branch is created
+      // empty (no cluster size yet); we'll size it below.
+      if (news.defaultBranch && news.defaultBranch !== "main") {
+        yield* waitForDatabaseReady(organization, observed.name, session);
+        const branchExists = yield* planetscale
+          .getBranch({
+            organization,
+            database: observed.name,
+            branch: news.defaultBranch,
+          })
+          .pipe(
+            Effect.map(() => true),
+            Effect.catchTag("NotFound", () => Effect.succeed(false)),
+          );
+        if (!branchExists) {
+          yield* planetscale.createBranch({
+            organization,
+            database: observed.name,
+            name: news.defaultBranch,
+            parent_branch: "main",
+            // create branch with cluster size to skip resizing when promoting the branch
+            cluster_size: clusterSize,
+          });
+        }
+      }
+
+      // Sync settings — `updateSettings` is upsert-shaped, so we can
+      // call it with the full desired payload on every reconcile.
+      const updated = yield* planetscale.updateDatabaseSettings({
+        organization,
+        database: observed.name,
+        new_name: newName !== observed.name ? newName : undefined,
+        automatic_migrations: news.automaticMigrations,
+        migration_framework: news.migrationFramework,
+        migration_table_name: news.migrationTableName,
+        allow_foreign_key_constraints: news.allowForeignKeyConstraints,
+        allow_data_branching: news.allowDataBranching,
+        require_approval_for_deploy: news.requireApprovalForDeploy,
+        restrict_branch_region: news.restrictBranchRegion,
+        insights_raw_queries: news.insightsRawQueries,
+        production_branch_web_console: news.productionBranchWebConsole,
+        deletion_protected: news.deletionProtection,
+        default_branch: news.defaultBranch,
+      });
+
+      // Sync cluster size and replicas on the active default branch —
+      // both converge in place via PlanetScale's keyspace resize
+      // lifecycle, diffed against the observed default keyspace.
+      const branch = news.defaultBranch ?? updated.default_branch ?? "main";
+      const keyspace = yield* ensureMySQLProductionBranchClusterSize(
+        organization,
+        updated.name,
+        branch,
+        news.clusterSize,
+        news.replicas,
+      );
+
+      const migrationTarget = {
+        organization,
+        database: updated.name,
+        branch,
+      };
+      const migrationsInput = migrationsInputOf(news);
+      if (migrationsInput || news.importFiles?.length) {
+        yield* waitForBranchReady(organization, updated.name, branch, session);
+      }
+      const migrations = migrationsInput
+        ? yield* runMySQLMigrations(migrationTarget, migrationsInput, stampedOf(output))
+        : undefined;
+      const importHashes = news.importFiles?.length
+        ? yield* runMySQLImports(
+            migrationTarget,
+            news.importFiles,
+            yield* rootDir,
+            output?.importHashes ?? {},
+          )
+        : {};
+
+      return {
+        id: updated.id,
+        name: updated.name,
+        organization,
+        state: updated.state,
+        defaultBranch: updated.default_branch ?? branch,
+        plan: updated.plan ?? output?.plan ?? "hobby",
+        createdAt: updated.created_at,
+        updatedAt: updated.updated_at,
+        htmlUrl: updated.html_url,
+        region: { slug: updated.region.slug },
+        clusterSize,
+        replicas: keyspace.replicas,
+        ...migrationsAttrs({ input: migrationsInput, run: migrations, output }),
+        importHashes,
+        requireApprovalForDeploy: updated.require_approval_for_deploy ?? false,
+        restrictBranchRegion: updated.restrict_branch_region ?? false,
+        insightsRawQueries: updated.insights_raw_queries ?? false,
+        productionBranchWebConsole: updated.production_branch_web_console ?? false,
+        deletionProtection: updated.deletion_protected ?? false,
+        automaticMigrations: updated.automatic_migrations ?? false,
+        migrationFramework: updated.migration_framework ?? undefined,
+        migrationTableName: updated.migration_table_name ?? undefined,
+        allowDataBranching: updated.allow_data_branching ?? false,
+        allowForeignKeyConstraints: updated.foreign_keys_enabled ?? false,
+      } satisfies MySQLDatabaseAttributes;
+    }),
+
+    delete: Effect.fn(function* ({ output }) {
+      yield* deleteUnprotectedDatabase(output.organization, output.name);
+    }),
+
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      return yield* planetscale.listDatabases.pages({ organization }).pipe(
+        Stream.runCollect,
+        Effect.map((chunk) =>
+          Array.from(chunk).flatMap((page) =>
+            page.data
+              .filter((db) => db.kind === "mysql")
+              .map((data): MySQLDatabase["Attributes"] => ({
+                id: data.id,
+                name: data.name,
+                organization,
+                state: data.state,
+                defaultBranch: data.default_branch ?? "main",
+                plan: data.plan ?? "hobby",
+                createdAt: data.created_at,
+                updatedAt: data.updated_at,
+                htmlUrl: data.html_url,
+                region: { slug: data.region.slug },
+                migrationsDir: undefined,
+                migrationsTable: undefined,
+                migrationsHashes: {},
+                importHashes: {},
+                clusterSize: "",
+                replicas: undefined,
+                requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
+                restrictBranchRegion: data.restrict_branch_region ?? false,
+                insightsRawQueries: data.insights_raw_queries ?? false,
+                productionBranchWebConsole: data.production_branch_web_console ?? false,
+                deletionProtection: data.deletion_protected ?? false,
+                automaticMigrations: data.automatic_migrations ?? false,
+                migrationFramework: data.migration_framework ?? undefined,
+                migrationTableName: data.migration_table_name ?? undefined,
+                allowDataBranching: data.allow_data_branching ?? false,
+                allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
+              })),
+          ),
+        ),
+      );
+    }),
+  });
+
+const createDatabaseName = (id: string, name: string | undefined) =>
+  Effect.gen(function* () {
+    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }));
+  });
+
+const rootDir = Effect.sync(() => process.cwd());

package/src/MySQL/MySQLMigrations.ts

@@ -0,0 +1,133 @@
+import {
+  runMigrations,
+  withMySqlExecutor,
+  type NormalizedMigrationsInput,
+  type SqlExecutor,
+  type StampedMigrationsState,
+} from "@alchemy.run/sql/Migrations";
+import { applySqlImports, splitSqlStatements } from "@alchemy.run/sql/SqlFile";
+import * as ps from "@distilled.cloud/planetscale";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+
+const MIGRATION_PASSWORD_TTL_SECONDS = 600;
+
+export interface MySQLMigrationTarget {
+  organization: string;
+  database: string;
+  branch: string;
+}
+
+/**
+ * PlanetScale MySQL's migration adaptation is exactly this: the shared
+ * pipeline with a temp-password-scoped mysql2 connection as its executor.
+ */
+export const runMySQLMigrations = (
+  target: MySQLMigrationTarget,
+  input: NormalizedMigrationsInput,
+  stamped: StampedMigrationsState,
+) =>
+  runMigrations({
+    input,
+    stamped,
+    withExecutor: (apply) => withMySQLExecutor(target, apply),
+  });
+
+/**
+ * Apply `importFiles`, each once and again only when it changes. Vitess
+ * rejects drizzle-kit's `--> statement-breakpoint` markers, so statements
+ * run one at a time.
+ */
+export const runMySQLImports = (
+  target: MySQLMigrationTarget,
+  importFiles: ReadonlyArray<string>,
+  rootDir: string,
+  previous: Record<string, string>,
+) =>
+  applySqlImports({
+    importFiles,
+    rootDir,
+    previous,
+    apply: (file) =>
+      withMySQLExecutor(target, (executor) =>
+        Effect.forEach(splitSqlStatements(file.sql), (statement) => executor.query(statement), {
+          discard: true,
+        }),
+      ),
+  });
+
+/** A verified-TLS `mysql2` session as a short-lived admin password. */
+const withMySQLExecutor = <A, E, R>(
+  target: MySQLMigrationTarget,
+  use: (executor: SqlExecutor) => Effect.Effect<A, E, R>,
+) =>
+  withTemporaryMySQLPassword(target, (password) =>
+    withMySqlExecutor(
+      {
+        host: password.host,
+        user: password.username,
+        password: Redacted.value(password.password),
+        database: target.database,
+        multipleStatements: true,
+        ssl: { rejectUnauthorized: true },
+      },
+      use,
+    ),
+  );
+
+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* ps.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) =>
+      ps
+        .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.max([Schedule.exponential("500 millis"), 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,
+            ),
+          ),
+        ),
+  );

package/src/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>;
+};