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

package/src/Credentials.ts

@@ -0,0 +1,116 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  type Config as PlanetscaleClientConfig,
+  Credentials,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/planetscale/Credentials";
+import * as CredentialsCache from "alchemy/Auth/CredentialsCache";
+import {
+  deferUntilFirstUse,
+  orDieCredentialsUnavailable,
+  resolveProviderConfig,
+} from "alchemy/Auth/Resolve";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import {
+  PLANETSCALE_AUTH_PROVIDER_NAME,
+  type PlanetscaleAuthConfig,
+  type PlanetscaleResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/planetscale/Credentials";
+
+/**
+ * Build a PlanetScale `Credentials` Layer from an explicit token. Useful for
+ * tests or when the caller already has credentials in hand.
+ *
+ * @example
+ * ```ts
+ * Effect.provide(
+ *   Planetscale.fromToken({
+ *     tokenId: "abcd1234",
+ *     token: "api-token-secret",
+ *     organization: "my-org",
+ *   }),
+ * )
+ * ```
+ */
+export const fromToken = (input: {
+  tokenId: string | Redacted.Redacted<string>;
+  token: string | Redacted.Redacted<string>;
+  organization: string;
+  apiBaseUrl?: string;
+}) =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({
+      tokenId: typeof input.tokenId === "string" ? Redacted.make(input.tokenId) : input.tokenId,
+      token: typeof input.token === "string" ? Redacted.make(input.token) : input.token,
+      organization: input.organization,
+      apiBaseUrl: input.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+    }),
+  );
+
+/**
+ * Build a PlanetScale `Credentials` Layer that resolves credentials via the
+ * Alchemy AuthProvider using the configured profile (defaults to "default",
+ * selected by the current Alchemy profile).
+ */
+export const fromAuthProvider = () =>
+  Layer.effect(
+    Credentials,
+    Effect.gen(function* () {
+      const apiBaseUrl = yield* Config.String("PLANETSCALE_API_BASE_URL").pipe(
+        Config.withDefault(DEFAULT_API_BASE_URL),
+      );
+      // Defer profile lookup and credential resolution until first use, so
+      // building the provider layers never requires a configured profile.
+      const resolve = yield* resolveProviderConfig<
+        PlanetscaleAuthConfig,
+        PlanetscaleResolvedCredentials
+      >(PLANETSCALE_AUTH_PROVIDER_NAME).pipe(
+        Effect.flatMap(({ profileName, resolve }) =>
+          Effect.mapError(resolve, (e) =>
+            ConfigError.make({
+              message: `Failed to resolve Planetscale credentials from ${profileName === undefined ? "the CI environment" : `profile '${profileName}'`}: ${e.message}`,
+            }),
+          ),
+        ),
+        deferUntilFirstUse,
+      );
+
+      // Cache until shortly before the OAuth token expires (service tokens
+      // never expire) so a long `alchemy dev` session re-resolves — and
+      // thereby refreshes — the token instead of keeping the first, by then
+      // dead, resolution forever. The cache wraps `resolve` (not the mapped
+      // client config) because the mapping drops the `expires` timestamp.
+      const cached = yield* CredentialsCache.cacheUntilExpiry(resolve, (creds) =>
+        creds.type === "oauth" ? creds.expires : undefined,
+      );
+      return cached.pipe(
+        Effect.map((creds): PlanetscaleClientConfig =>
+          creds.type === "oauth"
+            ? {
+                type: "oauth",
+                accessToken: creds.accessToken,
+                organization: creds.organization,
+                apiBaseUrl,
+              }
+            : {
+                type: "serviceToken",
+                tokenId: creds.tokenId,
+                token: creds.token,
+                organization: creds.organization,
+                apiBaseUrl,
+              },
+        ),
+        orDieCredentialsUnavailable(PLANETSCALE_AUTH_PROVIDER_NAME),
+      );
+    }),
+  );

package/src/Database.ts

