alchemy 0.64.0 → 0.65.1

package/src/planetscale/password.ts

@@ -102,7 +102,9 @@ export interface Password
 }
 
 /**
- * Create and manage database passwords for PlanetScale branches. Database passwords provide secure access to your database with specific roles and permissions.
+ * Create and manage database passwords for PlanetScale MySQL branches. Database passwords provide secure access to your database with specific roles and permissions.
+ *
+ * For Postgres, use [Roles](./role.ts) instead.
  *
  * @example
  * ## Basic Reader Password

package/src/planetscale/role.ts

@@ -0,0 +1,278 @@
+import { alchemy } from "../alchemy.ts";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
+import { PlanetScaleClient, type PlanetScaleProps } from "./api/client.gen.ts";
+import type { CreateRoleData } from "./api/types.gen.ts";
+import type { Branch } from "./branch.ts";
+import type { Database } from "./database.ts";
+import { waitForBranchReady } from "./utils.ts";
+
+/**
+ * Properties for creating or updating a PlanetScale PostgreSQL Role
+ */
+export interface RoleProps extends PlanetScaleProps {
+  /**
+   * The organization ID where the role will be created
+   * Required when using string database name, optional when using Database resource
+   */
+  organizationId?: string;
+
+  /**
+   * The database where the role will be created
+   * Can be either a database name (string) or Database resource
+   */
+  database: string | Database;
+
+  /**
+   * The branch where the role will be created
+   * Can be either a branch name (string) or Branch resource
+   * @default "main"
+   */
+  branch?: string | Branch;
+
+  /**
+   * Time to live in seconds
+   */
+  ttl?: number;
+
+  /**
+   * Roles to inherit from.
+   * The `"postgres"` role provides full administrator access to the database.
+   * You can also inherit from another Role resource.
+   */
+  inheritedRoles: InheritedRole[] | Role;
+}
+
+/**
+ * Roles that can be inherited from.
+ */
+export type InheritedRole =
+  | "postgres"
+  | "pg_checkpoint"
+  | "pg_create_subscription"
+  | "pg_maintain"
+  | "pg_monitor"
+  | "pg_read_all_data"
+  | "pg_read_all_settings"
+  | "pg_read_all_stats"
+  | "pg_signal_backend"
+  | "pg_stat_scan_tables"
+  | "pg_use_reserved_connections"
+  | "pg_write_all_data"
+  | (string & {});
+
+export interface Role
+  extends Resource<"planetscale::Role">,
+    Omit<RoleProps, "inheritedRoles"> {
+  /**
+   * The unique identifier for the role
+   */
+  id: string;
+
+  /**
+   * The name of the role
+   */
+  name: string;
+
+  /**
+   * The timestamp when the role expires (ISO 8601 format)
+   */
+  expiresAt: string;
+
+  /**
+   * The host URL for database connection
+   */
+  host: string;
+
+  /**
+   * The username for database authentication
+   */
+  username: string;
+
+  /**
+   * The encrypted password for database authentication
+   */
+  password: Secret<string>;
+
+  /**
+   * The database name
+   */
+  databaseName: string;
+
+  /**
+   * The direct connection URL for the database.
+   */
+  connectionUrl: Secret<string>;
+
+  /**
+   * The pooled connection URL for the database.
+   * Uses PSBouncer on port 6432. Recommended for production.
+   * @see https://planetscale.com/docs/postgres/connecting/psbouncer
+   */
+  connectionUrlPooled: Secret<string>;
+
+  /**
+   * The roles that this role inherits from.
+   */
+  inheritedRoles: InheritedRole[];
+}
+
+/**
+ * Create and manage database roles for PlanetScale PostgreSQL branches. Database roles provide secure access to your database with specific roles and permissions.
+ *
+ * For MySQL, use [Passwords](./password.ts) instead.
+ *
+ * @example
+ * ## Basic Role
+ *
+ * Create a default role with all permissions:
+ *
+ * ```ts
+ * const role = await Role("my-role", {
+ *   database: "my-database",
+ *   inheritedRoles: ["postgres"],
+ * });
+ * ```
+ *
+ * ## Role with TTL
+ *
+ * Create a role with a TTL of 1 hour:
+ *
+ * ```ts
+ * const role = await Role("my-role", {
+ *   database: "my-database",
+ *   ttl: 3600,
+ * });
+ * ```
+ *
+ * ## Role with Inherited Permissions
+ *
+ * Create a role with read-only access to all data and settings:
+ *
+ * ```ts
+ * const role = await Role("my-role", {
+ *   database: "my-database",
+ *   inheritedRoles: ["pg_read_all_data", "pg_read_all_settings"],
+ * });
+ * ```
+ */
+export const Role = Resource(
+  "planetscale::Role",
+  async function (
+    this: Context<Role, RoleProps>,
+    id: string,
+    props: RoleProps,
+  ): Promise<Role> {
+    const api = new PlanetScaleClient(props);
+    const organization =
+      typeof props.branch === "object"
+        ? props.branch.organizationId
+        : typeof props.database === "object"
+          ? props.database.organizationId
+          : props.organizationId;
+    const database =
+      typeof props.database === "string" ? props.database : props.database.name;
+    const branch =
+      typeof props.branch === "string"
+        ? props.branch
+        : (props.branch?.name ?? "main");
+    const inheritedRoles = Array.isArray(props.inheritedRoles)
+      ? props.inheritedRoles
+      : props.inheritedRoles.inheritedRoles;
+    if (!organization) {
+      throw new Error("Organization ID is required");
+    }
+
+    switch (this.phase) {
+      case "delete": {
+        if (this.output?.id) {
+          const res = await api.organizations.databases.branches.roles.delete({
+            path: {
+              organization,
+              database,
+              branch,
+              id: this.output.id,
+            },
+            result: "full",
+          });
+          if (res.error) {
+            switch (res.error.status) {
+              case 404:
+                break;
+              case 422:
+                // This is a workaround for 422 unprocessable: Role is still referenced and cannot be dropped.
+                // Essentially, the role is still linked to a branch, so we can't delete it here, but it'll be deleted when the branch is deleted.
+                logger.warn(
+                  [
+                    `Failed to delete role "${id}" (name: "${this.output.name}").`,
+                    `Error: ${res.error.message}`,
+                    `If you are deleting database "${database}" or branch "${branch}", the role will be deleted automatically.`,
+                    `Otherwise, consider manually deleting the role at: https://app.planetscale.com/${organization}/${database}/settings/roles`,
+                  ].join("\n"),
+                );
+                break;
+              default:
+                throw new Error(`Failed to delete role "${id}"`, {
+                  cause: res.error,
+                });
+            }
+          }
+        }
+        return this.destroy();
+      }
+      case "create": {
+        const { kind, ready } = await api.organizations.databases.branches.get({
+          path: {
+            organization,
+            database,
+            name: branch,
+          },
+        });
+        if (kind !== "postgresql") {
+          throw new Error(
+            `Cannot create a role on MySQL database "${database}". Roles are only supported on PostgreSQL databases. For MySQL databases, please use the Password resource instead.`,
+          );
+        }
+        // Cannot create role until branch is ready
+        if (!ready) {
+          await waitForBranchReady(api, organization, database, branch);
+        }
+        const role = await api.organizations.databases.branches.roles.post({
+          path: {
+            organization,
+            database,
+            branch,
+          },
+          body: {
+            ttl: props.ttl,
+            inherited_roles: inheritedRoles,
+          } as CreateRoleData["body"],
+        });
+        return this({
+          ...props,
+          id: role.id,
+          name: role.name,
+          host: role.access_host_url,
+          username: role.username,
+          password: alchemy.secret(role.password),
+          expiresAt: role.expires_at,
+          databaseName: role.database_name,
+          inheritedRoles,
+          connectionUrl: alchemy.secret(
+            `postgresql://${role.username}:${role.password}@${role.access_host_url}:5432/${role.database_name}?sslmode=verify-full`,
+          ),
+          connectionUrlPooled: alchemy.secret(
+            `postgresql://${role.username}:${role.password}@${role.access_host_url}:6432/${role.database_name}?sslmode=verify-full`,
+          ),
+        });
+      }
+      case "update": {
+        // According to the types, the only property that can be updated is the name.
+        // However, I was getting 500 errors when trying to update the name, so we'll just replace.
+        return this.replace();
+      }
+    }
+  },
+);

