@alchemy.run/planetscale 0.0.0-stage → 2.0.0-beta.84

package/src/Branch.ts

@@ -0,0 +1,657 @@
+import {
+  classifyMigrationHistory,
+  describeRewrittenHistory,
+  migrationsAttrs,
+  migrationsInputOf,
+  RewrittenMigrationHistoryError,
+  stampedOf,
+  type MigrationRun,
+  type MigrationsInput,
+  type NormalizedMigrationsInput,
+  type StampedMigrationsState,
+} 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 { Unowned } from "alchemy/AdoptPolicy";
+import { havePropsChanged, isResolved } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import type { ResourceClass, ResourceLike } from "alchemy/Resource";
+import { recordsEqual } from "alchemy/Util/equal";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { ensureMySQLProductionBranchClusterSize } from "./MySQL/MySQLClusterSize.ts";
+import {
+  ensurePostgresProductionBranchClusterSize,
+  toPostgresClusterArch,
+  toPostgresClusterSku,
+  waitForPendingPostgresChanges,
+} from "./Postgres/PostgresClusterSize.ts";
+import { PlanetscaleConflict, isKnownError, waitForBranchReady } from "./Util.ts";
+
+/**
+ * Props shared between {@link MySQLBranch} and {@link PostgresBranch}. The
+ * `database` and `parentBranch` fields are typed by each engine's resource.
+ */
+export interface BaseBranchProps {
+  /**
+   * Branch name. If omitted, a name is generated from the stack/stage/id.
+   */
+  name?: string;
+
+  /**
+   * If provided, restores the backup's schema and data to the new branch.
+   * Ignored if the branch already exists.
+   */
+  backupId?: string;
+
+  /**
+   * If provided, restores the last successful backup's schema and data.
+   * Ignored if the branch already exists.
+   */
+  seedData?: "last_successful_backup";
+
+  /**
+   * Whether safe migrations are enabled on the branch.
+   */
+  safeMigrations?: boolean;
+
+  /**
+   * Region in which to create the branch. Defaults to the database's
+   * region. The actual region is validated on adopt/update.
+   */
+  region?: { slug: string };
+
+  /**
+   * SQL migrations to apply against this branch. Accepts a directory path,
+   * a `Drizzle.Schema` resource, or `{ dir, table? }`. Bookkeeping lives
+   * in Alchemy's `__alchemy_migrations` table; drizzle/prisma history is
+   * converted one-way on first deploy.
+   *
+   * Adding a file is an in-place update. Editing or removing an
+   * already-applied file replaces a non-production branch (re-forked from
+   * its parent) and fails on a current or desired production branch — add
+   * a forward migration instead.
+   */
+  migrations?: MigrationsInput;
+
+  /**
+   * Paths to additional `.sql` files to apply after migrations. Each file is
+   * hashed; only files whose contents change are re-applied on later deploys.
+   */
+  importFiles?: string[];
+}
+
+/**
+ * Attributes shared between {@link MySQLBranch} and {@link PostgresBranch}.
+ */
+export interface BaseBranchAttributes {
+  /** The branch name. */
+  name: string;
+  /** The PlanetScale organization slug. */
+  organization: string;
+  /** The database name. */
+  database: string;
+  /** The parent branch name. */
+  parentBranch: string;
+  /** Whether this is a production branch. */
+  production: boolean;
+  /** Time at which the branch was created (ISO 8601). */
+  createdAt: string;
+  /**
+   * Time at which the branch was last updated (ISO 8601), as observed by the
+   * last deploy. PlanetScale bumps this timestamp on its own, so it is not
+   * refreshed by drift detection.
+   */
+  updatedAt: string;
+  /** HTML URL for accessing the branch in the dashboard. */
+  htmlUrl: string;
+  /** The region of the branch as reported by PlanetScale. */
+  region: { slug: string };
+  /** Directory containing migration files, if configured. */
+  migrationsDir: string | undefined;
+  /** Table used to track applied migrations, if configured. */
+  migrationsTable: string | undefined;
+  /** Content hashes for the last applied migration files. */
+  migrationsHashes: Record<string, string>;
+  /** Content hashes for the last applied import files. */
+  importHashes: Record<string, string>;
+  /**
+   * Desired total replica count requested by the resource input, when known.
+   * PlanetScale's branch read API exposes only boolean HA state, so this is
+   * persisted from Alchemy state rather than observed from live provider data.
+   */
+  desiredReplicas: number | undefined;
+  /** Whether the branch currently has HA replicas. */
+  hasReplicas: boolean | undefined;
+  /** Whether the branch currently has read-only replicas. */
+  hasReadOnlyReplicas: boolean | undefined;
+}
+
+// Runtime-resolved Database/Branch references. `news.database` can be a
+// plain string OR (after resolution) the Database resource's attributes —
+// which contain plain values for `name` / `organization`. The static
+// Database type has those fields as `Output<...>`, so we cast through a
+// structural shape here.
+type DatabaseRef = string | { name: string; organization?: string };
+type BranchRef = string | { name: string };
+
+const resolveDatabase = (database: unknown): { name: string; organization?: string } => {
+  const ref = database as DatabaseRef | undefined;
+  if (!ref) return { name: "" };
+  return typeof ref === "string"
+    ? { name: ref }
+    : { name: ref.name, organization: ref.organization };
+};
+
+const resolveParent = (parent: unknown): string => {
+  const ref = parent as BranchRef | undefined;
+  return !ref ? "main" : typeof ref === "string" ? ref : ref.name;
+};
+
+const createBranchName = (id: string, name: string | undefined) =>
+  Effect.gen(function* () {
+    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 63 }));
+  });
+
+/**
+ * Shape of the engine-specific migration runners used by
+ * {@link makeBranchProvider}. MySQL and Postgres each supply their own
+ * implementations in their respective `*Migrations.ts` modules.
+ */
+export interface BranchMigrationRunners {
+  runMigrations: (
+    target: { organization: string; database: string; branch: string },
+    input: NormalizedMigrationsInput,
+    stamped: StampedMigrationsState,
+  ) => Effect.Effect<MigrationRun, any, any>;
+  runImports: (
+    target: { organization: string; database: string; branch: string },
+    importFiles: string[],
+    rootDir: string,
+    previousHashes: Record<string, string>,
+  ) => Effect.Effect<Record<string, string>, any, any>;
+}
+
+const rootDir = Effect.sync(() => process.cwd());
+
+/**
+ * Matches the UnprocessableEntity errors PlanetScale returns when a
+ * branch promotion/demotion races an in-flight cluster resize, e.g.
+ * "Branches with a cluster resize in progress cannot be demoted."
+ */
+const isResizeInProgress = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  (error as { readonly _tag?: unknown })._tag === "UnprocessableEntity" &&
+  typeof (error as { readonly message?: unknown }).message === "string" &&
+  (error as { readonly message: string }).message.includes("cluster resize in progress");
+
+/**
+ * Build a branch provider for a specific PlanetScale engine. The
+ * caller supplies the typed `Resource` token and the engine's migration
+ * runners; everything else (observe / ensure / sync / delete) is shared.
+ */
+export const makeBranchProvider = <R extends ResourceLike>(opts: {
+  resource: ResourceClass<R>;
+  expectedKind: "mysql" | "postgresql";
+  engineLabel: string;
+  runners: BranchMigrationRunners;
+}) =>
+  Provider.succeed(opts.resource, {
+    stables: ["organization", "database"],
+
+    // PARENT FAN-OUT: PlanetScale branches are nested under a database within
+    // an organization, so there is no flat per-org branch enumeration API.
+    // Enumerate every database in the credentialed org, then list each
+    // database's branches concurrently (bounded), exhaustively paginating
+    // both levels, and keep only the branches whose engine kind matches this
+    // resource. Each item is hydrated into the exact `read` Attributes shape.
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      const databases = yield* planetscale.listDatabases.pages({ organization }).pipe(
+        Stream.runCollect,
+        Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.data)),
+      );
+
+      const rows = yield* Effect.forEach(
+        databases,
+        (db) =>
+          planetscale.listBranches.pages({ organization, database: db.name }).pipe(
+            Stream.runCollect,
+            Effect.map((chunk) =>
+              Array.from(chunk).flatMap((page) =>
+                page.data
+                  .filter((branch) => branch.kind === opts.expectedKind)
+                  .map(
+                    (branch) =>
+                      ({
+                        name: branch.name,
+                        organization,
+                        database: db.name,
+                        parentBranch: branch.parent_branch ?? "main",
+                        production: branch.production,
+                        createdAt: branch.created_at,
+                        updatedAt: branch.updated_at,
+                        htmlUrl: branch.html_url,
+                        region: { slug: branch.region.slug },
+                        migrationsDir: undefined,
+                        migrationsTable: undefined,
+                        migrationsHashes: {},
+                        importHashes: {},
+                        desiredReplicas: undefined,
+                        hasReplicas: branch.has_replicas,
+                        hasReadOnlyReplicas: branch.has_read_only_replicas,
+                      }) satisfies BaseBranchAttributes,
+                  ),
+              ),
+            ),
+            // A database can be deleted between enumeration and the
+            // per-database branch list — skip it rather than fail.
+            Effect.catchTag("NotFound", () => Effect.succeed([] as BaseBranchAttributes[])),
+          ),
+        { concurrency: 10 },
+      );
+
+      return rows.flat();
+    }),
+
+    diff: Effect.fn(function* ({ news, olds, output }: any) {
+      if (!isResolved(news)) return undefined;
+
+      // Branch names are rename-mutable (reconcile syncs `news.name` in
+      // place), so `name` cannot live in the provider-level stables. But
+      // almost no update is a rename — for those, advertise `name` as
+      // stable on the update so downstream consumers referencing this
+      // branch still resolve `branch.name` at plan time. Without it, a
+      // metadata-only update (e.g. an embedded database ref whose
+      // `migrationsHashes` moved) resolves consumer refs to just
+      // `{ organization, database }`, and identity-sensitive consumers
+      // (PostgresRole) falsely plan a replacement against `name: undefined`.
+      //
+      // 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 — the instance id only rotates on replacement).
+      const nameIsStable =
+        output?.name !== undefined &&
+        (news.name !== undefined ? news.name === output.name : olds?.name === undefined);
+      const stables = nameIsStable ? ["organization", "database", "name"] : undefined;
+
+      const newDb = resolveDatabase(news.database).name;
+      const oldDbRef = output?.database ?? olds.database;
+      if (oldDbRef) {
+        const oldDb = resolveDatabase(oldDbRef).name;
+        if (newDb !== oldDb) {
+          return { action: "replace" } as const;
+        }
+      }
+
+      const newParent = resolveParent(news.parentBranch);
+      const oldParent = output?.parentBranch ?? resolveParent(olds.parentBranch);
+      if (newParent !== oldParent) {
+        return { action: "replace" } as const;
+      }
+
+      if (news.region?.slug && output?.region?.slug && news.region.slug !== output.region.slug) {
+        return { action: "replace" } as const;
+      }
+
+      if (news.replicas !== undefined) {
+        if (output?.desiredReplicas !== news.replicas) {
+          return { action: "update", stables } as const;
+        }
+
+        const desiredHasReplicas = news.replicas > 0;
+        if (output?.hasReplicas !== undefined && output.hasReplicas !== desiredHasReplicas) {
+          return { action: "update", stables } as const;
+        }
+      }
+
+      const migrationChange = yield* classifyMigrationHistory({
+        news,
+        output,
+      });
+      if (migrationChange.kind === "rewritten") {
+        // Editing or deleting an already-applied file cannot be replayed
+        // in place (apply is name-keyed). Development branches re-fork
+        // from the parent and apply from scratch; production must add a
+        // forward migration instead.
+        const production = output?.production === true || news.isProduction === true;
+        if (production) {
+          return yield* new RewrittenMigrationHistoryError({
+            changed: migrationChange.changed,
+            removed: migrationChange.removed,
+            message:
+              `Cannot rewrite applied migration history on production PlanetScale branch ` +
+              `"${output?.name ?? news.name ?? "unknown"}" ` +
+              `(${describeRewrittenHistory(migrationChange)}). ` +
+              "Add a new forward migration instead of editing or deleting already-applied files.",
+          });
+        }
+        return { action: "replace" } as const;
+      }
+      if (migrationChange.kind === "pending") {
+        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, safeMigrations, clusterSize,
+      // metadata embedded in resource refs) are all 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, olds, output }: any) {
+      // If we have neither a cached output nor a usable `olds.database`
+      // there's no way to identify which branch to refresh — most often
+      // this is destroy of a partially-created resource whose props
+      // never got fully persisted. Return `undefined` so the engine
+      // treats it as already-gone and drops the state entry.
+      if (!output && !olds?.database) {
+        return undefined;
+      }
+      const dbInfo = output
+        ? { name: output.database, organization: output.organization }
+        : resolveDatabase(olds.database);
+      const { organization: envOrg } = yield* yield* Credentials;
+      const organization = output?.organization ?? dbInfo.organization ?? envOrg;
+      const databaseName = output?.database ?? dbInfo.name;
+      const branchName = output?.name ?? (yield* createBranchName(id, olds.name));
+
+      return yield* planetscale
+        .getBranch({
+          organization,
+          database: databaseName,
+          branch: branchName,
+        })
+        .pipe(
+          Effect.map((data) => {
+            const attrs = {
+              name: data.name,
+              organization,
+              database: databaseName,
+              parentBranch: data.parent_branch ?? "main",
+              production: data.production,
+              createdAt: data.created_at,
+              // PlanetScale bumps `updated_at` asynchronously (e.g. seconds
+              // after a deploy, on role creation, maintenance) without any
+              // config change, so the observed value is volatile. Keep the
+              // value recorded by the last reconcile so drift detection only
+              // flags real configuration changes (#1955).
+              updatedAt: output?.updatedAt ?? data.updated_at,
+              htmlUrl: data.html_url,
+              region: { slug: data.region.slug },
+              migrationsDir: output?.migrationsDir ?? olds?.migrationsDir,
+              migrationsTable: output?.migrationsTable ?? olds?.migrationsTable,
+              migrationsHashes: output?.migrationsHashes ?? {},
+              importHashes: output?.importHashes ?? {},
+              desiredReplicas: output?.desiredReplicas ?? olds?.desiredReplicas ?? olds?.replicas,
+              hasReplicas: data.has_replicas,
+              hasReadOnlyReplicas: data.has_read_only_replicas,
+            } satisfies BaseBranchAttributes;
+
+            return output ? attrs : Unowned(attrs);
+          }),
+          Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+        );
+    }),
+
+    reconcile: Effect.fn(function* ({ id, news, output, session }: any) {
+      const { organization: envOrg } = yield* yield* Credentials;
+      const dbInfo = resolveDatabase(news.database);
+      const organization = output?.organization ?? dbInfo.organization ?? envOrg;
+      const databaseName = output?.database ?? dbInfo.name;
+      const desiredBranchName = yield* createBranchName(id, news.name);
+      const observedBranchName = output?.name ?? desiredBranchName;
+      const parentBranchName = resolveParent(news.parentBranch);
+
+      // If parentBranch is a plain string (an unmanaged branch reference),
+      // wait for it to be ready before we touch the child branch. When it
+      // is a Branch resource, Alchemy's resource graph already guarantees
+      // readiness before this resource's inputs are resolved.
+      if (news.parentBranch && typeof news.parentBranch === "string") {
+        yield* waitForBranchReady(organization, databaseName, parentBranchName, session);
+      }
+
+      // Observe — fetch the live branch state.
+      let current = yield* planetscale
+        .getBranch({
+          organization,
+          database: databaseName,
+          branch: observedBranchName,
+        })
+        .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+
+      // Ensure — if missing, create. The parent must be ready before
+      // the child can fork from it. PostgreSQL short cluster sizes need
+      // to be expanded against the parent's region so the API call lands
+      // with a valid sku.
+      if (!current) {
+        const parent = yield* waitForBranchReady(
+          organization,
+          databaseName,
+          parentBranchName,
+          session,
+        );
+        const parentClusterSize = news.clusterSize
+          ? parent.kind === "postgresql"
+            ? toPostgresClusterSku({
+                size: news.clusterSize,
+                arch: toPostgresClusterArch(parent.cluster_architecture),
+                region: parent.region.slug,
+              })
+            : news.clusterSize
+          : undefined;
+        yield* session.note("Creating branch...");
+        current = yield* planetscale.createBranch({
+          organization,
+          database: databaseName,
+          name: desiredBranchName,
+          parent_branch: parentBranchName,
+          backup_id: news.backupId,
+          seed_data: news.seedData,
+          region: news.region?.slug,
+          cluster_size: parentClusterSize,
+        });
+      }
+
+      if (current.kind !== opts.expectedKind) {
+        return yield* new PlanetscaleConflict({
+          message:
+            `Planetscale branch "${current.name}" (database "${databaseName}") has kind ` +
+            `"${current.kind}" but this resource is a ${opts.engineLabel}. ` +
+            `Use the matching ${current.kind === "mysql" ? "MySQLBranch" : "PostgresBranch"} ` +
+            `resource instead.`,
+        });
+      }
+
+      yield* waitForBranchReady(organization, databaseName, current.name, session);
+
+      // Sync name — branch names are mutable. Continue subsequent syncs
+      // under the name returned by the API.
+      if (current.name !== desiredBranchName) {
+        current = yield* planetscale.updateBranch({
+          organization,
+          database: databaseName,
+          branch: current.name,
+          new_name: desiredBranchName,
+        });
+      }
+
+      const branchName = current.name;
+
+      // Sync production status before branch settings that depend on it.
+      // PlanetScale only supports explicit branch promotion/demotion for MySQL.
+      if (opts.expectedKind === "mysql") {
+        const desiredProduction = news.isProduction ?? false;
+        if (current.production !== desiredProduction) {
+          // A keyspace can report `resizing: false` while the resize
+          // workflow is still finalizing, during which promote/demote is
+          // rejected with an UnprocessableEntity. Retry until it clears.
+          const retryWhileResizing = Effect.retry({
+            while: isResizeInProgress,
+            schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(120)]),
+          });
+          current = desiredProduction
+            ? yield* planetscale
+                .promoteBranch({
+                  organization,
+                  database: databaseName,
+                  branch: branchName,
+                })
+                .pipe(retryWhileResizing)
+            : yield* planetscale
+                .demoteBranch({
+                  organization,
+                  database: databaseName,
+                  branch: branchName,
+                })
+                .pipe(retryWhileResizing);
+        }
+      }
+
+      // Sync safeMigrations — observed via `current.safe_migrations`,
+      // skip the API call entirely on no-op.
+      if (news.safeMigrations !== undefined && current.safe_migrations !== news.safeMigrations) {
+        if (news.safeMigrations) {
+          yield* planetscale.enableSafeMigrations({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+        } else {
+          yield* planetscale.disableSafeMigrations({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+        }
+      }
+
+      if (opts.expectedKind === "postgresql" && news.replicas !== undefined) {
+        const desiredReplicas = news.replicas;
+        const desiredHasReplicas = desiredReplicas > 0;
+        const shouldApplyReplicaChange =
+          current.has_replicas !== desiredHasReplicas ||
+          (desiredHasReplicas && output?.desiredReplicas !== desiredReplicas);
+
+        if (shouldApplyReplicaChange) {
+          yield* waitForPendingPostgresChanges(organization, databaseName, branchName);
+          const change = yield* planetscale.updateBranchChangeRequest({
+            organization,
+            database: databaseName,
+            branch: branchName,
+            replicas: desiredReplicas,
+          });
+          yield* waitForPendingPostgresChanges(organization, databaseName, branchName, change.id);
+          current = yield* planetscale.getBranch({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+        }
+      }
+
+      // Sync clusterSize — only meaningful on production branches.
+      if (news.clusterSize) {
+        if (current.kind === "postgresql") {
+          yield* ensurePostgresProductionBranchClusterSize(
+            organization,
+            databaseName,
+            branchName,
+            news.clusterSize,
+          );
+        } else {
+          yield* ensureMySQLProductionBranchClusterSize(
+            organization,
+            databaseName,
+            branchName,
+            news.clusterSize,
+          );
+        }
+      }
+
+      // Re-read so the returned attributes reflect any mutation.
+      const updated = yield* planetscale.getBranch({
+        organization,
+        database: databaseName,
+        branch: branchName,
+      });
+
+      const migrationTarget = {
+        organization,
+        database: databaseName,
+        branch: updated.name,
+      };
+
+      const migrationsInput = migrationsInputOf(news);
+      const migrations = migrationsInput
+        ? yield* opts.runners.runMigrations(migrationTarget, migrationsInput, stampedOf(output))
+        : undefined;
+      const importHashes = news.importFiles?.length
+        ? yield* opts.runners.runImports(
+            migrationTarget,
+            news.importFiles,
+            yield* rootDir,
+            output?.importHashes ?? {},
+          )
+        : {};
+
+      return {
+        name: updated.name,
+        organization,
+        database: databaseName,
+        parentBranch: updated.parent_branch ?? parentBranchName,
+        production: updated.production,
+        createdAt: updated.created_at,
+        updatedAt: updated.updated_at,
+        htmlUrl: updated.html_url,
+        region: { slug: updated.region.slug },
+        ...migrationsAttrs({ input: migrationsInput, run: migrations, output }),
+        importHashes,
+        desiredReplicas: news.replicas ?? output?.desiredReplicas,
+        hasReplicas: updated.has_replicas,
+        hasReadOnlyReplicas: updated.has_read_only_replicas,
+      } satisfies BaseBranchAttributes;
+    }),
+
+    delete: Effect.fn(function* ({ output }: any) {
+      // If `read` returned undefined (e.g. destroy of a partially-
+      // created branch whose props never finished persisting), there
+      // is nothing addressable to delete. Drop the state entry.
+      if (!output) return;
+      yield* planetscale
+        .deleteBranch({
+          organization: output.organization,
+          database: output.database,
+          branch: output.name,
+        })
+        .pipe(
+          Effect.catchTag("NotFound", () => Effect.void),
+          Effect.catchIf(
+            isKnownError("UnprocessableEntity", "The default branch cannot be deleted."),
+            () => Effect.void,
+          ),
+        );
+    }),
+  } as any);

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "planetscale",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.PlanetscaleAuth,
+  ),
+});