@@ -0,0 +1,152 @@
+import type { MigrationsInput } from "@alchemy.run/sql/Migrations";
+
+/**
+ * Region selector for a PlanetScale Database.
+ */
+export interface DatabaseRegion {
+  /**
+   * Region slug (e.g. `"us-east"`, `"eu-west"`, `"gcp-us-central1"`).
+   * @see https://planetscale.com/docs/concepts/regions#available-regions
+   */
+  slug: "us-east" | "eu-west" | "gcp-us-central1" | (string & {});
+}
+
+/**
+ * Properties shared between {@link MySQLDatabase} and
+ * {@link PostgresDatabase}. Engine-specific props live on the per-engine
+ * resource types.
+ */
+export interface BaseDatabaseProps {
+  /**
+   * Database name. Must be lowercase. If omitted, a unique name will be
+   * generated from the stack/stage/logical-id. A change that replaces the
+   * database needs a new name, so it fails while an explicit name stays
+   * the same.
+   */
+  name?: string;
+
+  /**
+   * Region where the database will be created. Cannot be changed after
+   * creation. If omitted, the organization's default region is used.
+   */
+  region?: DatabaseRegion;
+
+  /**
+   * Number of replicas for the database. `0` for non-HA, `2+` for HA.
+   * Create-only for PostgreSQL databases; MySQL databases reconcile
+   * changes in place ({@link MySQLDatabaseProps.replicas}).
+   */
+  replicas?: number;
+
+  /**
+   * Whether deploy requests must be approved by a database administrator
+   * other than the request creator.
+   */
+  requireApprovalForDeploy?: boolean;
+
+  /**
+   * Whether to limit branch creation to the same region as the one
+   * selected during database creation.
+   */
+  restrictBranchRegion?: boolean;
+
+  /**
+   * Whether the web console can be used on the production branch.
+   */
+  productionBranchWebConsole?: boolean;
+
+  /**
+   * Whether PlanetScale refuses to delete the database. While enabled,
+   * destroying or replacing the database fails with a
+   * `PlanetscaleDeletionProtected` error; set it to `false` and deploy
+   * before deleting. If omitted, Alchemy leaves the database's current
+   * setting unchanged.
+   *
+   * A replacement (e.g. a region change) creates the new database first,
+   * so deleting the protected old one fails afterwards. The resource then
+   * manages the new database, so turn protection off on the old one in
+   * PlanetScale directly and deploy again.
+   */
+  deletionProtection?: boolean;
+
+  /**
+   * The default branch of the database.
+   * @default "main"
+   */
+  defaultBranch?: string;
+
+  /**
+   * SQL migrations to apply against the default branch. Accepts a directory
+   * path, a `Drizzle.Schema` resource, or `{ dir, table? }`.
+   *
+   * Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A
+   * database previously migrated by drizzle-kit or Prisma is adopted by a
+   * one-way conversion on first deploy: the old tool's applied history is
+   * copied into Alchemy's table and the old table is left frozen. No
+   * baselining required.
+   */
+  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[];
+}
+
+/**
+ * Output attributes shared by both database engines.
+ */
+export interface BaseDatabaseAttributes {
+  /** The unique identifier of the database. */
+  id: string;
+  /** The name of the database. */
+  name: string;
+  /** The PlanetScale organization slug that owns the database. */
+  organization: string;
+  /** The current state of the database. */
+  state: string;
+  /** The default branch name. */
+  defaultBranch: string;
+  /** The plan tier (e.g. `"hobby"`, `"scaler"`). */
+  plan: string;
+  /** Time at which the database was created (ISO 8601). */
+  createdAt: string;
+  /** Time at which the database was last updated (ISO 8601). */
+  updatedAt: string;
+  /** HTML URL for accessing the database in the dashboard. */
+  htmlUrl: string;
+  /** The region of the database as reported by PlanetScale. */
+  region: DatabaseRegion;
+  /** The cluster size that was actually applied. */
+  clusterSize: 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>;
+  /**
+   * Whether deploy requests must be approved by a database administrator
+   * other than the request creator.
+   */
+  requireApprovalForDeploy: boolean;
+
+  /**
+   * Whether to limit branch creation to the same region as the one
+   * selected during database creation.
+   */
+  restrictBranchRegion: boolean;
+
+  /**
+   * Whether the web console can be used on the production branch.
+   */
+  productionBranchWebConsole: boolean;
+
+  /**
+   * Whether deletion protection is enabled for the database.
+   */
+  deletionProtection: boolean;
+}

package/src/MySQL/MySQLBranch.ts

