alchemy 2.0.0-beta.41 → 2.0.0-beta.43

package/src/Planetscale/Database.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+   */
+  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.
+   */
+  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;
+
+  /**
+   * The default branch of the database.
+   * @default "main"
+   */
+  defaultBranch?: string;
+
+  /**
+   * Directory containing `.sql` migration files. Files are sorted by numeric
+   * prefix (for example `0001_init.sql`) and applied in order against the
+   * default branch.
+   */
+  migrationsDir?: string;
+
+  /**
+   * Name of the table used to track applied migrations.
+   * @default "planetscale_migrations"
+   */
+  migrationsTable?: string;
+
+  /**
+   * 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;
+}

package/src/Planetscale/MySQL/MySQLBranch.ts

@@ -0,0 +1,112 @@
+import { Resource } from "../../Resource.ts";
+import {
+  type BaseBranchAttributes,
+  type BaseBranchProps,
+  makeBranchProvider,
+} from "../Branch.ts";
+import type { Providers } from "../Providers.ts";
+import type { MySQLClusterSize } from "./MySQLClusterSize.ts";
+import { runMySQLImports, runMySQLMigrations } from "./MySQLMigrations.ts";
+import type { MySQLDatabase } from "./MySQLDatabase.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.
+ *
+ * @section 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,
+ * });
+ * ```
+ *
+ * @section 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",
+ * });
+ * ```
+ *
+ * @section 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
+>;
+
+export const MySQLBranch = Resource<MySQLBranch>("Planetscale.MySQLBranch");
+
+export const MySQLBranchProvider = () =>
+  makeBranchProvider({
+    resource: MySQLBranch,
+    expectedKind: "mysql",
+    engineLabel: "MySQLBranch",
+    runners: {
+      runMigrations: runMySQLMigrations,
+      runImports: runMySQLImports,
+    },
+  });

package/src/Planetscale/MySQL/MySQLClusterSize.ts

@@ -0,0 +1,102 @@
+import * as ops from "@distilled.cloud/planetscale/Operations";
+import * as Effect from "effect/Effect";
+import { 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`,
+    ops.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;
+    },
+  );
+});
+
+/**
+ * Ensures the default keyspace of a MySQL production branch has the
+ * expected cluster size, triggering a resize if it doesn't. Cluster sizes
+ * can only be configured on production branches.
+ */
+export const ensureMySQLProductionBranchClusterSize = Effect.fn(function* (
+  organization: string,
+  database: string,
+  branch: string,
+  expectedClusterSize: MySQLClusterSize,
+) {
+  const keyspaces = yield* ops.listKeyspaces({
+    organization,
+    database,
+    branch,
+    page: 1,
+    per_page: 100,
+  });
+  // Default keyspace is always the same name as the database.
+  const defaultKeyspace = keyspaces.data.find((x) => x.name === database);
+  if (!defaultKeyspace) {
+    return yield* Effect.die(`No default keyspace found for branch ${branch}`);
+  }
+
+  yield* waitForKeyspaceReady(
+    organization,
+    database,
+    branch,
+    defaultKeyspace.name,
+  );
+
+  if (defaultKeyspace.cluster_name !== expectedClusterSize) {
+    yield* ops.updateBranchClusterConfig({
+      organization,
+      database,
+      branch,
+      cluster_size: expectedClusterSize,
+    });
+    yield* waitForKeyspaceReady(
+      organization,
+      database,
+      branch,
+      defaultKeyspace.name,
+    );
+  }
+});