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

package/src/Planetscale/Postgres/PostgresDefaultRole.ts

@@ -0,0 +1,270 @@
+import { Credentials } from "@distilled.cloud/planetscale/Credentials";
+import * as ops from "@distilled.cloud/planetscale/Operations";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+import { PlanetscaleConflict, waitForBranchReady } from "../Util.ts";
+import type { PostgresBranch } from "./PostgresBranch.ts";
+import type { PostgresDatabase } from "./PostgresDatabase.ts";
+import type { InheritedRole } from "./PostgresRole.ts";
+
+/**
+ * Properties for creating or updating the default PlanetScale PostgreSQL
+ * role for a branch.
+ *
+ * Default roles are only meant for PostgreSQL databases. For MySQL,
+ * use {@link MySQLPassword} instead.
+ */
+export interface PostgresDefaultRoleProps {
+  /**
+   * PostgreSQL database — string name or {@link PostgresDatabase} resource.
+   */
+  database: string | PostgresDatabase;
+
+  /**
+   * Branch — string name or {@link PostgresBranch} resource.
+   * @default "main"
+   */
+  branch?: string | PostgresBranch;
+
+  /**
+   * Whether to force-reset the default role if it already exists.
+   * Adopting an existing default role is not supported because the
+   * password is only returned at create time.
+   * @default false
+   */
+  forceReset?: boolean;
+}
+
+/**
+ * Output attributes of a deployed PlanetScale default role.
+ */
+export interface PostgresDefaultRoleAttributes {
+  /** Unique identifier for the role (stable). */
+  id: string;
+  /** The Postgres role name. */
+  name: string;
+  /** ISO 8601 timestamp at which the role expires. */
+  expiresAt: string | null;
+  /** Hostname for the database connection. */
+  host: string;
+  /** Username for database authentication. */
+  username: string;
+  /** Password for database authentication (Redacted). */
+  password: Redacted.Redacted<string>;
+  /** TTL in seconds (if set). */
+  ttl: number | null;
+  /** The database name. */
+  databaseName: string;
+  /** Direct connection URL for the database (Redacted). */
+  connectionUrl: Redacted.Redacted<string>;
+  /** Pooled connection URL via PSBouncer (Redacted). */
+  connectionUrlPooled: Redacted.Redacted<string>;
+  /** Inherited roles. */
+  inheritedRoles: InheritedRole[];
+  /** Resolved organization slug. */
+  organization: string;
+  /** Resolved database name (for delete). */
+  database: string;
+  /** Resolved branch name. */
+  branch: string;
+}
+
+/**
+ * The default PlanetScale PostgreSQL role for a database branch.
+ *
+ * @section Creating a Default Role
+ * @example Default role on the main branch
+ * ```typescript
+ * const db = yield* Planetscale.PostgresDatabase("MyDb", {
+ *   clusterSize: "PS_10",
+ * });
+ * const defaultRole = yield* Planetscale.PostgresDefaultRole("MainRole", {
+ *   database: db,
+ *   forceReset: true,
+ * });
+ * ```
+ */
+export type PostgresDefaultRole = Resource<
+  "Planetscale.PostgresDefaultRole",
+  PostgresDefaultRoleProps,
+  PostgresDefaultRoleAttributes,
+  never,
+  Providers
+>;
+
+export const PostgresDefaultRole = Resource<PostgresDefaultRole>(
+  "Planetscale.PostgresDefaultRole",
+);
+
+// Structural shapes for runtime-resolved Resource references — see
+// notes in Password.ts.
+type DatabaseRef = string | { name: string; organization?: string };
+type BranchRef = string | { name: string };
+
+const resolveDatabaseName = (database: string | PostgresDatabase): string => {
+  const ref = database as unknown as DatabaseRef;
+  return typeof ref === "string" ? ref : ref.name;
+};
+
+const resolveDatabaseOrg = (
+  database: string | PostgresDatabase,
+): string | undefined => {
+  const ref = database as unknown as DatabaseRef;
+  return typeof ref === "string" ? undefined : ref.organization;
+};
+
+const resolveBranchName = (
+  branch: string | PostgresBranch | undefined,
+): string => {
+  const ref = branch as unknown as BranchRef | undefined;
+  return !ref ? "main" : typeof ref === "string" ? ref : ref.name;
+};
+
+export const PostgresDefaultRoleProvider = () =>
+  Provider.effect(
+    PostgresDefaultRole,
+    Effect.gen(function* () {
+      const getDefault = yield* ops.getDefaultRole;
+      const resetDefault = yield* ops.resetDefaultRole;
+
+      return {
+        stables: ["id"],
+
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+
+          const newDb = resolveDatabaseName(news.database);
+          const oldDb = olds.database
+            ? resolveDatabaseName(olds.database)
+            : undefined;
+          if (oldDb && newDb !== oldDb) {
+            return { action: "replace" } as const;
+          }
+          const newBranch = resolveBranchName(news.branch);
+          const oldBranch = resolveBranchName(olds.branch);
+          if (newBranch !== oldBranch) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+
+        read: Effect.fn(function* ({ output }) {
+          // Adoption (no cached output) is impossible without destroying
+          // existing credentials. The engine routes adoption through
+          // `read`, but here we always defer to reconcile so the
+          // `forceReset` props flag remains the user-facing switch for
+          // takeover. Returning undefined makes the engine treat the
+          // resource as greenfield; reconcile then observes live state
+          // and either fails (no forceReset) or resets (forceReset).
+          if (!output) return undefined;
+
+          // Refresh — verify the default role still exists and re-emit
+          // the persisted output (with plaintext intact). If gone,
+          // return undefined so the engine routes through reconcile,
+          // which will recreate via reset.
+          return yield* getDefault({
+            organization: output.organization,
+            database: output.database,
+            branch: output.branch,
+          }).pipe(
+            Effect.map(() => output),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const { organization: envOrg } = yield* Credentials;
+          const organization = resolveDatabaseOrg(news.database) ?? envOrg;
+          const databaseName = resolveDatabaseName(news.database);
+          const branchName = resolveBranchName(news.branch);
+
+          // 1. Observe — the default role is the singleton for this
+          //    (database, branch); we key on those rather than an id.
+          //    Observation runs unconditionally so the adoption guard
+          //    below fires on greenfield deploys against branches that
+          //    already have a default role (otherwise we would silently
+          //    `resetDefault` and destroy their credentials).
+          const observed = yield* getDefault({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+
+          // 2. Sync (no-op) — we own the role and it still exists in the
+          //    cloud. Default roles have nothing mutable in place: their
+          //    plaintext password isn't retrievable, so we re-emit the
+          //    persisted attributes unchanged. diff() forces a replace
+          //    when database/branch change.
+          if (output && observed) {
+            return output;
+          }
+
+          // 3. Adoption guard — observed exists but we have no prior
+          //    output (greenfield against a pre-existing default role).
+          //    Taking over requires a reset (which destroys the existing
+          //    password), so gate on an explicit forceReset opt-in.
+          if (observed && !news.forceReset) {
+            return yield* Effect.fail(
+              new PlanetscaleConflict({
+                message: `Default role already exists for database "${databaseName}" branch "${branchName}". Use forceReset: true to reset.`,
+              }),
+            );
+          }
+
+          // 4. Ensure — (re)create the default role. This branch runs
+          //    for greenfield (no output, no observed), drift recovery
+          //    (output cached but cloud state gone), and authorised
+          //    adoption (observed present + forceReset).
+          yield* waitForBranchReady(organization, databaseName, branchName);
+          const data = yield* resetDefault({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+
+          if (!data.password) {
+            return yield* Effect.die(
+              `Planetscale did not return a password for Default Role.`,
+            );
+          }
+
+          const password = Redacted.isRedacted(data.password)
+            ? Redacted.value(data.password)
+            : data.password;
+
+          const connectionUrl = `postgresql://${data.username}:${password}@${data.access_host_url}:5432/${data.database_name}?sslmode=verify-full`;
+          const connectionUrlPooled = `postgresql://${data.username}:${password}@${data.access_host_url}:6432/${data.database_name}?sslmode=verify-full`;
+
+          return {
+            id: data.id,
+            name: data.name,
+            expiresAt: data.expires_at,
+            host: data.access_host_url,
+            username: data.username,
+            password: Redacted.make(password),
+            ttl: data.ttl,
+            databaseName: data.database_name,
+            connectionUrl: Redacted.make(connectionUrl),
+            connectionUrlPooled: Redacted.make(connectionUrlPooled),
+            inheritedRoles: data.inherited_roles as InheritedRole[],
+            organization,
+            database: databaseName,
+            branch: branchName,
+          } satisfies PostgresDefaultRoleAttributes;
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // No delete endpoint — reset to invalidate existing credentials.
+          yield* resetDefault({
+            organization: output.organization,
+            database: output.database,
+            branch: output.branch,
+          }).pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/Planetscale/Postgres/PostgresMigrations.ts

@@ -0,0 +1,256 @@
+import * as ops from "@distilled.cloud/planetscale/Operations";
+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 { Client } from "pg";
+import { listSqlFiles, readSqlFile, type SqlFile } from "../../Sql/SqlFile.ts";
+
+const MIGRATION_ROLE_TTL_SECONDS = 600;
+
+export class PostgresMigrationError extends Data.TaggedError(
+  "Planetscale::PostgresMigrationError",
+)<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+export interface PostgresMigrationTarget {
+  organization: string;
+  database: string;
+  branch: string;
+}
+
+export const runPostgresMigrations = (
+  target: PostgresMigrationTarget,
+  migrationsDir: string,
+  migrationsTable: string,
+) =>
+  Effect.gen(function* () {
+    const files = yield* listSqlFiles(migrationsDir);
+    if (files.length > 0) {
+      yield* applyPostgresMigrations({
+        target,
+        migrationsTable,
+        migrationsFiles: files,
+      });
+    }
+    const hashes: Record<string, string> = {};
+    for (const file of files) hashes[file.id] = file.hash;
+    return hashes;
+  });
+
+export const runPostgresImports = (
+  target: PostgresMigrationTarget,
+  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* runPostgresSql(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;
+  });
+
+interface ApplyMigrationsOptions {
+  target: PostgresMigrationTarget;
+  migrationsTable: string;
+  migrationsFiles: ReadonlyArray<SqlFile>;
+}
+
+const applyPostgresMigrations = (options: ApplyMigrationsOptions) =>
+  withPostgresClient(options.target, (client) =>
+    Effect.gen(function* () {
+      const table = quotePgIdentifier(options.migrationsTable);
+      yield* pgExec(
+        client,
+        `CREATE TABLE IF NOT EXISTS ${table} (
+           id TEXT PRIMARY KEY,
+           name TEXT NOT NULL,
+           applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+         );`,
+      );
+
+      const applied = yield* pgRows<{ name: string }>(
+        client,
+        `SELECT name FROM ${table};`,
+      ).pipe(Effect.map((rows) => new Set(rows.map((row) => row.name))));
+      let nextSeq = yield* getNextPgSeq(client, table);
+
+      for (const file of options.migrationsFiles) {
+        if (applied.has(file.id)) continue;
+        const migrationId = nextSeq.toString().padStart(5, "0");
+        nextSeq += 1;
+        yield* Effect.gen(function* () {
+          yield* pgExec(client, "BEGIN");
+          yield* pgExec(client, file.sql);
+          yield* pgExec(
+            client,
+            `INSERT INTO ${table} (id, name) VALUES ($1, $2);`,
+            [migrationId, file.id],
+          );
+          yield* pgExec(client, "COMMIT");
+        }).pipe(
+          Effect.catch((error) =>
+            pgExec(client, "ROLLBACK").pipe(
+              Effect.catch(() => Effect.void),
+              Effect.andThen(Effect.fail(error)),
+            ),
+          ),
+        );
+      }
+    }),
+  );
+
+const runPostgresSql = (target: PostgresMigrationTarget, sql: string) =>
+  withPostgresClient(target, (client) => pgExec(client, sql));
+
+const getNextPgSeq = (client: Client, table: string) =>
+  pgRows<{ id: string }>(client, `SELECT id FROM ${table};`).pipe(
+    Effect.map((rows) => {
+      let max = 0;
+      for (const { id } of rows) {
+        if (/^\d+$/.test(id)) {
+          max = Math.max(max, Number.parseInt(id, 10));
+        }
+      }
+      return max + 1;
+    }),
+  );
+
+const withPostgresClient = <A, E, R>(
+  target: PostgresMigrationTarget,
+  use: (client: Client) => Effect.Effect<A, E, R>,
+) =>
+  withTemporaryPostgresRole(target, (role) =>
+    Effect.acquireUseRelease(
+      Effect.gen(function* () {
+        const client = yield* Effect.sync(
+          () =>
+            new Client({
+              connectionString: stripPgSslQueryParams(
+                Redacted.value(role.connectionUrl),
+              ),
+              ssl: { rejectUnauthorized: true },
+            }),
+        );
+        yield* Effect.tryPromise({
+          try: () => client.connect(),
+          catch: toMigrationError,
+        });
+        return client;
+      }),
+      use,
+      (client) =>
+        Effect.tryPromise({
+          try: () => client.end(),
+          catch: toMigrationError,
+        }).pipe(Effect.catch(() => Effect.void)),
+    ),
+  );
+
+const withTemporaryPostgresRole = <A, E, R>(
+  target: PostgresMigrationTarget,
+  use: (role: {
+    id: string;
+    connectionUrl: Redacted.Redacted<string>;
+  }) => Effect.Effect<A, E, R>,
+) =>
+  Effect.acquireUseRelease(
+    Effect.gen(function* () {
+      const created = yield* ops.createRole({
+        organization: target.organization,
+        database: target.database,
+        branch: target.branch,
+        ttl: MIGRATION_ROLE_TTL_SECONDS,
+        inherited_roles: ["postgres"],
+      });
+
+      const password = created.password!;
+      const value = Redacted.value(password);
+      const connectionUrl = yield* Effect.sync(
+        () =>
+          `postgresql://${encodeURIComponent(created.username)}:${encodeURIComponent(value)}@${created.access_host_url}:5432/${created.database_name}?sslmode=verify-full`,
+      );
+      return {
+        id: created.id,
+        connectionUrl: Redacted.make(connectionUrl),
+      };
+    }),
+    use,
+    (role) =>
+      ops
+        .deleteRole({
+          organization: target.organization,
+          database: target.database,
+          branch: target.branch,
+          id: role.id,
+          successor: "postgres",
+        })
+        .pipe(
+          // Already-deleted roles are a success: nothing to clean up.
+          Effect.catchTag("NotFound", () => Effect.void),
+          Effect.retry({
+            schedule: Schedule.exponential("500 millis").pipe(
+              Schedule.both(Schedule.recurs(5)),
+            ),
+          }),
+          // Migrations succeeded; don't fail the parent over a release-step
+          // hiccup. The role's TTL bounds the orphan window; log loudly so
+          // an operator can clean it up manually if needed.
+          Effect.catch((cause: unknown) =>
+            Effect.logWarning(
+              `Failed to delete temporary Planetscale migration role after retries. ` +
+                `It will expire via TTL (~${MIGRATION_ROLE_TTL_SECONDS}s). ` +
+                `organization=${target.organization} database=${target.database} ` +
+                `branch=${target.branch} id=${role.id}`,
+              cause,
+            ),
+          ),
+        ),
+  );
+
+const pgExec = (client: Client, sql: string, values?: ReadonlyArray<unknown>) =>
+  Effect.tryPromise({
+    try: () =>
+      client.query(sql, values as Array<unknown>).then(() => undefined),
+    catch: toMigrationError,
+  });
+
+const pgRows = <A>(client: Client, sql: string) =>
+  Effect.tryPromise({
+    try: () => client.query(sql).then((result) => result.rows as A[]),
+    catch: toMigrationError,
+  });
+
+const toMigrationError = (cause: unknown) =>
+  new PostgresMigrationError({
+    message: cause instanceof Error ? cause.message : String(cause),
+    cause,
+  });
+
+const quotePgIdentifier = (identifier: string) =>
+  `"${identifier.replaceAll('"', '""')}"`;
+
+const stripPgSslQueryParams = (uri: string): string => {
+  try {
+    const url = new URL(uri);
+    url.searchParams.delete("sslmode");
+    url.searchParams.delete("channel_binding");
+    return url.toString();
+  } catch {
+    return uri;
+  }
+};

package/src/Planetscale/Postgres/PostgresOrigin.ts

@@ -0,0 +1,15 @@
+import * as Redacted from "effect/Redacted";
+
+/**
+ * The shape `Cloudflare.Hyperdrive` and other Postgres consumers accept as an
+ * origin. Materialized on `Planetscale.PostgresRole` so callers can wire role
+ * credentials into Hyperdrive directly.
+ */
+export type PostgresOrigin = {
+  scheme: "postgres" | "postgresql";
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: Redacted.Redacted<string>;
+};