@@ -0,0 +1,109 @@
+import { Resource } from "alchemy/Resource";
+import { type BaseBranchAttributes, type BaseBranchProps, makeBranchProvider } from "../Branch.ts";
+import type { Providers } from "../Providers.ts";
+import type { MySQLClusterSize } from "./MySQLClusterSize.ts";
+import type { MySQLDatabase } from "./MySQLDatabase.ts";
+import { runMySQLImports, runMySQLMigrations } from "./MySQLMigrations.ts";
+
+/**
+ * Properties for creating or updating a {@link MySQLBranch}.
+ */
+export interface MySQLBranchProps extends BaseBranchProps {
+  /**
+   * Whether the branch should be a production branch.
+   */
+  isProduction: boolean;
+
+  /**
+   * The MySQL database. Either a string database name or a
+   * {@link MySQLDatabase} resource.
+   */
+  database: string | MySQLDatabase;
+
+  /**
+   * MySQL cluster size for the branch. Required if `backupId` is provided.
+   * For non-production branches must be `"PS_DEV"`.
+   */
+  clusterSize?: MySQLClusterSize;
+
+  /**
+   * Parent branch — either a string name or another {@link MySQLBranch}.
+   * @default "main"
+   */
+  parentBranch?: string | MySQLBranch;
+}
+
+/**
+ * Output attributes of a deployed {@link MySQLBranch}.
+ */
+export interface MySQLBranchAttributes extends BaseBranchAttributes {}
+
+/**
+ * A PlanetScale branch of a {@link MySQLDatabase}. For PostgreSQL branches
+ * use {@link PostgresBranch} instead.
+ *
+ * ### Creating a Branch
+ * **Example:** Branch from main
+ * ```typescript
+ * const branch = yield* Planetscale.MySQLBranch("Feature123", {
+ *   database: "my-db",
+ *   parentBranch: "main",
+ *   isProduction: false,
+ * });
+ * ```
+ *
+ * **Example:** Branch from a MySQLDatabase resource
+ * ```typescript
+ * const db = yield* Planetscale.MySQLDatabase("MyDb", { clusterSize: "PS_10" });
+ * const branch = yield* Planetscale.MySQLBranch("Feature456", {
+ *   database: db,
+ *   parentBranch: "main",
+ *   isProduction: false,
+ * });
+ * ```
+ *
+ * ### Restoring from Backup
+ * **Example:** Branch restored from a backup
+ * ```typescript
+ * const branch = yield* Planetscale.MySQLBranch("Restored", {
+ *   database: "my-db",
+ *   parentBranch: "main",
+ *   isProduction: true,
+ *   backupId: "backup-123",
+ *   clusterSize: "PS_10",
+ * });
+ * ```
+ *
+ * ### Migrations and seed data
+ * **Example:** Apply migrations on a branch
+ * ```typescript
+ * const branch = yield* Planetscale.MySQLBranch("Feature123", {
+ *   database: db,
+ *   parentBranch: "main",
+ *   isProduction: false,
+ *   migrationsDir: "./migrations",
+ *   importFiles: ["./seed.sql"],
+ * });
+ * ```
+ */
+export type MySQLBranch = Resource<
+  "Planetscale.MySQLBranch",
+  MySQLBranchProps,
+  MySQLBranchAttributes,
+  never,
+  Providers
+>;
+
+/** @resource */
+export const MySQLBranch = Resource<MySQLBranch>("Planetscale.MySQLBranch");
+
+export const MySQLBranchProvider = () =>
+  makeBranchProvider({
+    resource: MySQLBranch,
+    expectedKind: "mysql",
+    engineLabel: "MySQLBranch",
+    runners: {
+      runMigrations: runMySQLMigrations,
+      runImports: runMySQLImports,
+    },
+  });

package/src/MySQL/MySQLClusterSize.ts

