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

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAmD,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAmD,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/planetscale",
-  "version": "2.0.0-beta.85",
+  "version": "2.0.0-beta.86",
   "description": "PlanetScale MySQL and Postgres databases for Alchemy.",
   "keywords": [
     "alchemy",
@@ -58,22 +58,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@alchemy.run/sql": "2.0.0-beta.85",
-    "@distilled.cloud/core": "1.0.0-rc.18",
-    "@distilled.cloud/planetscale": "1.0.0-rc.18"
+    "@alchemy.run/sql": "2.0.0-beta.86",
+    "@distilled.cloud/core": "1.0.0-rc.19",
+    "@distilled.cloud/planetscale": "1.0.0-rc.19"
   },
   "devDependencies": {
     "@types/bun": "1.4.3",
     "@types/pg": "^8.20.0",
-    "alchemy": "2.0.0-beta.85",
-    "effect": "^4.1.0",
+    "alchemy": "2.0.0-beta.86",
+    "effect": "^4.1.4",
     "mysql2": "^3.24.2",
     "pg": "^8.22.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.1.0-dev.20261105.1"
   },
   "peerDependencies": {
-    "alchemy": "2.0.0-beta.85",
-    "effect": "^4.1.0",
+    "alchemy": "2.0.0-beta.86",
+    "effect": "^4.1.4",
     "mysql2": "^3.24.2",
     "pg": "^8.22.0"
   },

package/src/Branch.ts

@@ -73,7 +73,12 @@ export interface BaseBranchProps {
    * Adding a file is an in-place update. Editing or removing an
    * already-applied file replaces a non-production branch (re-forked from
    * its parent) and fails on a current or desired production branch — add
-   * a forward migration instead.
+   * a forward migration instead. Renaming an applied file without changing
+   * its contents keeps it applied and replaces nothing.
+   *
+   * History is linear: a new file must sort after every applied one, or
+   * the deploy fails with `NonLinearMigrationHistoryError`. See
+   * [Migrations](https://alchemy.run/sql/effect-sql/migrations#change-migration-history-safely).
    */
   migrations?: MigrationsInput;
 
@@ -361,6 +366,34 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
       return stables ? ({ action: "noop", stables } as const) : undefined;
     }),
 
+    lookup: Effect.fn(function* ({ database, name }: any) {
+      const { organization } = yield* yield* Credentials;
+      return yield* planetscale.getBranch({ organization, database, branch: name }).pipe(
+        Effect.map(
+          (data) =>
+            ({
+              name: data.name,
+              organization,
+              database,
+              parentBranch: data.parent_branch ?? "main",
+              production: data.production,
+              createdAt: data.created_at,
+              updatedAt: data.updated_at,
+              htmlUrl: data.html_url,
+              region: { slug: data.region.slug },
+              migrationsDir: undefined,
+              migrationsTable: undefined,
+              migrationsHashes: {},
+              importHashes: {},
+              desiredReplicas: undefined,
+              hasReplicas: data.has_replicas,
+              hasReadOnlyReplicas: data.has_read_only_replicas,
+            }) satisfies BaseBranchAttributes,
+        ),
+        Effect.catchTag("NotFound", () => Effect.undefined),
+      );
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }: any) {
       // If we have neither a cached output nor a usable `olds.database`
       // there's no way to identify which branch to refresh — most often

package/src/Database.ts

@@ -84,6 +84,13 @@ export interface BaseDatabaseProps {
    * 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.
+   *
+   * History is forward-only and linear. A new file must sort after every
+   * applied one, or the deploy fails with `NonLinearMigrationHistoryError`;
+   * an edited or deleted applied file fails with
+   * `RewrittenMigrationHistoryError`. Renaming an applied file without
+   * changing its contents keeps it applied. See
+   * [Migrations](https://alchemy.run/sql/effect-sql/migrations#change-migration-history-safely).
    */
   migrations?: MigrationsInput;
 

package/src/MySQL/MySQLBranch.ts

@@ -91,10 +91,36 @@ export type MySQLBranch = Resource<
   MySQLBranchProps,
   MySQLBranchAttributes,
   never,
-  Providers
+  Providers,
+  MySQLBranchLookup
 >;
 
-/** @resource */
+/**
+ * Props for {@link MySQLBranch.lookup}: find a MySQL branch this
+ * stack doesn't manage by its database and name.
+ */
+export interface MySQLBranchLookup {
+  /** Database name. */
+  database: string;
+  /** Branch name. */
+  name: string;
+}
+
+/**
+ * A branch of a PlanetScale MySQL database.
+ *
+ * ### Looking up an existing MySQL branch
+ * `MySQLBranch.lookup` references a MySQL 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.MySQLBranch.lookup({ database: "app", name: "main" });
+ * ```
+ *
+ * @resource
+ */
 export const MySQLBranch = Resource<MySQLBranch>("Planetscale.MySQLBranch");
 
 export const MySQLBranchProvider = () =>

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.undefined),
-        );
-    }),
+    lookup: ({ name }) => readMySQLDatabase({ id: name, olds: { name } }),
+
+    read: readMySQLDatabase,
 
     reconcile: Effect.fn(function* ({ id, news, output, session }) {
       const { organization } = yield* yield* Credentials;

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.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.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;

package/src/Providers.ts

@@ -15,6 +15,7 @@ import {
   PostgresDefaultRoleProvider,
 } from "./Postgres/PostgresDefaultRole.ts";
 import { PostgresRole, PostgresRoleProvider } from "./Postgres/PostgresRole.ts";
+import { ServiceToken, ServiceTokenProvider } from "./ServiceToken.ts";
 
 /**
  * Service tag bundling all PlanetScale providers + auth + credentials. Use
@@ -45,6 +46,7 @@ export const providers = () =>
       MySQLPassword,
       PostgresRole,
       PostgresDefaultRole,
+      ServiceToken,
     ]),
   ).pipe(
     Layer.provide(
@@ -56,6 +58,7 @@ export const providers = () =>
         MySQLPasswordProvider(),
         PostgresRoleProvider(),
         PostgresDefaultRoleProvider(),
+        ServiceTokenProvider(),
       ),
     ),
     Layer.provideMerge(Credentials.fromAuthProvider()),