alchemy 2.0.0-beta.30 → 2.0.0-beta.32

package/src/Neon/Migrations.ts

@@ -0,0 +1,128 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { Client } from "pg";
+import type { SqlFile } from "./SqlFile.ts";
+
+export class PgError extends Data.TaggedError("PgError")<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+export interface ApplyMigrationsOptions {
+  connectionUri: Redacted.Redacted<string>;
+  migrationsTable: string;
+  migrationsFiles: ReadonlyArray<SqlFile>;
+}
+
+/**
+ * Strip query-string SSL flags from a Neon connection URI. Neon's URIs
+ * include `sslmode=require` and `channel_binding=require`, which trigger
+ * a deprecation warning from `pg-connection-string`:
+ *
+ *   SECURITY WARNING: The SSL modes 'prefer', 'require', and 'verify-ca'
+ *   are treated as aliases for 'verify-full'.
+ *
+ * We control SSL programmatically via the `ssl` option below, so removing
+ * the conflicting query params silences the warning without changing the
+ * effective behavior.
+ */
+const stripSslQueryParams = (uri: string): string => {
+  try {
+    const url = new URL(uri);
+    url.searchParams.delete("sslmode");
+    url.searchParams.delete("channel_binding");
+    return url.toString();
+  } catch {
+    return uri;
+  }
+};
+
+const withClient = <A, E>(
+  connectionUri: Redacted.Redacted<string>,
+  fn: (client: Client) => Promise<A>,
+): Effect.Effect<A, PgError | E> =>
+  Effect.tryPromise({
+    try: async () => {
+      const client = new Client({
+        connectionString: stripSslQueryParams(Redacted.value(connectionUri)),
+        ssl: { rejectUnauthorized: false },
+      });
+      await client.connect();
+      try {
+        return await fn(client);
+      } finally {
+        await client.end().catch(() => {});
+      }
+    },
+    catch: (cause) =>
+      new PgError({
+        message: cause instanceof Error ? cause.message : String(cause),
+        cause,
+      }),
+  });
+
+const ensureMigrationsTable = (client: Client, migrationsTable: string) =>
+  client.query(
+    `CREATE TABLE IF NOT EXISTS "${migrationsTable}" (
+       id TEXT PRIMARY KEY,
+       name TEXT NOT NULL,
+       applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+     );`,
+  );
+
+const getApplied = (client: Client, migrationsTable: string) =>
+  client
+    .query<{ name: string }>(`SELECT name FROM "${migrationsTable}";`)
+    .then((r) => new Set(r.rows.map((row) => row.name)));
+
+const getNextSeq = (client: Client, migrationsTable: string) =>
+  client
+    .query<{ id: string }>(`SELECT id FROM "${migrationsTable}";`)
+    .then((r) => {
+      let max = 0;
+      for (const { id } of r.rows) {
+        if (/^\d+$/.test(id)) {
+          max = Math.max(max, Number.parseInt(id, 10));
+        }
+      }
+      return max + 1;
+    });
+
+/**
+ * Apply pending Postgres migrations in order, tracked in `migrationsTable`.
+ * Each migration runs inside a transaction together with the bookkeeping
+ * INSERT so partial application is impossible.
+ */
+export const applyMigrations = (options: ApplyMigrationsOptions) =>
+  withClient(options.connectionUri, async (client) => {
+    await ensureMigrationsTable(client, options.migrationsTable);
+    const applied = await getApplied(client, options.migrationsTable);
+    let nextSeq = await getNextSeq(client, options.migrationsTable);
+
+    for (const file of options.migrationsFiles) {
+      if (applied.has(file.id)) continue;
+      const migrationId = nextSeq.toString().padStart(5, "0");
+      nextSeq += 1;
+      await client.query("BEGIN");
+      try {
+        await client.query(file.sql);
+        await client.query(
+          `INSERT INTO "${options.migrationsTable}" (id, name) VALUES ($1, $2);`,
+          [migrationId, file.id],
+        );
+        await client.query("COMMIT");
+      } catch (err) {
+        await client.query("ROLLBACK").catch(() => {});
+        throw err;
+      }
+    }
+  });
+
+/**
+ * Run a single SQL script against the database (used for `importFiles`).
+ */
+export const runSql = (connectionUri: Redacted.Redacted<string>, sql: string) =>
+  withClient(connectionUri, async (client) => {
+    await client.query(sql);
+  });

package/src/Neon/NeonEnvironment.ts

