Neon

API reference for Neon serverless PostgreSQL resources

Neon

Neon is a serverless PostgreSQL platform that provides instant branching, autoscaling, and a generous free tier.

Resources

NeonProject

Creates a Neon serverless PostgreSQL project.

Basic Project

import { NeonProject } from "alchemy/neon";

const project = await NeonProject("my-project", {
  name: "My Project"
});

Props

name · string · default: "${app}-${stage}-${id}"

Name of the project

region_id · NeonRegion · default: "aws-us-east-1"

Region where the project will be provisioned. Available regions:

• 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

pg_version · number · default: "16"

PostgreSQL version to use. Supported versions: 14, 15, 16, 17, 18

default_branch_name · string · default: "main"

Default branch name

adopt · boolean

When true, will adopt an existing project by name

delete · boolean · default: "true"

Whether to delete the database when the resource is destroyed. When false, the database will only be removed from the state but not deleted via API.

history_retention_seconds · number · default: "86400"

History retention seconds for the project

settings · ProjectSettingsData

Settings for the project

default_endpoint_settings · DefaultEndpointSettings

Default endpoint settings for the project

Returns

id · string

The ID of the project

name · string

Name of the Project

created_at · string

Time at which the project was created

updated_at · string

Time at which the project was last updated

proxy_host · string

Hostname for proxy access

region_id · NeonRegion

Region where the project is provisioned

pg_version · number

PostgreSQL version used by the project

connection_uris · NeonConnectionUri[]

Connection URIs for the databases

roles · NeonRole[]

Database roles created with the project

databases · Database[]

Databases created with the project

branch · Branch

Default branch information

endpoints · Endpoint[]

Compute endpoints for the project

NeonBranch

Creates a branch in a Neon project.

Basic Branch

import { NeonBranch } from "alchemy/neon";

const branch = await NeonBranch("feature-branch", {
  project: project,
  endpoints: [{ type: "read-write" }]
});

Props

project · string | NeonProject · required

The project to create the new branch in. This can be a Project object or an ID string.

name · string · default: "${app}-${stage}-${id}"

The name of the branch

protected · boolean · default: "false"

Whether the branch is protected

parentBranch · string | NeonBranch | Branch

The parent branch to create the new branch from. Default is the project’s default branch. This can be a Branch object or an ID string beginning with br-.

parentLsn · string

A Log Sequence Number (LSN) on the parent branch. The branch will be created with data from this LSN.

parentTimestamp · string

A timestamp identifying a point in time on the parent branch. The branch will be created with data starting from this point in time. The timestamp must be provided in ISO 8601 format; for example: 2024-02-26T12:00:00Z.

adopt · boolean

When true, will adopt an existing branch by name

expiresAt · string

The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set following the RFC 3339, section 5.6 format with precision up to seconds (such as 2025-06-09T18:02:16Z).

initSource · 'schema-only' | 'parent-data' · default: "parent-data"

The source of initialization for the branch:

• schema-only - creates a new root branch containing only the schema
• parent-data - creates the branch with both schema and data from the parent

endpoints · BranchCreateRequestEndpointOptions[] · required

The endpoints to create for the branch. If you do not configure endpoints, you will not be able to connect to the branch.

Returns

id · string

The branch ID. This value is generated when a branch is created. A branch_id value has a br- prefix.

projectId · string

The ID of the project to which the branch belongs

name · string

The name of the branch

protected · boolean

Whether the branch is protected

default · boolean

Whether the branch is the default branch

createdAt · Date

The timestamp when the branch was created

updatedAt · Date

The timestamp when the branch was last updated

endpoints · Endpoint[]

The endpoints for the branch

databases · Database[]

The databases for the branch

roles · NeonRole[]

The roles for the branch

connectionUris · NeonConnectionUri[]

The connection URIs for the branch