@@ -0,0 +1,185 @@
+import * as ps from "@distilled.cloud/planetscale";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { PlanetscaleConflict, pollUntil } from "../Util.ts";
+
+/**
+ * Available PlanetScale MySQL (Vitess) cluster sizes.
+ *
+ * `PS_*` sizes are backed by network-attached storage (NAS) and can be
+ * specified either as the short size (`"PS_10"`) or the API SKU
+ * (`"PS_10_AWS_X86"`)
+ *
+ * @see https://planetscale.com/docs/concepts/planetscale-skus
+ */
+export type MySQLClusterSize =
+  | "PS_DEV"
+  | "PS_5"
+  | "PS_10"
+  | "PS_20"
+  | "PS_40"
+  | "PS_80"
+  | "PS_160"
+  | "PS_320"
+  | "PS_400"
+  | "PS_640"
+  | "PS_700"
+  | "PS_900"
+  | "PS_1280"
+  | "PS_1400"
+  | "PS_1800"
+  | "PS_2100"
+  | "PS_2560"
+  | "PS_2700"
+  | "PS_2800"
+  | (string & {});
+
+/**
+ * Polls keyspaces in a branch until the named keyspace reports
+ * `resizing === false` (i.e. any in-flight resize has completed).
+ */
+export const waitForKeyspaceReady = Effect.fn(function* (
+  organization: string,
+  database: string,
+  branch: string,
+  keyspace: string,
+) {
+  yield* pollUntil(
+    `keyspace "${keyspace}" not resizing`,
+    ps.listKeyspaces({ organization, database, branch }),
+    (page) => {
+      const ks = page.data.find((x) => x.name === keyspace);
+      // If keyspace is missing, treat as ready (caller will re-check)
+      return ks ? !ks.resizing : true;
+    },
+  );
+});
+
+/**
+ * Observes the default keyspace of a branch. The default keyspace usually
+ * shares the database's name, but a renamed database keeps its original
+ * keyspace name, so prefer the `default` flag and fall back to name
+ * matching.
+ */
+const observeDefaultKeyspace = Effect.fn(function* (
+  organization: string,
+  database: string,
+  branch: string,
+) {
+  const keyspaces = yield* ps.listKeyspaces({
+    organization,
+    database,
+    branch,
+    page: 1,
+    per_page: 100,
+  });
+  return keyspaces.data.find((x) => x.default) ?? keyspaces.data.find((x) => x.name === database);
+});
+
+/**
+ * Observes the total replica count of a branch's default keyspace, or
+ * `undefined` when the branch or keyspace does not exist (yet).
+ */
+export const observeDefaultKeyspaceReplicas = Effect.fn(function* (
+  organization: string,
+  database: string,
+  branch: string,
+) {
+  return yield* observeDefaultKeyspace(organization, database, branch).pipe(
+    Effect.map((keyspace) => keyspace?.replicas),
+    Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+  );
+});
+
+/**
+ * Ensures the default keyspace of a MySQL production branch has the
+ * expected cluster size and (optionally) total replica count, driving
+ * PlanetScale's in-place keyspace resize lifecycle when it doesn't.
+ * Cluster sizes can only be configured on production branches. Returns
+ * the final observed keyspace.
+ */
+export const ensureMySQLProductionBranchClusterSize = Effect.fn(function* (
+  organization: string,
+  database: string,
+  branch: string,
+  expectedClusterSize: MySQLClusterSize,
+  expectedReplicas?: number,
+) {
+  let keyspace = yield* observeDefaultKeyspace(organization, database, branch);
+  if (!keyspace) {
+    return yield* Effect.die(`No default keyspace found for branch ${branch}`);
+  }
+
+  yield* waitForKeyspaceReady(organization, database, branch, keyspace.name);
+
+  if (keyspace.cluster_name !== expectedClusterSize) {
+    yield* ps.updateBranchClusterConfig({
+      organization,
+      database,
+      branch,
+      cluster_size: expectedClusterSize,
+    });
+    yield* waitForKeyspaceReady(organization, database, branch, keyspace.name);
+    // Re-observe so the replica sync below diffs against the post-resize
+    // keyspace state.
+    keyspace = (yield* observeDefaultKeyspace(organization, database, branch)) ?? keyspace;
+  }
+
+  // Sync replicas — MySQL databases cannot configure replicas at
+  // creation time (the API rejects the `replicas` param for mysql), so
+  // the desired total replica count is converged in place via a keyspace
+  // resize request.
+  if (expectedReplicas !== undefined && keyspace.replicas !== expectedReplicas) {
+    // Each cluster size includes a fixed number of replicas (2 for
+    // production PS_* sizes); the resize API only accepts the count of
+    // additional replicas beyond that.
+    const includedReplicas = keyspace.replicas - keyspace.extra_replicas;
+    const extraReplicas = expectedReplicas - includedReplicas;
+    if (extraReplicas < 0) {
+      return yield* new PlanetscaleConflict({
+        message:
+          `Cannot set replicas to ${expectedReplicas} on keyspace "${keyspace.name}": ` +
+          `cluster size ${keyspace.cluster_name} always includes ${includedReplicas} replicas. ` +
+          `Set replicas to ${includedReplicas} or more (or omit it).`,
+      });
+    }
+
+    const resize = yield* ps
+      .updateKeyspaceResizeRequest({
+        organization,
+        database,
+        branch,
+        keyspace: keyspace.name,
+        extra_replicas: extraReplicas,
+      })
+      .pipe(
+        // A prior resize (e.g. the cluster-size change above) can still
+        // be finalizing after the keyspace reports `resizing: false`;
+        // PlanetScale rejects new resize requests during that window.
+        Effect.retry({
+          while: (e): boolean =>
+            e._tag === "UnprocessableEntity" && e.message.includes("resize in progress"),
+          schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(120)]),
+        }),
+      );
+
+    yield* pollUntil(
+      `keyspace "${keyspace.name}" resize completed`,
+      ps.listKeyspaceResizeRequests({
+        organization,
+        database,
+        branch,
+        keyspace: keyspace.name,
+      }),
+      (page) => {
+        const request = page.data.find((r) => r.id === resize.id);
+        // If the request is missing, treat as settled (caller re-observes).
+        return request ? request.state === "completed" : true;
+      },
+    );
+
+    keyspace = (yield* observeDefaultKeyspace(organization, database, branch)) ?? keyspace;
+  }
+
+  return keyspace;
+});