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

package/src/MySQL/MySQLDatabase.ts

@@ -180,12 +180,109 @@ export type MySQLDatabase = Resource<
   MySQLDatabaseProps,
   MySQLDatabaseAttributes,
   never,
-  Providers
+  Providers,
+  MySQLDatabaseLookup
 >;
 
-/** @resource */
+/**
+ * Props for {@link MySQLDatabase.lookup}: find a MySQL database this
+ * stack doesn't manage by its name, in the credentialed organization.
+ */
+export interface MySQLDatabaseLookup {
+  /** Database name. */
+  name: string;
+}
+
+/**
+ * A PlanetScale MySQL (Vitess) database.
+ *
+ * ### Looking up an existing MySQL database
+ * `MySQLDatabase.lookup` references a MySQL database Alchemy doesn't manage (created in
+ * the PlanetScale dashboard or by another stack). It is read during
+ * plan/deploy, never created, updated or deleted.
+ *
+ * **Example:** Branch an existing database
+ * ```typescript
+ * const db = Planetscale.MySQLDatabase.lookup({ name: "app" });
+ * const preview = yield* Planetscale.MySQLBranch("Preview", {
+ *   database: db,
+ *   isProduction: false,
+ * });
+ * ```
+ *
+ * @resource
+ */
 export const MySQLDatabase = Resource<MySQLDatabase>("Planetscale.MySQLDatabase");
 