@@ -0,0 +1,31 @@
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { getAuthProvider } from "../Auth/AuthProvider.ts";
+import { ALCHEMY_PROFILE, loadOrConfigure } from "../Auth/Profile.ts";
+import {
+  NEON_AUTH_PROVIDER_NAME,
+  type NeonAuthConfig,
+  type NeonResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export class NeonEnvironment extends Context.Service<
+  NeonEnvironment,
+  NeonResolvedCredentials
+>()("Neon::NeonEnvironment") {}
+
+export const fromProfile = () =>
+  Layer.effect(
+    NeonEnvironment,
+    Effect.gen(function* () {
+      const auth = yield* getAuthProvider<
+        NeonAuthConfig,
+        NeonResolvedCredentials
+      >(NEON_AUTH_PROVIDER_NAME);
+      const profileName = yield* ALCHEMY_PROFILE;
+      const ci = yield* Config.boolean("CI").pipe(Config.withDefault(false));
+      const config = yield* loadOrConfigure(auth, profileName, { ci });
+      return yield* auth.read(profileName, config as NeonAuthConfig);
+    }),
+  );

package/src/Neon/PostgresOrigin.ts

@@ -0,0 +1,41 @@
+import * as Redacted from "effect/Redacted";
+
+/**
+ * The shape `Cloudflare.Hyperdrive` and other Postgres consumers accept
+ * as `origin`. Materialized on `Neon.Project` and `Neon.Branch` so callers
+ * can wire databases into Hyperdrive directly:
+ *
+ * ```typescript
+ * const branch = yield* Neon.Branch("preview", { project });
+ * const hd = yield* Cloudflare.Hyperdrive("preview-hd", {
+ *   origin: branch.origin,
+ * });
+ * ```
+ */
+export type PostgresOrigin = {
+  scheme: "postgres" | "postgresql" | "mysql";
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: Redacted.Redacted<string>;
+};
+
+/**
+ * Parse a Postgres connection URI into the structured origin shape.
+ * Used to derive `branch.origin` / `project.origin` from the API
+ * response's `connectionUri`.
+ */
+export const parsePostgresOrigin = (uri: string): PostgresOrigin => {
+  const url = new URL(uri);
+  const scheme: PostgresOrigin["scheme"] =
+    url.protocol === "postgresql:" ? "postgresql" : "postgres";
+  return {
+    scheme,
+    host: url.hostname,
+    port: url.port ? Number(url.port) : 5432,
+    database: url.pathname.replace(/^\//, ""),
+    user: decodeURIComponent(url.username),
+    password: Redacted.make(decodeURIComponent(url.password)),
+  };
+};

package/src/Neon/Project.ts

@@ -0,0 +1,498 @@
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { isResolved } from "../Diff.ts";
+import { createPhysicalName } from "../PhysicalName.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import * as api from "./api.ts";
+import { applyMigrations, runSql } from "./Migrations.ts";
+import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
+import type { Providers } from "./Providers.ts";
+import { listSqlFiles, readSqlFile } from "./SqlFile.ts";
+
+export type NeonRegion =
+  | "aws-us-east-1"
+  | "aws-us-east-2"
+  | "aws-us-west-2"
+  | "aws-eu-central-1"
+  | "aws-eu-west-2"
+  | "aws-ap-southeast-1"
+  | "aws-ap-southeast-2"
+  | "aws-sa-east-1"
+  | "azure-eastus2"
+  | "azure-westus3"
+  | "azure-gwc";
+
+export type NeonPgVersion = 14 | 15 | 16 | 17 | 18;
+
+const DEFAULT_MIGRATIONS_TABLE = "neon_migrations";
+const DEFAULT_REGION: NeonRegion = "aws-us-east-1";
+const DEFAULT_PG_VERSION: NeonPgVersion = 17;
+
+export type ProjectProps = {
+  /**
+   * Name of the project. If omitted, a unique name is generated from
+   * `${app}-${stage}-${id}`.
+   */
+  name?: string;
+  /**
+   * Region where the project is provisioned. Cannot be changed after
+   * creation.
+   *
+   * @default "aws-us-east-1"
+   */
+  region?: NeonRegion;
+  /**
+   * Postgres version. Cannot be changed after creation.
+   *
+   * @default 17
+   */
+  pgVersion?: NeonPgVersion;
+  /**
+   * Name of the default branch. Defaults to Neon's default ("main"). Cannot
+   * be changed after creation.
+   */
+  defaultBranchName?: string;
+  /**
+   * Name of the default role created with the project. Defaults to
+   * `neondb_owner`. Cannot be changed after creation.
+   */
+  roleName?: string;
+  /**
+   * Name of the default database created with the project. Defaults to
+   * `neondb`. Cannot be changed after creation.
+   */
+  databaseName?: string;
+  /**
+   * Number of seconds of WAL history retained on the project for
+   * point-in-time branching/restore.
+   *
+   * @default 86400
+   */
+  historyRetentionSeconds?: number;
+  /**
+   * Optional Neon organization ID. Cannot be changed after creation.
+   */
+  orgId?: string;
+  /**
+   * Directory containing `.sql` migration files. Files are sorted by their
+   * numeric prefix (e.g. `0001_init.sql`) and applied in order against the
+   * default branch's primary database.
+   */
+  migrationsDir?: string;
+  /**
+   * Name of the table used to track applied migrations.
+   *
+   * @default "neon_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
+   * subsequent deploys.
+   */
+  importFiles?: string[];
+};
+
+export type Project = Resource<
+  "Neon.Project",
+  ProjectProps,
+  {
+    projectId: string;
+    projectName: string;
+    region: NeonRegion;
+    pgVersion: NeonPgVersion;
+    defaultBranchId: string;
+    defaultBranchName: string;
+    databaseName: string;
+    roleName: string;
+    /** Postgres connection URI for the default branch + database. */
+    connectionUri: string;
+    /** Pooled connection URI (uses pgbouncer). */
+    pooledConnectionUri: string;
+    /**
+     * Parsed connection components ready to feed into a Postgres origin
+     * — e.g. `Cloudflare.Hyperdrive`'s `origin` prop. Points at the
+     * direct (non-pooled) endpoint, which is the recommended target
+     * when fronting Neon with another pooler like Hyperdrive.
+     */
+    origin: PostgresOrigin;
+    historyRetentionSeconds: number;
+    migrationsDir: string | undefined;
+    migrationsTable: string | undefined;
+    migrationsHashes: Record<string, string>;
+    importHashes: Record<string, string>;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * A Neon serverless Postgres project.
+ *
+ * Creating a project also provisions the project's default branch (named
+ * "main" by default), an initial role, an initial database, and a
+ * read-write compute endpoint, exposed as `connectionUri`.
+ *
+ * @section Creating a Project
+ * @example Basic project
+ * ```typescript
+ * const project = yield* Neon.Project("my-project");
+ * ```
+ *
+ * @example Project with explicit region and PG version
+ * ```typescript
+ * const project = yield* Neon.Project("my-project", {
+ *   region: "aws-eu-central-1",
+ *   pgVersion: 17,
+ * });
+ * ```
+ *
+ * @section Migrations and seed data
+ * @example Apply migrations and seed files
+ * ```typescript
+ * const project = yield* Neon.Project("my-project", {
+ *   migrationsDir: "./migrations",
+ *   importFiles: ["./seed/users.sql"],
+ * });
+ * ```
+ *
+ * @section Branching
+ * @example Create a branch off the project's default branch
+ * ```typescript
+ * const project = yield* Neon.Project("my-project");
+ * const dev = yield* Neon.Branch("dev-branch", { project });
+ * ```
+ *
+ * @see https://neon.tech/docs/manage/projects/
+ */
+export const Project = Resource<Project>("Neon.Project");
+
+const getRoleName = (creation: api.CreateProjectOutput) =>
+  creation.roles.find((r) => !r.protected)?.name ?? creation.roles[0]?.name;
+
+const getDatabaseName = (creation: api.CreateProjectOutput) =>
+  creation.databases[0]?.name ?? "neondb";
+
+const buildConnectionUri = (
+  uri: string,
+  pooledHost: string,
+): { uri: string; pooled: string } => {
+  const url = new URL(uri);
+  const pooledUrl = new URL(uri);
+  pooledUrl.host = pooledHost;
+  return { uri: url.toString(), pooled: pooledUrl.toString() };
+};
+
+const resolveConnection = (
+  projectId: string,
+  branchId: string,
+  databaseName: string,
+  roleName: string,
+) =>
+  Effect.gen(function* () {
+    const direct = yield* api.getConnectionUri(projectId, {
+      branch_id: branchId,
+      database_name: databaseName,
+      role_name: roleName,
+      pooled: false,
+    });
+    const pooled = yield* api.getConnectionUri(projectId, {
+      branch_id: branchId,
+      database_name: databaseName,
+      role_name: roleName,
+      pooled: true,
+    });
+    return { uri: direct.uri, pooled: pooled.uri };
+  });
+
+export const ProjectProvider = () =>
+  Provider.effect(
+    Project,
+    Effect.gen(function* () {
+      const rootDir = process.cwd();
+
+      const createProjectName = (id: string, name: string | undefined) =>
+        Effect.gen(function* () {
+          return name ?? (yield* createPhysicalName({ id }));
+        });
+
+      return {
+        stables: ["projectId", "defaultBranchId"],
+        diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
+          if (!isResolved(news)) return undefined;
+          const name = yield* createProjectName(id, news.name);
+          const oldName = output?.projectName
+            ? output.projectName
+            : yield* createProjectName(id, olds.name);
+          if (
+            oldName !== name ||
+            (news.region ?? DEFAULT_REGION) !==
+              (output?.region ?? olds.region ?? DEFAULT_REGION) ||
+            (news.pgVersion ?? DEFAULT_PG_VERSION) !==
+              (output?.pgVersion ?? olds.pgVersion ?? DEFAULT_PG_VERSION) ||
+            (news.defaultBranchName ?? output?.defaultBranchName) !==
+              output?.defaultBranchName
+          ) {
+            return { action: "replace" } as const;
+          }
+          if (
+            (news.historyRetentionSeconds ?? 86400) !==
+            (output?.historyRetentionSeconds ?? 86400)
+          ) {
+            return { action: "update" } as const;
+          }
+          if (news.migrationsDir) {
+            const newHashes = yield* hashMigrations(news.migrationsDir);
+            if (!recordsEqual(newHashes, output?.migrationsHashes ?? {})) {
+              return { action: "update" } as const;
+            }
+            if (
+              (news.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE) !==
+              (output?.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE)
+            ) {
+              return { action: "update" } as const;
+            }
+          }
+          if (news.importFiles?.length) {
+            const newHashes = yield* hashImports(news.importFiles, rootDir);
+            if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
+              return { action: "update" } as const;
+            }
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          if (output?.projectId) {
+            return yield* api.getProject(output.projectId).pipe(
+              Effect.map(({ project }) => ({
+                ...output,
+                projectName: project.name,
+                historyRetentionSeconds: project.history_retention_seconds,
+              })),
+              Effect.catchTag("ProjectNotFound", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          }
+          const name = yield* createProjectName(id, olds?.name);
+          const matches = yield* api.findProjectByName(name);
+          const match = matches[0];
+          if (!match) return undefined;
+          const branches = yield* api.listProjectBranches(match.id, {
+            search: olds?.defaultBranchName ?? "main",
+          });
+          const defaultBranch =
+            branches.branches.find((b) => b.default) ?? branches.branches[0];
+          if (!defaultBranch) return undefined;
+          const databases = yield* api.listProjectBranchDatabases(
+            match.id,
+            defaultBranch.id,
+          );
+          const db = databases.databases[0];
+          if (!db) return undefined;
+          const conn = yield* resolveConnection(
+            match.id,
+            defaultBranch.id,
+            db.name,
+            db.owner_name,
+          );
+          return {
+            projectId: match.id,
+            projectName: match.name,
+            region: match.region_id as NeonRegion,
+            pgVersion: match.pg_version as NeonPgVersion,
+            defaultBranchId: defaultBranch.id,
+            defaultBranchName: defaultBranch.name,
+            databaseName: db.name,
+            roleName: db.owner_name,
+            connectionUri: conn.uri,
+            pooledConnectionUri: conn.pooled,
+            origin: parsePostgresOrigin(conn.uri),
+            historyRetentionSeconds: match.history_retention_seconds,
+            migrationsDir: olds?.migrationsDir,
+            migrationsTable: olds?.migrationsTable,
+            migrationsHashes: {},
+            importHashes: {},
+          };
+        }),
+        reconcile: Effect.fn(function* ({ id, news = {}, output }) {
+          // Ensure — when no prior output exists we create the project
+          // (and let `read` upstream decide adoption); otherwise update
+          // the mutable scalar fields on the existing project.
+          const projectInfo = output
+            ? yield* api
+                .updateProject(output.projectId, {
+                  name: news.name,
+                  history_retention_seconds: news.historyRetentionSeconds,
+                })
+                .pipe(
+                  Effect.map((r) => ({
+                    projectId: output.projectId,
+                    projectName: r.project.name,
+                    region: output.region,
+                    pgVersion: output.pgVersion,
+                    defaultBranchId: output.defaultBranchId,
+                    defaultBranchName: output.defaultBranchName,
+                    databaseName: output.databaseName,
+                    roleName: output.roleName,
+                    connectionUri: output.connectionUri,
+                    pooledConnectionUri: output.pooledConnectionUri,
+                    origin: output.origin,
+                    historyRetentionSeconds:
+                      r.project.history_retention_seconds ??
+                      output.historyRetentionSeconds,
+                  })),
+                )
+            : yield* Effect.gen(function* () {
+                const name = yield* createProjectName(id, news.name);
+                const created = yield* api.createProject({
+                  name,
+                  region_id: news.region,
+                  pg_version: news.pgVersion,
+                  default_branch: {
+                    name: news.defaultBranchName,
+                    role_name: news.roleName,
+                    database_name: news.databaseName,
+                  },
+                  history_retention_seconds: news.historyRetentionSeconds,
+                  org_id: news.orgId,
+                });
+                yield* api.waitForOperations(created.operations);
+
+                const branchId = created.branch.id;
+                const databaseName = getDatabaseName(created);
+                const roleName = getRoleName(created) ?? "neondb_owner";
+                const conn = yield* resolveConnection(
+                  created.project.id,
+                  branchId,
+                  databaseName,
+                  roleName,
+                );
+                return {
+                  projectId: created.project.id,
+                  projectName: created.project.name,
+                  region: created.project.region_id as NeonRegion,
+                  pgVersion: created.project.pg_version as NeonPgVersion,
+                  defaultBranchId: branchId,
+                  defaultBranchName: created.branch.name,
+                  databaseName,
+                  roleName,
+                  connectionUri: conn.uri,
+                  pooledConnectionUri: conn.pooled,
+                  origin: parsePostgresOrigin(conn.uri),
+                  historyRetentionSeconds:
+                    created.project.history_retention_seconds ?? 86400,
+                };
+              });
+
+          const connectionUri = Redacted.make(projectInfo.connectionUri);
+          const migrationsTable =
+            news.migrationsTable ??
+            output?.migrationsTable ??
+            DEFAULT_MIGRATIONS_TABLE;
+          const migrationsHashes = news.migrationsDir
+            ? yield* runMigrations(
+                connectionUri,
+                news.migrationsDir,
+                migrationsTable,
+              )
+            : (output?.migrationsHashes ?? {});
+          const importHashes = news.importFiles?.length
+            ? yield* runImports(
+                connectionUri,
+                news.importFiles,
+                rootDir,
+                output?.importHashes ?? {},
+              )
+            : {};
+
+          return {
+            ...projectInfo,
+            migrationsDir: news.migrationsDir,
+            migrationsTable: news.migrationsDir ? migrationsTable : undefined,
+            migrationsHashes,
+            importHashes,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* api.deleteProject(output.projectId);
+        }),
+      };
+    }),
+  );
+
+const runMigrations = (
+  connectionUri: Redacted.Redacted<string>,
+  migrationsDir: string,
+  migrationsTable: string,
+) =>
+  Effect.gen(function* () {
+    const files = yield* listSqlFiles(migrationsDir);
+    if (files.length > 0) {
+      yield* applyMigrations({
+        connectionUri,
+        migrationsTable,
+        migrationsFiles: files,
+      });
+    }
+    const hashes: Record<string, string> = {};
+    for (const file of files) hashes[file.id] = file.hash;
+    return hashes;
+  });
+
+const runImports = (
+  connectionUri: Redacted.Redacted<string>,
+  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* runSql(connectionUri, 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;
+  });
+
+const hashMigrations = (migrationsDir: string) =>
+  listSqlFiles(migrationsDir).pipe(
+    Effect.map((files) => {
+      const hashes: Record<string, string> = {};
+      for (const file of files) hashes[file.id] = file.hash;
+      return hashes;
+    }),
+  );
+
+const hashImports = (importFiles: ReadonlyArray<string>, rootDir: string) =>
+  Effect.gen(function* () {
+    const hashes: Record<string, string> = {};
+    for (const filePath of importFiles) {
+      const file = yield* readSqlFile(rootDir, filePath);
+      hashes[filePath] = file.hash;
+    }
+    return hashes;
+  });
+
+const recordsEqual = (
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean => {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+};