import {
diffMigrations,
migrationsAttrs,
migrationsInputOf,
stampedOf,
type MigrationsInput,
} from "@alchemy.run/sql/Migrations";
import { hashImports } from "@alchemy.run/sql/SqlFile";
import {
deleteProject,
getConnectionURI,
getProject,
getProjectOperation,
listProjectBranchDatabases,
listProjectBranches,
listProjects,
type ListProjectsResponse,
type Project as NeonProject,
createProject as sdkCreateProject,
updateProject,
} from "@distilled.cloud/neon";
import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { recordsEqual } from "alchemy/Util/equal";
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 { runImports, runPgMigrations } from "./Migrations.ts";
import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
import type { Providers } from "./Providers.ts";
const DEFAULT_REGION: NeonRegion = "aws-us-east-1";
const DEFAULT_PG_VERSION: NeonPgVersion = 17;
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;
export type ProjectProps = {
/**
* Mutable project name. If omitted at creation, a unique name is generated
* from `${app}-${stage}-${id}`. Omitting it later preserves the deployed name.
*/
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` on creation; omission preserves the observed role on adoption
* and updates. An explicit change replaces the project.
*/
roleName?: string;
/**
* Name of the default database created with the project. Defaults to
* `neondb` on creation; omission preserves the observed database on adoption
* and updates. An explicit change replaces the project.
*/
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;
/**
* Enable Postgres logical replication on the project. Once enabled,
* Neon does not support disabling it again.
*
* @default false
* @see https://neon.tech/docs/guides/logical-replication-neon
*/
enableLogicalReplication?: boolean;
/**
* SQL migrations to apply against the default branch's primary database.
* Accepts a directory path, a `Drizzle.Schema` resource, or
* `{ dir, table? }`.
*
* Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A
* database previously migrated by drizzle-kit or Prisma is adopted by a
* 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.
*/
migrations?: MigrationsInput;
/**
* 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,
{
/** Neon project identifier. */
projectId: string;
/** Observed project name. */
projectName: string;
/** Immutable Postgres region. */
region: NeonRegion;
/** Immutable Postgres major version. */
pgVersion: NeonPgVersion;
/** Current default branch identifier. */
defaultBranchId: string;
/** Current default branch name. */
defaultBranchName: string;
/** Database selected for connection outputs and migrations. */
databaseName: string;
/** Observed owner of the selected database. */
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;
/**
* Parsed pooled connection components. Useful as a Hyperdrive `dev`
* origin when local workers bypass Hyperdrive and connect directly.
*/
pooledOrigin: PostgresOrigin;
/** Observed history retention window in seconds. */
historyRetentionSeconds: number;
/** Whether logical replication is enabled. Once enabled it cannot be disabled. */
enableLogicalReplication: boolean;
/** Directory of the applied SQL migrations. */
migrationsDir: string | undefined;
/** Migration bookkeeping table. */
migrationsTable: string | undefined;
/** Applied migration content hashes. */
migrationsHashes: Record<string, string>;
/** Applied SQL import content hashes. */
importHashes: Record<string, string>;
},
never,
Providers
>;
type ProjectAttributes = Project["Attributes"];
/**
* 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`.
* ### 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,
* });
* ```
*
* **Example:** Project with logical replication enabled
* ```typescript
* const project = yield* Neon.Project("my-project", {
* enableLogicalReplication: true,
* });
* ```
*
* ### Migrations and seed data
* **Example:** Apply migrations and seed files
* ```typescript
* const project = yield* Neon.Project("my-project", {
* migrations: "./migrations",
* importFiles: ["./seed/users.sql"],
* });
* ```
*
* ### 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/
*
* @resource
* @product Project
*/
export const Project = Resource<Project>("Neon.Project");
export const ProjectProvider = () =>
Provider.succeed(Project, {
stables: ["projectId", "defaultBranchId"],
list: Effect.fn(function* () {
// Account-scoped collection: enumerate every project via the Neon
// projects list API, then hydrate each into the exact `read`
// Attributes shape with bounded concurrency.
const projects = yield* listAllProjects;
const rows = yield* Effect.forEach(
projects,
(project) =>
hydrateProjectAttributes(project).pipe(
// A project can be deleted between the list call and
// hydration — skip it rather than fail the whole enumeration.
Effect.catchTag("NotFound", () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is ProjectAttributes => row !== undefined);
}),
diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
if (!isResolved(news)) return undefined;
const oldName = output?.projectName ?? (yield* createProjectName(id, olds.name));
// Preserve generated names; only an explicit name requests a rename.
const name = news.name ?? oldName;
if (
(news.region ?? output?.region ?? DEFAULT_REGION) !==
(output?.region ?? olds.region ?? DEFAULT_REGION) ||
(news.pgVersion ?? output?.pgVersion ?? DEFAULT_PG_VERSION) !==
(output?.pgVersion ?? olds.pgVersion ?? DEFAULT_PG_VERSION) ||
(news.defaultBranchName ?? output?.defaultBranchName) !== output?.defaultBranchName ||
(news.databaseName ?? output?.databaseName ?? "neondb") !==
(output?.databaseName ?? olds.databaseName ?? "neondb") ||
(news.roleName ?? output?.roleName ?? "neondb_owner") !==
(output?.roleName ?? olds.roleName ?? "neondb_owner") ||
news.orgId !== olds.orgId
) {
return {
action: "replace",
deleteFirst: news.name === oldName && news.orgId === olds.orgId,
} as const;
}
if (
oldName !== name ||
(news.historyRetentionSeconds ?? 86400) !== (output?.historyRetentionSeconds ?? 86400)
) {
return { action: "update" } as const;
}
if (
news.enableLogicalReplication !== undefined &&
news.enableLogicalReplication !== (output?.enableLogicalReplication ?? false)
) {
return { action: "update" } as const;
}
if (yield* diffMigrations({ news, output })) {
return { action: "update" } as const;
}
if (news.importFiles?.length) {
const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
return { action: "update" } as const;
}
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds, previous }) {
if (output?.projectId) {
return yield* getProject({ project_id: output.projectId }).pipe(
Effect.flatMap(({ project }) => hydrateProjectAttributes(project, output)),
Effect.catchTag("NotFound", () => Effect.undefined),
);
}
const name = yield* createProjectName(id, olds?.name);
const matches = yield* findProjectByName(name, olds?.orgId);
if (matches.length > 1) {
return yield* new ProjectStateError({
reason: "Ambiguous project name",
});
}
const match = matches[0];
if (!match) return undefined;
const attrs = yield* hydrateProjectAttributes(match, {
defaultBranchName: olds?.defaultBranchName,
migrationsDir: (olds && migrationsInputOf(olds))?.dir,
migrationsTable: (olds && migrationsInputOf(olds))?.table,
});
// The generation a delete-first replacement is about to free is ours.
if (attrs && attrs.projectId === previous?.projectId) return attrs;
return attrs && Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news = {}, output }) {
const name = news.name ?? output?.projectName ?? (yield* createProjectName(id, undefined));
// Names are not ownership evidence; approval applies only to the observed ID.
const authorize = (
project: ObservedProject,
): Effect.Effect<ObservedProject, OwnedBySomeoneElse> =>
project.id === output?.projectId
? Effect.succeed(project)
: Effect.fail(
new OwnedBySomeoneElse({
message: `Neon project "${name}" requires explicit adoption`,
resourceType: "Neon.Project",
logicalId: id,
physicalName: project.id,
}),
);
let observed: ObservedProject | undefined = output?.projectId
? yield* getProject({ project_id: output.projectId }).pipe(
Effect.map(({ project }) => project),
Effect.catchTag("NotFound", () => Effect.undefined),
)
: undefined;
if (!observed) {
const matches = yield* findProjectByName(name, news.orgId);
if (matches.length > 1) {
return yield* new ProjectStateError({
reason: "Ambiguous project name",
});
}
observed = matches[0] ? yield* authorize(matches[0]) : undefined;
}
if (!observed) {
const created = yield* sdkCreateProject({
project: {
name,
region_id: news.region ?? DEFAULT_REGION,
pg_version: news.pgVersion ?? DEFAULT_PG_VERSION,
branch: {
name: news.defaultBranchName,
role_name: news.roleName,
database_name: news.databaseName,
},
history_retention_seconds: news.historyRetentionSeconds,
org_id: news.orgId,
settings: news.enableLogicalReplication
? { enable_logical_replication: true }
: undefined,
},
}).pipe(
Effect.catchTag("Conflict", (error) =>
findProjectByName(name, news.orgId).pipe(
Effect.flatMap(
Effect.fn(function* (matches) {
if (matches.length !== 1) return yield* error;
const project = yield* authorize(matches[0]!);
return { project, operations: [] };
}),
),
),
),
);
yield* waitForOperations(created.operations);
observed = created.project;
}
const replication = observed.settings?.enable_logical_replication === true;
if (replication && news.enableLogicalReplication === false) {
return yield* new ProjectStateError({
reason: "Neon logical replication cannot be disabled once enabled",
});
}
const retention = news.historyRetentionSeconds ?? 86400;
if (
observed.name !== name ||
observed.history_retention_seconds !== retention ||
(news.enableLogicalReplication === true && !replication)
) {
const updated = yield* updateProject({
project_id: observed.id,
project: {
name: observed.name !== name ? name : undefined,
history_retention_seconds:
observed.history_retention_seconds !== retention ? retention : undefined,
settings:
news.enableLogicalReplication === true && !replication
? { enable_logical_replication: true }
: undefined,
},
});
yield* waitForOperations(updated.operations);
}
const current = yield* getProject({ project_id: observed.id });
const projectInfo = yield* hydrateProjectAttributes(current.project, {
defaultBranchName: news.defaultBranchName,
databaseName:
news.databaseName ??
(output?.projectId === observed.id ? output.databaseName : undefined),
});
if (!projectInfo) {
return yield* new ProjectStateError({
reason: "Project has no default branch or database",
});
}
const previous = projectInfo.projectId === output?.projectId ? output : undefined;
const connectionUri = Redacted.make(projectInfo.connectionUri);
const migrationsInput = migrationsInputOf(news);
const migrations = migrationsInput
? yield* runPgMigrations({
connectionUri,
input: migrationsInput,
stamped: stampedOf(previous),
})
: undefined;
const importHashes = news.importFiles?.length
? yield* runImports(
connectionUri,
news.importFiles,
yield* rootDir,
previous?.importHashes ?? {},
)
: {};
return {
...projectInfo,
...migrationsAttrs({
input: migrationsInput,
run: migrations,
output: previous,
}),
importHashes,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* deleteProject({ project_id: output.projectId }).pipe(
Effect.catchTag("NotFound", () => Effect.void),
);
yield* getProject({ project_id: output.projectId }).pipe(
Effect.flatMap(() => Effect.fail(new DeletionPending({ resourceId: output.projectId }))),
Effect.catchTag("NotFound", () => Effect.void),
Effect.retry({
while: (error) => error._tag === "NeonDeletionPending",
schedule: Schedule.spaced("2 seconds"),
times: 8,
}),
Effect.timeout("20 seconds"),
);
}),
});
const rootDir = Effect.sync(() => process.cwd());
const createProjectName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id }));
});
const resolveConnection = (
projectId: string,
branchId: string,
databaseName: string,
roleName: string,
) =>
Effect.gen(function* () {
const direct = yield* getConnectionURI({
project_id: projectId,
branch_id: branchId,
database_name: databaseName,
role_name: roleName,
pooled: false,
});
const pooled = yield* getConnectionURI({
project_id: projectId,
branch_id: branchId,
database_name: databaseName,
role_name: roleName,
pooled: true,
});
return { uri: direct.uri, pooled: pooled.uri };
});
export class ProjectStateError extends Data.TaggedError("NeonProjectStateError")<{
reason: string;
}> {}
export class DeletionPending extends Data.TaggedError("NeonDeletionPending")<{
resourceId: string;
}> {}
export class OperationFailed extends Data.TaggedError("NeonOperationFailed")<{
operationId: string;
action: string;
status: string;
}> {
override get message() {
return `Neon operation ${this.operationId} (${this.action}) ended ${this.status}`;
}
}
export class OperationPending extends Data.TaggedError("NeonOperationPending")<{
operationId: string;
status: string;
}> {}
type PendingOperation = {
readonly id: string;
readonly project_id: string;
readonly action: string;
readonly status: string;
};
const checkOperation = (
op: PendingOperation,
): Effect.Effect<void, OperationFailed | OperationPending> => {
if (op.status === "finished" || op.status === "skipped") return Effect.void;
if (op.status === "failed" || op.status === "error" || op.status === "cancelled") {
return Effect.fail(
new OperationFailed({
operationId: op.id,
action: op.action,
status: op.status,
}),
);
}
return Effect.fail(new OperationPending({ operationId: op.id, status: op.status }));
};
/** Wait at most 55 seconds; pending, cancelled and failed operations never succeed. */
export const waitForOperations = (operations: ReadonlyArray<PendingOperation>) =>
Effect.forEach(
operations,
(op) =>
checkOperation(op).pipe(
Effect.catchTag("NeonOperationPending", () =>
getProjectOperation({
project_id: op.project_id,
operation_id: op.id,
}).pipe(
Effect.flatMap(({ operation }) => checkOperation(operation)),
Effect.retry({
while: (error) => error._tag === "NeonOperationPending",
schedule: Schedule.spaced("5 seconds"),
times: 8,
}),
),
),
),
{ concurrency: 10, discard: true },
).pipe(Effect.timeout("55 seconds"));
const findProjectByName = (name: string, orgId?: string) =>
Effect.gen(function* () {
const matches: ListProjectsResponse["projects"][number][] = [];
let cursor: string | undefined;
while (true) {
const page = yield* listProjects({
search: name,
...(orgId !== undefined ? { org_id: orgId } : {}),
...(cursor !== undefined ? { cursor } : {}),
});
for (const p of page.projects) {
if (p.name === name) matches.push(p);
}
const nextCursor = page.pagination?.cursor;
// Neon returns a `pagination.cursor` on every response — it's the
// `created_at` of the last row, not a "has next page" flag — so we
// can't loop on cursor presence alone or we spin forever re-fetching
// empty/identical pages. Stop once a page comes back empty or the
// cursor stops advancing.
if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) {
break;
}
cursor = nextCursor;
}
return matches;
});
/**
* Exhaustively enumerate every project in the account. Uses the same
* cursor-stop heuristic as {@link findProjectByName} because Neon returns a
* `pagination.cursor` on every page (it's the last row's `created_at`, not a
* "has next page" flag), so we'd otherwise loop forever re-fetching.
*/
const listAllProjects = Effect.gen(function* () {
const projects: ListProjectsResponse["projects"][number][] = [];
let cursor: string | undefined;
while (true) {
const page = yield* listProjects(cursor !== undefined ? { cursor } : {});
projects.push(...page.projects);
const nextCursor = page.pagination?.cursor;
if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) {
break;
}
cursor = nextCursor;
}
return projects;
});
type ObservedProject = NeonProject | ListProjectsResponse["projects"][number];
/**
* Hydrate a project summary (from the list API) into the exact `read`
* Attributes shape — resolving the default branch, its primary database, and
* the direct + pooled connection URIs. Returns `undefined` when the project
* has no branch or database yet (mirrors `read`).
*/
const hydrateProjectAttributes = (
project: ObservedProject,
opts: {
defaultBranchName?: string;
databaseName?: string;
migrationsDir?: string;
migrationsTable?: string;
migrationsHashes?: Record<string, string>;
importHashes?: Record<string, string>;
} = {},
) =>
Effect.gen(function* () {
const branches: import("@distilled.cloud/neon").Branch[] = [];
let cursor: string | undefined;
do {
const page = yield* listProjectBranches({
project_id: project.id,
cursor,
});
branches.push(...page.branches);
const next = page.pagination?.next;
if (!next || next === cursor || page.branches.length === 0) break;
cursor = next;
} while (cursor);
const defaultBranch = branches.find((b) => b.default);
if (!defaultBranch) return undefined;
const databases = yield* listProjectBranchDatabases({
project_id: project.id,
branch_id: defaultBranch.id,
});
const db = opts.databaseName
? databases.databases.find((db) => db.name === opts.databaseName)
: databases.databases[0];
if (!db) return undefined;
const conn = yield* resolveConnection(project.id, defaultBranch.id, db.name, db.owner_name);
return {
projectId: project.id,
projectName: project.name,
region: project.region_id as NeonRegion,
pgVersion: project.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),
pooledOrigin: parsePostgresOrigin(conn.pooled),
historyRetentionSeconds: project.history_retention_seconds ?? 86400,
enableLogicalReplication: project.settings?.enable_logical_replication === true,
migrationsDir: opts.migrationsDir,
migrationsTable: opts.migrationsTable,
migrationsHashes: opts.migrationsHashes ?? {},
importHashes: opts.importHashes ?? {},
} satisfies ProjectAttributes;
});