+/** Observe a database by name; `read` and `lookup` share it. */
+const readMySQLDatabase = Effect.fn(function* ({
+  id,
+  output,
+  olds,
+}: {
+  id: string;
+  output?: MySQLDatabase["Attributes"];
+  olds?: Partial<MySQLDatabaseProps>;
+}) {
+  const { organization } = yield* yield* Credentials;
+  const databaseName = output?.name ?? (yield* createDatabaseName(id, olds?.name));
+  return yield* planetscale
+    .getDatabase({
+      organization,
+      database: databaseName,
+    })
+    .pipe(
+      Effect.flatMap(
+        Effect.fn(function* (data) {
+          if (data.kind !== "mysql") {
+            return yield* new PlanetscaleConflict({
+              message:
+                `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
+                `is a MySQLDatabase. Use Planetscale.${data.kind === "postgresql" ? "PostgresDatabase" : data.kind}() instead, ` +
+                `or delete the existing database and retry.`,
+            });
+          }
+          // Observe the default keyspace's live replica configuration
+          // so adopted databases diff against reality.
+          const replicas = yield* observeDefaultKeyspaceReplicas(
+            organization,
+            data.name,
+            data.default_branch ?? "main",
+          );
+          return {
+            id: data.id,
+            name: data.name,
+            organization,
+            state: data.state,
+            defaultBranch: data.default_branch ?? "main",
+            replicas,
+            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: output?.clusterSize ?? "",
+            requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
+            restrictBranchRegion: data.restrict_branch_region ?? false,
+            insightsRawQueries: data.insights_raw_queries ?? false,
+            productionBranchWebConsole: data.production_branch_web_console ?? false,
+            deletionProtection: data.deletion_protected ?? false,
+            automaticMigrations: data.automatic_migrations ?? false,
+            migrationFramework: data.migration_framework ?? undefined,
+            migrationTableName: data.migration_table_name ?? undefined,
+            allowDataBranching: data.allow_data_branching ?? false,
+            allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
+          };
+        }),
+      ),
+      Effect.catchTag("NotFound", () => Effect.undefined),
+    );
+});
+
 export const MySQLDatabaseProvider = () =>
   Provider.succeed(MySQLDatabase, {
     stables: ["id", "organization", "region"],
@@ -246,66 +343,9 @@ export const MySQLDatabaseProvider = () =>
       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));
-      return yield* planetscale
-        .getDatabase({
-          organization,
-          database: databaseName,
-        })
-        .pipe(
-          Effect.flatMap(
-            Effect.fn(function* (data) {
-              if (data.kind !== "mysql") {
-                return yield* new PlanetscaleConflict({
-                  message:
-                    `Planetscale database "${data.name}" has kind "${data.kind}" but this resource ` +
-                    `is a MySQLDatabase. Use Planetscale.${data.kind === "postgresql" ? "PostgresDatabase" : data.kind}() instead, ` +
-                    `or delete the existing database and retry.`,
-                });
-              }
-              // Observe the default keyspace's live replica configuration
-              // so adopted databases diff against reality.
-              const replicas = yield* observeDefaultKeyspaceReplicas(
-                organization,
-                data.name,
-                data.default_branch ?? "main",
-              );
-              return {
-                id: data.id,
-                name: data.name,
-                organization,
-                state: data.state,
-                defaultBranch: data.default_branch ?? "main",
-                replicas,
-                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: output?.clusterSize ?? "",
-                requireApprovalForDeploy: data.require_approval_for_deploy ?? false,
-                restrictBranchRegion: data.restrict_branch_region ?? false,
-                insightsRawQueries: data.insights_raw_queries ?? false,
-                productionBranchWebConsole: data.production_branch_web_console ?? false,
-                deletionProtection: data.deletion_protected ?? false,
-                automaticMigrations: data.automatic_migrations ?? false,
-                migrationFramework: data.migration_framework ?? undefined,
-                migrationTableName: data.migration_table_name ?? undefined,
-                allowDataBranching: data.allow_data_branching ?? false,
-                allowForeignKeyConstraints: data.foreign_keys_enabled ?? false,
-              };
-            }),
-          ),
-          Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
-        );
-    }),
+    lookup: ({ name }) => readMySQLDatabase({ id: name, olds: { name } }),
+
+    read: readMySQLDatabase,
 
     reconcile: Effect.fn(function* ({ id, news, output, session }) {
       const { organization } = yield* yield* Credentials;
@@ -327,7 +367,7 @@ export const MySQLDatabaseProvider = () =>
           organization,
           database: observedName,
         })
-        .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
       // Ensure — if missing, create.
       if (!observed) {

package/src/MySQL/MySQLMigrations.ts

@@ -1,34 +1,18 @@
 import {
-  makeMySQLMigrationExecutor,
   runMigrations,
+  withMySqlExecutor,
   type NormalizedMigrationsInput,
+  type SqlExecutor,
   type StampedMigrationsState,
 } from "@alchemy.run/sql/Migrations";
-import { readSqlFile, splitSqlStatements } from "@alchemy.run/sql/SqlFile";
+import { applySqlImports, splitSqlStatements } from "@alchemy.run/sql/SqlFile";
 import * as ps from "@distilled.cloud/planetscale";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import * as Schedule from "effect/Schedule";
-import type { Connection } from "mysql2/promise";
 
 const MIGRATION_PASSWORD_TTL_SECONDS = 600;
 
-// `mysql2` is an optional peer dependency — loaded lazily so importing the
-// Planetscale provider never requires the driver unless migrations run.
-const importMysql = () =>
-  import("mysql2/promise").catch((cause) => {
-    throw new Error(
-      "Failed to load the 'mysql2' driver. Install the optional peer dependency 'mysql2' to run Planetscale MySQL migrations.",
-      { cause },
-    );
-  });
-
-export class MySQLMigrationError extends Data.TaggedError("Planetscale::MySQLMigrationError")<{
-  message: string;
-  cause?: unknown;
-}> {}
-
 export interface MySQLMigrationTarget {
   organization: string;
   database: string;
@@ -47,69 +31,48 @@ export const runMySQLMigrations = (
   runMigrations({
     input,
     stamped,
-    withExecutor: (apply) =>
-      withMySQLConnection(target, (connection) => apply(makeMySQLMigrationExecutor(connection))),
+    withExecutor: (apply) => withMySQLExecutor(target, apply),
   });
 
+/**
+ * Apply `importFiles`, each once and again only when it changes. Vitess
+ * rejects drizzle-kit's `--> statement-breakpoint` markers, so statements
+ * run one at a time.
+ */
 export const runMySQLImports = (
   target: MySQLMigrationTarget,
   importFiles: ReadonlyArray<string>,
   rootDir: string,
   previous: Record<string, string>,
 ) =>
-  Effect.gen(function* () {
-    const hashes: Record<string, string> = { ...previous };
-    for (const filePath of importFiles) {
-      const file = yield* readSqlFile(rootDir, filePath);
-      if (previous[filePath] === file.hash) {
-        hashes[filePath] = file.hash;
-        continue;
-      }
-      yield* runMySQLSql(target, file.sql);
-      hashes[filePath] = file.hash;
-    }
-    const tracked = new Set(importFiles);
-    for (const key of Object.keys(hashes)) {
-      if (!tracked.has(key)) delete hashes[key];
-    }
-    return hashes;
+  applySqlImports({
+    importFiles,
+    rootDir,
+    previous,
+    apply: (file) =>
+      withMySQLExecutor(target, (executor) =>
+        Effect.forEach(splitSqlStatements(file.sql), (statement) => executor.query(statement), {
+          discard: true,
+        }),
+      ),
   });
 
-const runMySQLSql = (target: MySQLMigrationTarget, sql: string) =>
-  withMySQLConnection(target, (connection) =>
-    Effect.gen(function* () {
-      for (const statement of splitSqlStatements(sql)) {
-        yield* mysqlQuery(connection, statement);
-      }
-    }),
-  );
-
-const withMySQLConnection = <A, E, R>(
+/** A verified-TLS `mysql2` session as a short-lived admin password. */
+const withMySQLExecutor = <A, E, R>(
   target: MySQLMigrationTarget,
-  use: (connection: Connection) => Effect.Effect<A, E, R>,
+  use: (executor: SqlExecutor) => Effect.Effect<A, E, R>,
 ) =>
   withTemporaryMySQLPassword(target, (password) =>
-    Effect.acquireUseRelease(
-      Effect.tryPromise({
-        try: async () => {
-          const { createConnection } = await importMysql();
-          return createConnection({
-            host: password.host,
-            user: password.username,
-            password: Redacted.value(password.password),
-            database: target.database,
-            multipleStatements: true,
-            ssl: { rejectUnauthorized: true },
-          });
-        },
-        catch: toMigrationError,
-      }),
+    withMySqlExecutor(
+      {
+        host: password.host,
+        user: password.username,
+        password: Redacted.value(password.password),
+        database: target.database,
+        multipleStatements: true,
+        ssl: { rejectUnauthorized: true },
+      },
       use,
-      (connection) =>
-        Effect.tryPromise({
-          try: () => connection.end(),
-          catch: toMigrationError,
-        }).pipe(Effect.ignore),
     ),
   );
 
@@ -168,15 +131,3 @@ const withTemporaryMySQLPassword = <A, E, R>(
           ),
         ),
   );
-
-const mysqlQuery = (connection: Connection, sql: string) =>
-  Effect.tryPromise({
-    try: () => connection.query(sql).then(() => undefined),
-    catch: toMigrationError,
-  });
-
-const toMigrationError = (cause: unknown) =>
-  new MySQLMigrationError({
-    message: cause instanceof Error ? cause.message : String(cause),
-    cause,
-  });

package/src/MySQL/MySQLPassword.ts

@@ -189,7 +189,7 @@ export const MySQLPasswordProvider = () =>
               branch: output.branch,
             }),
           ),
-          Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          Effect.catchTag("NotFound", () => Effect.undefined),
         );
     }),
 
@@ -217,7 +217,7 @@ export const MySQLPasswordProvider = () =>
               branch: branchName,
               id: output.id,
             })
-            .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)))
+            .pipe(Effect.catchTag("NotFound", () => Effect.undefined))
         : undefined;
 
       // 2. Ensure — create the password if it doesn't exist live.

package/src/Postgres/PostgresBranch.ts

@@ -79,10 +79,36 @@ export type PostgresBranch = Resource<
   PostgresBranchProps,
   PostgresBranchAttributes,
   never,
-  Providers
+  Providers,
+  PostgresBranchLookup
 >;
 
-/** @resource */
+/**
+ * Props for {@link PostgresBranch.lookup}: find a Postgres branch this
+ * stack doesn't manage by its database and name.
+ */
+export interface PostgresBranchLookup {
+  /** Database name. */
+  database: string;
+  /** Branch name. */
+  name: string;
+}
+
+/**
+ * A branch of a PlanetScale Postgres database.
+ *
+ * ### Looking up an existing Postgres branch
+ * `PostgresBranch.lookup` references a Postgres branch Alchemy doesn't manage (created in
+ * the PlanetScale dashboard or by another stack). It is read during
+ * plan/deploy, never created, updated or deleted.
+ *
+ * **Example:** Reference an existing branch
+ * ```typescript
+ * const main = Planetscale.PostgresBranch.lookup({ database: "app", name: "main" });
+ * ```
+ *
+ * @resource
+ */
 export const PostgresBranch = Resource<PostgresBranch>("Planetscale.PostgresBranch");
 
 export const PostgresBranchProvider = () =>

package/src/Postgres/PostgresDatabase.ts

@@ -124,12 +124,110 @@ export type PostgresDatabase = Resource<
   PostgresDatabaseProps,
   PostgresDatabaseAttributes,
   never,
-  Providers
+  Providers,
+  PostgresDatabaseLookup
 >;
 
-/** @resource */
+/**
+ * Props for {@link PostgresDatabase.lookup}: find a Postgres database this
+ * stack doesn't manage by its name, in the credentialed organization.
+ */
+export interface PostgresDatabaseLookup {
+  /** Database name. */
+  name: string;
+}
+
+/**
+ * A PlanetScale Postgres database.
+ *
+ * ### Looking up an existing Postgres database
+ * `PostgresDatabase.lookup` references a Postgres database Alchemy doesn't manage (created in
+ * the PlanetScale dashboard or by another stack). It is read during
+ * plan/deploy, never created, updated or deleted.
+ *
+ * **Example:** Branch an existing database
+ * ```typescript
+ * const db = Planetscale.PostgresDatabase.lookup({ name: "app" });
+ * const preview = yield* Planetscale.PostgresBranch("Preview", {
+ *   database: db,
+ *   isProduction: false,
+ * });
+ * ```
+ *
+ * @resource
+ */
 export const PostgresDatabase = Resource<PostgresDatabase>("Planetscale.PostgresDatabase");
 
+/** Observe a database by name; `read` and `lookup` share it. */
+const readPostgresDatabase = Effect.fn(function* ({
+  id,
+  output,
+  olds,
+}: {
+  id: string;
+  output?: PostgresDatabase["Attributes"];
+  olds?: Partial<PostgresDatabaseProps>;
+}) {
+  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,
+  };
+});
+
 export const PostgresDatabaseProvider = () =>
   Provider.succeed(PostgresDatabase, {
     stables: ["id", "organization", "region"],
@@ -191,66 +289,9 @@ export const PostgresDatabaseProvider = () =>
       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.succeed(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";
+    lookup: ({ name }) => readPostgresDatabase({ id: name, olds: { name } }),
 
-      // 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.succeed(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,
-      };
-    }),
+    read: readPostgresDatabase,
 
     reconcile: Effect.fn(function* ({ id, news, output, session }) {
       const { organization } = yield* yield* Credentials;
@@ -276,7 +317,7 @@ export const PostgresDatabaseProvider = () =>
           organization,
           database: observedName,
         })
-        .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
       // Ensure — if missing, create.
       if (!observed) {
@@ -425,7 +466,7 @@ export const PostgresDatabaseProvider = () =>
                 database: data.name,
                 branch: defaultBranch,
               })
-              .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+              .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
             const arch = toPostgresClusterArch(branch?.cluster_architecture);
             const clusterSize = branch?.cluster_name ?? "";

package/src/Postgres/PostgresDefaultRole.ts

@@ -153,7 +153,7 @@ export const PostgresDefaultRoleProvider = () =>
             privateHost: role.private_access_host_url,
             privateConnectionServiceName: role.private_connection_service_name,
           })),
-          Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          Effect.catchTag("NotFound", () => Effect.undefined),
         );
     }),
 
@@ -175,7 +175,7 @@ export const PostgresDefaultRoleProvider = () =>
           database: databaseName,
           branch: branchName,
         })
-        .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
       // 2. Sync (no-op) — we own the role and it still exists in the
       //    cloud. Default roles have nothing mutable in place: their