> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/integrations/integrations-overview/neon-integration.md).

# Neon integration

How to set up the Release Neon integration for instant databases

Release integrates with [Neon](https://neon.tech) to provision serverless PostgreSQL databases for your ephemeral environments. Neon's branching feature allows Release to automatically create isolated database branches, giving each environment its own database instance with near-instant provisioning.

## Prerequisites

Before setting up the Neon integration in Release, you'll need:

1. A Neon account (sign up at [console.neon.tech](https://console.neon.tech))
2. A Neon project with at least one database created
3. A Neon API key

## Step 1: Create a Neon Account and Project

1. Sign up or log in at [console.neon.tech](https://console.neon.tech).
2. Create a new project (or use an existing one). Each project comes with a default branch and a `neondb` database.

![Neon Console showing projects](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-78b78a173ce0fc5992d2da09cf57c5800db6ba4e%2Fneon-console-projects.png?alt=media)

## Step 2: Create an API Key in Neon

Release connects to Neon using an **API key**. You'll need to create one with the right scope.

1. In the Neon Console, navigate to **Account settings**.
2. In the sidebar, click **API keys** to open the **Personal API keys** section.

![Neon API keys page in Account settings](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-7e45cebb493646536a697742924435e387da164d%2Fneon-api-keys.png?alt=media)

3. Click **Create new API key**.
4. Enter a name for the key (e.g., `release-integration`).
5. **Important:** Copy the API key value immediately. It will not be shown again.

![API key created dialog — copy the key before closing](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e2360b5b57a097ea6e4cd6d1518716350914f4b8%2Fneon-api-key-created.png?alt=media)

{% hint style="warning" %}
The API key is only displayed once. Make sure to copy it before closing the dialog.
{% endhint %}

## Step 3: Install the Neon Integration in Release

1. In the Release UI, navigate to **Configuration** > **Integrations** (accessible at `/workspaces/<workspace-id>/configuration/integrations`).

![Release Integrations page showing Neon under Available](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-5b54a28f0974a976408ffe5cf2d793c98b2b1ef8%2Frelease-integrations-list-neon-available.png?alt=media)

2. Find **Neon** under the **Available** section and click on it.
3. Click **Install Neon**.

![Neon integration page with Install Neon button](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-199cb3e0aa48f99a52d884beed764eea15b9912c%2Frelease-neon-install-button.png?alt=media)

4. Enter your **API Key** from Step 2.

![Install Neon form with API Key field](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-c310b86024a6fbd27b5fd08e6ae72ba53ef58cb2%2Frelease-neon-install-form.png?alt=media)

5. Click **Install Integration**.
6. The integration is now installed and will appear under the **Installed** section on the Integrations page.

![Neon now showing as an installed integration](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-1507be8478dc12bb842984ec2fe46e8b91395476%2Frelease-integrations-list-neon-installed.png?alt=media)

## Step 4: Create a Neon Dataset

Once the integration is installed, you can create datasets that use Neon as the database provider.

1. Navigate to **Configuration** > **Datasets**.
2. Click **Create Dataset**. If the Neon integration is installed, you'll see a **Neon** tab alongside the **Cloud Provider** tab.
3. Select the **Neon** tab.
4. Enter a **Dataset Name** (3–50 characters, lowercase letters, numbers, and hyphens).
5. Select a **Neon Project** from the dropdown. This lists all projects accessible to your API key.
6. Optionally change the **Database Name** (defaults to `neondb`).
7. Configure the **Number of available databases** (how many branches to keep in the pool).
8. Click **Create Dataset**.

![Neon dataset creation form with project selected and database name configured](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-6b37ac434256299d4bcb648d6a86f612e15ee848%2Frelease-create-neon-dataset.png?alt=media)

A password is automatically generated for each branch — you don't need to set one manually.

## How It Works

When Release creates an ephemeral environment that uses a Neon dataset:

1. Release creates a **new branch** from the default branch of your Neon project.
2. A **compute endpoint** is automatically provisioned for the branch.
3. A **database role** is created with connection credentials.
4. Connection credentials are automatically injected as **environment variables** into your services.
5. When the environment is torn down, the branch (and its compute endpoint) is deleted to clean up resources.

### Environment Variables

The following environment variables are automatically set for services using Neon datasets. The prefix is derived from the dataset name (uppercased, with hyphens replaced by underscores).

For example, a dataset named `my-app` would produce:

| Variable                       | Description                     |
| ------------------------------ | ------------------------------- |
| `MY_APP_DB_POOL_HOST`          | Neon connection hostname        |
| `MY_APP_DB_POOL_PASS`          | Database password               |
| `MY_APP_DB_POOL_USER`          | Database username               |
| `MY_APP_DB_POOL_DATABASE_NAME` | Database name within the branch |
| `MY_APP_DB_POOL_NAME`          | Branch name created by Release  |

### Key Benefits of Neon Branching

* **Instant provisioning** — Neon branches are created in seconds using copy-on-write, regardless of database size.
* **Cost-efficient** — Neon's serverless architecture means compute scales to zero when not in use. You only pay for the storage diff between branches.
* **Full data isolation** — Each branch gets a complete copy of the database, so environments can't interfere with each other.

## Updating the Integration

To update your Neon credentials:

1. Go to **Configuration** > **Integrations** > **Neon**.

![Neon integration page with Actions dropdown](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-fa39fe9c684ddb695f21860de8d9c2be0767533c%2Frelease-neon-installed.png?alt=media)

2. Click **Actions** > **Configure**.
3. Update the API Key as needed.
4. Click **Save**.

## Troubleshooting

### Integration won't connect

* Verify your API key hasn't been revoked
* Ensure the API key has access to the projects you want to use
* If using an organization API key, ensure it has the correct permissions

### Branches not creating

* Verify your Neon project hasn't reached its branch limit (free tier allows 10 branches)
* Check that your default branch is in a healthy state in the Neon Console

### Connection issues in environments

* Neon requires SSL connections — ensure your application is configured to use SSL
* Neon is PostgreSQL-only — ensure your application's database driver is configured for PostgreSQL
* If connections are timing out, the compute endpoint may have scaled to zero. Neon auto-wakes endpoints on connection, but the first connection may take a few seconds


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.release.com/integrations/integrations-overview/neon-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.