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

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 {
  ensurePostgresProductionBranchClusterSize,
  toPostgresClusterArch,
  toPostgresClusterSku,
  type PostgresClusterSize,
} from "./PostgresClusterSize.ts";
import { runPostgresImports, runPostgresMigrations } from "./PostgresMigrations.ts";

/**
 * Properties for creating or updating a PostgreSQL PlanetScale database.
 */
export interface PostgresDatabaseProps extends BaseDatabaseProps {
  /**
   * The PostgreSQL database cluster size. Required.
   *
   * Short NAS sizes (`"PS_10"`) are expanded using the target region and
   * architecture. [PlanetScale Metal](https://planetscale.com/docs/metal)
   * requires the full SKU (e.g. `"M1_10_AWS_ARM_D_METAL_10"`) because
   * Metal also encodes CPU series, architecture, and NVMe drive size.
   *
   * @see https://planetscale.com/docs/postgres/pricing
   * @see {@link PostgresClusterSize}
   */
  clusterSize: PostgresClusterSize;

  /**
   * PostgreSQL major version. Defaults to the latest available major
   * version.
   */
  majorVersion?: string;

  /**
   * CPU architecture. Cannot be changed after creation.
   * @default "x86"
   */
  arch?: "x86" | "arm";
}

/**
 * Output attributes of a deployed PostgreSQL PlanetScale database.
 */
export interface PostgresDatabaseAttributes extends BaseDatabaseAttributes {
  /** PostgreSQL CPU architecture. */
  arch: "x86" | "arm";
}

/**
 * A PostgreSQL PlanetScale database. For MySQL, use {@link MySQLDatabase}
 * instead.
 *
 * ### Creating a PostgreSQL Database
 * **Example:** Basic PostgreSQL database
 * ```typescript
 * const db = yield* Planetscale.PostgresDatabase("MyDb", {
 *   clusterSize: "PS_10",
 * });
 * ```
 *
 * **Example:** PlanetScale Metal (NVMe)
 * ```typescript
 * const db = yield* Planetscale.PostgresDatabase("MyDb", {
 *   clusterSize: "M1_10_AWS_ARM_D_METAL_10",
 *   arch: "arm",
 * });
 * ```
 *
 * ### Migrations and seed data
 * **Example:** Apply migrations and seed files
 * ```typescript
 * const db = yield* Planetscale.PostgresDatabase("MyDb", {
 *   clusterSize: "PS_10",
 *   migrationsDir: "./migrations/postgres",
 *   importFiles: ["./seed/postgres.sql"],
 * });
 * ```
 *
 * ### Deletion protection
 * **Example:** Refuse deletes of a production database
 * ```typescript
 * const db = yield* Planetscale.PostgresDatabase("MyDb", {
 *   clusterSize: "PS_10",
 *   deletionProtection: true,
 * });
 * ```
 *
 * ### Adoption
 * **Example:** Adopting an existing database
 * ```typescript
 * import { adopt } from "alchemy/AdoptPolicy";
 *
 * const db = yield* Planetscale.PostgresDatabase("Existing", {
 *   name: "existing-db",
 *   clusterSize: "PS_10",
 * }).pipe(adopt());
 * ```
 */
export type PostgresDatabase = Resource<
  "Planetscale.PostgresDatabase",
  PostgresDatabaseProps,
  PostgresDatabaseAttributes,
  never,
  Providers
>;

/** @resource */
export const PostgresDatabase = Resource<PostgresDatabase>("Planetscale.PostgresDatabase");

