sailfork / t3code-github / .repos/ alchemy-effect/ packages/ planetscale/ src/ Branch.ts

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.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.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);