package/src/planetscale/utils.ts

@@ -1,4 +1,5 @@
 import type { PlanetScaleClient } from "./api/client.gen.ts";
+import type { DatabaseBranch } from "./api/types.gen.ts";
 
 export type PlanetScaleClusterSize =
   | "PS_DEV"
@@ -22,27 +23,62 @@ export type PlanetScaleClusterSize =
   | (string & {});
 
 /**
- * Wait for a database to be ready with exponential backoff
+ * Ensures that the given cluster size is in the correct format.
+ */
+export function sanitizeClusterSize(input: {
+  size: PlanetScaleClusterSize;
+  kind?: "mysql" | "postgresql";
+  arch?: "x86" | "arm";
+  region?: string;
+}): string {
+  // NAS-backed Postgres cluster sizes are formatted as `PS_<size>_<provider>_<arch>`,
+  // where <provider> is either "AWS" or "GCP", and <arch> is either "ARM" or "X86".
+  // Postgres clusters backed by PlanetScale Metal are more complex (e.g. "M6_160_AWS_INTEL_D_METAL_118"),
+  // so to avoid messing with those, we just check for AWS or GCP in the size.
+  if (input.kind === "postgresql" && !input.size.match(/(AWS|GCP)/)) {
+    // Infer the provider from the region.
+    // Not all AWS regions start with "aws-", but all GCP regions start with "gcp-".
+    const provider = input.region?.startsWith("gcp") ? "GCP" : "AWS";
+    const arch = (input.arch ?? "x86").toUpperCase();
+    return `${input.size}_${provider}_${arch}`;
+  }
+  return input.size;
+}
+
+/**
+ * Polls a branch until it is ready.
+ */
+export async function waitForBranchReady(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+): Promise<DatabaseBranch> {
+  return await poll({
+    description: `branch "${branch}" ready`,
+    fn: () =>
+      api.organizations.databases.branches.get({
+        path: { organization, database, name: branch },
+      }),
+    predicate: (branch) => branch.ready,
+  });
+}
+
+/**
+ * Polls a database until it is ready.
  */
 export async function waitForDatabaseReady(
   api: PlanetScaleClient,
   organization: string,
   database: string,
-  branch?: string,
 ): Promise<void> {
   await poll({
-    description: `database "${database}" ${branch ? `branch "${branch}"` : ""} ready`,
-    fn: async () => {
-      if (branch) {
-        return await api.organizations.databases.branches.get({
-          path: { organization, database, name: branch },
-        });
-      }
-      return await api.organizations.databases.get({
+    description: `database "${database}" ready`,
+    fn: () =>
+      api.organizations.databases.get({
         path: { organization, name: database },
-      });
-    },
-    predicate: (item) => item.ready,
+      }),
+    predicate: (database) => database.ready,
   });
 }
 