export const PostgresDatabaseProvider = () =>
  Provider.succeed(PostgresDatabase, {
    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, roles) 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 && output?.region?.slug && news.region.slug !== output.region.slug) {
        return yield* replaceDatabase(news, output, "region");
      }

      if (news.replicas !== olds.replicas) {
        return yield* replaceDatabase(news, output, "replicas");
      }

      const oldArch = output?.arch ?? olds.arch ?? "x86";
      if (news.arch && news.arch !== oldArch) {
        return yield* replaceDatabase(news, output, "arch");
      }

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

      const data = yield* planetscale
        .getDatabase({
          organization,
          database: databaseName,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

      if (!data) return undefined;

      if (data.kind !== "postgresql") {
        return yield* new PlanetscaleConflict({
          message:
            `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
            `is a PostgresDatabase. Use Planetscale.${data.kind === "mysql" ? "MySQLDatabase" : data.kind}() instead, ` +
            `or delete the existing database and retry.`,
        });
      }

      const defaultBranch = data.default_branch ?? "main";

      // Observe `arch` and `clusterSize` from the default branch rather
      // than echoing input.
      const branch = yield* planetscale
        .getBranch({
          organization,
          database: data.name,
          branch: defaultBranch,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

      const arch = toPostgresClusterArch(branch!.cluster_architecture);
      const clusterSize = branch!.cluster_name;

      return {
        id: data.id,
        name: data.name,
        organization,
        state: data.state,
        defaultBranch,
        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,
        arch,
        requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
        restrictBranchRegion: data.restrict_branch_region ?? false,
        productionBranchWebConsole: data.production_branch_web_console ?? false,
        deletionProtection: data.deletion_protected ?? false,
      };
    }),

    reconcile: Effect.fn(function* ({ id, news, output, session }) {
      const { organization } = yield* yield* Credentials;
      const newName = yield* createDatabaseName(id, news.name);
      const clusterSize = toPostgresClusterSku({
        size: news.clusterSize,
        arch: news.arch,
        region: news.region?.slug,
      });

      // 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...");
        observed = yield* planetscale.createDatabase({
          organization,
          name: newName,
          region: news.region?.slug,
          kind: "postgresql",
          cluster_size: clusterSize,
          replicas: news.replicas,
          major_version: news.majorVersion,
        });
      }

      // 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 !== "postgresql") {
        return yield* new PlanetscaleConflict({
          message:
            `Planetscale database "${observed.name}" has kind "${observed.kind}" but this resource ` +
            `is a PostgresDatabase. Use Planetscale.${observed.kind === "mysql" ? "MySQLDatabase" : 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",
          });
        }
      }

      // Sync settings — `updateSettings` is upsert-shaped, so we can
      // call it with the full desired payload on every reconcile.
      // Folds the rename in via `new_name` so we don't pay for a
      // separate PATCH.
      const updated = yield* planetscale.updateDatabaseSettings({
        organization,
        database: observed.name,
        new_name: newName !== observed.name ? newName : undefined,
        require_approval_for_deploy: news.requireApprovalForDeploy,
        restrict_branch_region: news.restrictBranchRegion,
        production_branch_web_console: news.productionBranchWebConsole,
        deletion_protected: news.deletionProtection,
        default_branch: news.defaultBranch,
      });

      // Sync cluster size on the active default branch.
      const branch = news.defaultBranch ?? updated.default_branch ?? "main";
      yield* ensurePostgresProductionBranchClusterSize(
        organization,
        updated.name,
        branch,
        news.clusterSize,
      );

      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* runPostgresMigrations(migrationTarget, migrationsInput, stampedOf(output))
        : undefined;
      const importHashes = news.importFiles?.length
        ? yield* runPostgresImports(
            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: clusterSize,
        ...migrationsAttrs({ input: migrationsInput, run: migrations, output }),
        importHashes,
        arch: news.arch ?? output?.arch ?? "x86",
        requireApprovalForDeploy: updated.require_approval_for_deploy ?? false,
        restrictBranchRegion: updated.restrict_branch_region ?? false,
        productionBranchWebConsole: updated.production_branch_web_console ?? false,
        deletionProtection: updated.deletion_protected ?? false,
      } satisfies PostgresDatabaseAttributes;
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* deleteUnprotectedDatabase(output.organization, output.name);
    }),

    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.filter((db) => db.kind === "postgresql")),
        ),
      );

      const rows = yield* Effect.forEach(
        databases,
        (data) =>
          Effect.gen(function* () {
            const defaultBranch = data.default_branch ?? "main";
            const branch = yield* planetscale
              .getBranch({
                organization,
                database: data.name,
                branch: defaultBranch,
              })
              .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

            const arch = toPostgresClusterArch(branch?.cluster_architecture);
            const clusterSize = branch?.cluster_name ?? "";

            const attrs: PostgresDatabase["Attributes"] = {
              id: data.id,
              name: data.name,
              organization,
              state: data.state,
              defaultBranch,
              plan: data.plan ?? "hobby",
              createdAt: data.created_at,
              updatedAt: data.updated_at,
              htmlUrl: data.html_url,
              region: { slug: data.region.slug },
              clusterSize,
              migrationsDir: undefined,
              migrationsTable: undefined,
              migrationsHashes: {},
              importHashes: {},
              arch,
              requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
              restrictBranchRegion: data.restrict_branch_region ?? false,
              productionBranchWebConsole: data.production_branch_web_console ?? false,
              deletionProtection: data.deletion_protected ?? false,
            };
            return attrs;
          }),
        { concurrency: 10 },
      );

      return rows;
    }),
  });

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