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

package/src/Postgres/PostgresDatabase.ts

@@ -0,0 +1,469 @@
+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());