@@ -79,34 +115,74 @@ export async function ensureProductionBranchClusterSize(
   organization: string,
   database: string,
   branch: string,
+  kind: "mysql" | "postgresql",
   expectedClusterSize: PlanetScaleClusterSize,
-  isDBReady: boolean,
 ): Promise<void> {
-  if (!isDBReady) {
-    await waitForDatabaseReady(api, organization, database);
+  switch (kind) {
+    case "mysql": {
+      // Vitess databases must be promoted before resizing
+      await ensureProductionBranch(api, organization, database, branch);
+      await ensureMySQLClusterSize(
+        api,
+        organization,
+        database,
+        branch,
+        expectedClusterSize,
+      );
+      break;
+    }
+    case "postgresql": {
+      // Postgres databases must be resized first before promoting, otherwise 500 error
+      await ensurePostgresClusterSize(
+        api,
+        organization,
+        database,
+        branch,
+        expectedClusterSize,
+      );
+      await ensureProductionBranch(api, organization, database, branch);
+      break;
+    }
   }
+}
 
-  // 1. Ensure branch is production
-  const branchData = await api.organizations.databases.branches.get({
+/**
+ * Checks if a branch is production and promotes it if it is not.
+ */
+async function ensureProductionBranch(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  name: string,
+): Promise<void> {
+  const data = await api.organizations.databases.branches.get({
     path: {
       organization,
       database,
-      name: branch,
+      name,
     },
   });
-  if (!branchData.production) {
-    if (!branchData.ready) {
-      await waitForDatabaseReady(api, organization, database, branch);
+  if (!data.production) {
+    if (!data.ready) {
+      await waitForBranchReady(api, organization, database, name);
     }
     await api.organizations.databases.branches.promote.post({
-      path: {
-        organization,
-        database,
-        name: branch,
-      },
+      path: { organization, database, name },
     });
   }
-  // 2. Load default keyspace
+}
+
+/**
+ * Ensures that a MySQL branch has the correct cluster size.
+ */
+async function ensureMySQLClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  expectedClusterSize: PlanetScaleClusterSize,
+): Promise<void> {
+  // 1. Load default keyspace
   const keyspaces = await api.organizations.databases.branches.keyspaces.list({
     path: {
       organization,
@@ -119,7 +195,7 @@ export async function ensureProductionBranchClusterSize(
     throw new Error(`No default keyspace found for branch ${branch}`);
   }
 
-  // 3. Wait until any in-flight resize is done
+  // 2. Wait until any in-flight resize is done
   await waitForKeyspaceReady(
     api,
     organization,
@@ -128,7 +204,7 @@ export async function ensureProductionBranchClusterSize(
     defaultKeyspace.name,
   );
 
-  // 4. If size mismatch, trigger resize and wait again
+  // 3. If size mismatch, trigger resize and wait again
   // Ideally this would use the undocumented Keyspaces API, but there seems to be a missing oauth scope that we cannot add via the console yet
   if (defaultKeyspace.cluster_name !== expectedClusterSize) {
     await api.organizations.databases.branches.cluster.patch({
@@ -151,6 +227,72 @@ export async function ensureProductionBranchClusterSize(
   }
 }
 
+/**
+ * Ensures that a Postgres branch has the correct cluster size.
+ */
+async function ensurePostgresClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  expectedClusterSize: PlanetScaleClusterSize,
+): Promise<void> {
+  const data = await api.organizations.databases.branches.get({
+    path: {
+      organization,
+      database,
+      name: branch,
+    },
+  });
+  if (data.cluster_name === expectedClusterSize) {
+    return;
+  }
+  await waitForPendingPostgresChanges(api, organization, database, branch);
+  const change = await api.organizations.databases.branches.changes.patch({
+    path: {
+      organization,
+      database,
+      branch,
+    },
+    body: {
+      cluster_size: expectedClusterSize,
+    },
+  });
+  await waitForPendingPostgresChanges(
+    api,
+    organization,
+    database,
+    branch,
+    change.id,
+  );
+}
+
+/**
+ * Polls for a pending Postgres change to be completed.
+ */
+async function waitForPendingPostgresChanges(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  changeId?: string,
+) {
+  await poll({
+    description: `changes for branch "${branch}"`,
+    fn: () =>
+      api.organizations.databases.branches.changes.list({
+        path: { organization, database, branch },
+      }),
+    predicate: (response) =>
+      response.data.every(
+        (change) =>
+          change.state === "completed" ||
+          change.state === "canceled" ||
+          (changeId && change.id === changeId),
+      ),
+  });
+}
+
 /**
  * Polls a function until it returns a result that satisfies the predicate.
  */

package/src/secret.ts

@@ -17,8 +17,6 @@ function nextName() {
   return `alchemy:anonymous-secret-${i++}`;
 }
 
-const SecretSymbol = Symbol.for("alchemy::Secret");
-
 /**
  * Internal wrapper for sensitive values like API keys and credentials.
  * When stored in alchemy state files, the value is automatically encrypted
@@ -55,8 +53,6 @@ const SecretSymbol = Symbol.for("alchemy::Secret");
  * }
  */
 export class Secret<T = string> {
-  [SecretSymbol] = true;
-
   /**
    * @internal
    */

package/src/state/cloudflare-state-store.ts

@@ -47,13 +47,13 @@ export class CloudflareStateStore extends StateStoreProxy {
   options: CloudflareStateStoreOptions & { stateToken: Secret<string> };
   constructor(scope: Scope, options: CloudflareStateStoreOptions = {}) {
     super(scope);
-    const stateToken =
-      options.stateToken ?? alchemy.secret(process.env.ALCHEMY_STATE_TOKEN);
-    if (!stateToken) {
+    if (!options.stateToken && !process.env.ALCHEMY_STATE_TOKEN) {
       throw new Error(
-        "Missing token for DOStateStore. Please set ALCHEMY_STATE_TOKEN in the environment or set the `stateToken` option in the DOStateStore constructor.",
+        "Missing token for CloudflareStateStore. Please set ALCHEMY_STATE_TOKEN in the environment or set the `stateToken` option in the CloudflareStateStore constructor. See https://alchemy.run/guides/cloudflare-state-store/",
       );
     }
+    const stateToken =
+      options.stateToken ?? alchemy.secret(process.env.ALCHEMY_STATE_TOKEN);
     this.options = {
       ...options,
       stateToken: stateToken,

package/src/test/bun.ts

@@ -53,9 +53,9 @@ type test = {
    */
   skipIf(condition: boolean): test;
 
-  beforeAll(fn: (scope: Scope) => Promise<void>): void;
+  beforeAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
-  afterAll(fn: (scope: Scope) => Promise<void>): void;
+  afterAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
   /**
    * Current test scope

package/src/test/vitest.ts

@@ -57,9 +57,9 @@ type test = {
    */
   skipIf(condition: boolean): test;
 
-  beforeAll(fn: (scope: Scope) => Promise<void>): void;
+  beforeAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
-  afterAll(fn: (scope: Scope) => Promise<void>): void;
+  afterAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
   /**
    * Current test scope
@@ -134,12 +134,12 @@ export function test(
     password: process.env.ALCHEMY_PASSWORD,
   });
 
-  test.beforeAll = (fn: (scope: Scope) => Promise<void>) => {
-    return beforeAll(() => scope.run(() => fn(scope)));
+  test.beforeAll = (fn: (scope: Scope) => Promise<void>, timeout?: number) => {
+    return beforeAll(() => scope.run(() => fn(scope)), timeout);
   };
 
-  test.afterAll = (fn: (scope: Scope) => Promise<void>) => {
-    return afterAll(() => scope.run(() => fn(scope)));
+  test.afterAll = (fn: (scope: Scope) => Promise<void>, timeout?: number) => {
+    return afterAll(() => scope.run(() => fn(scope)), timeout);
   };
 
   return test as test;

package/src/util/content-type.ts

@@ -11,10 +11,10 @@ const mimeTypes: Record<string, string> = {
   ".jpeg": "image/jpeg",
   ".jpg": "image/jpeg",
   ".js.map": "application/source-map",
-  ".js": "application/javascript",
+  ".js": "text/javascript",
   ".json": "application/json",
   ".md": "text/markdown",
-  ".mjs": "application/javascript+module",
+  ".mjs": "text/javascript",
   ".mp3": "audio/mpeg",
   ".mp4": "video/mp4",
   ".otf": "font/otf",