# Source: https://neon.com/llms/guides-vercel-managed-integration.txt

# Connecting with the Vercel-Managed Integration

> This document details the process for integrating Neon with Vercel using the Vercel-managed integration, enabling users to seamlessly connect their Neon databases to Vercel applications.

## Source

- [Connecting with the Vercel-Managed Integration HTML](https://neon.com/docs/guides/vercel-managed-integration): The original HTML version of this documentation

What you will learn:
- [What the Vercel-Managed Integration is](https://neon.com/docs/guides/vercel-managed-integration#about-this-integration)
- [How to install it from the Vercel Marketplace](https://neon.com/docs/guides/vercel-managed-integration#installation-walkthrough)
- [How (and why) to enable automated Preview Branching](https://neon.com/docs/guides/vercel-managed-integration#enable-automated-preview-branching-recommended)
- [Where to manage billing and configuration](https://neon.com/docs/guides/vercel-managed-integration#managing--billing)

Related topics:
- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Manual Connections](https://neon.com/docs/guides/vercel-manual)

---

## About this integration

**Vercel-Managed Integration** (also known as _Neon Postgres Native Integration_) lets you add a Neon Postgres database to your Vercel project **with billing handled entirely inside Vercel**. Installing it:

- Creates a Neon account + project for you (if you don't already have one)
- For existing Neon users, adds a new organization named `Vercel: <team-name>` to your account
- Injects the required database environment variables (`DATABASE_URL`, etc.) into your Vercel project
- Optionally creates a dedicated database branch for every Preview Deployment so you can test schema changes safely

   **Note** Who should use this path?: Choose the Vercel-Managed Integration if you **do not already have a Neon account** *or* you prefer to consolidate payment for Neon inside your Vercel invoice.

---

## Installation walkthrough

## Open Neon integration

Open the [Neon integration on the Vercel Marketplace](https://vercel.com/marketplace/neon) and click **Install**.

## Add the integration in Vercel

This opens the **Install Neon** modal where you can choose between two options. Select **Create New Neon Account**, then click **Continue**.



## Complete Vercel's configuration

Accept the terms, pick a region & plan, then name your database. (Remember: a "Database" in Vercel is a **Project** in Neon.)

## View storage settings

After creation you'll land on Vercel's **Storage** tab that includes status, plan, connection string, billing plan, and more.

## Optionally open the project in the Neon Console

From the **Storage** tab, click **Open in Neon** to jump straight to your new Neon project dashboard in the Neon Console. You'll notice it lives in an organization named `Vercel: <your-vercel-team>`.

---

## Connecting the database to a Vercel project

1. In **Storage → `<your database>` → Connect Project** choose the Vercel project and the environments that should receive database variables (Development, Preview, Production).

   

2. (Optional) Under **Advanced Options → Deployments Configuration** enable **Preview** to turn on _Preview Branching_ (see next section).

   

3. Click **Connect**.

   **Tip** Environment variable prefix: You can add a prefix if you have multiple databases in the same project, e.g. `PRIMARY_`.

---

## Enable automated preview branching (recommended)

Preview branching creates an isolated Neon branch (copy-on-write) for every Vercel Preview Deployment so database schema changes can be tested safely.

To enable:

1. While connecting the project (step above) toggle **Required → Preview**.
2. Make sure **Resource must be active before deployment** is also on. This allows Vercel to wait for the branch to be ready.

Once enabled, the flow looks like this:

1.  Developer pushes to feature branch → Vercel kicks off Preview Deployment.
2.  Vercel sends a webhook to Neon → Neon creates branch `preview/<git-branch>`.
3.  Environment variables for the branch connection are injected via webhook at deployment time, overriding preview environment variables for this deployment only (cannot be accessed or viewed in your Vercel project's environment variable settings).
4.  (Optional) Run migrations in build step so schema matches code.

    

        To apply schema changes automatically, add migration commands to your Vercel build configuration:

        1. Go to **Vercel Dashboard → Settings → Build and Deployment Settings**
        1. Enable **Override** and add your build commands, including migrations, for example:

           ```bash
           npx prisma migrate deploy && npm run build
           ```

    This ensures schema changes in your commits are applied to each preview deployment's database branch.

### Test the setup

To verify preview branching works:

1. Create a local branch: `git checkout -b test-feature`
2. Make any change and commit: `git commit -a -m "Test change"`
3. Push: `git push`
4. Check Vercel deployments and Neon Console branches to confirm the preview branch was created

---

## Automatic branch cleanup

Preview branches are automatically deleted when their corresponding Vercel deployments are deleted. This keeps your Neon project organized and reduces storage usage.

**How it works:**

- Each Git branch can have multiple Vercel deployments, all using the same Neon branch.
- When the last deployment for a Git branch is deleted (manually or via Vercel's deployment retention policy), Neon automatically deletes the corresponding database branch.
- Cleanup happens when deployments are deleted, which you can configure using [Vercel's retention policy settings](https://vercel.com/docs/deployment-retention). By default, Pre-Production Deployments (preview environments) are retained for 180 days:

  

   **Note**: This deployment-based cleanup differs from the [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration), which deletes branches when Git branches are deleted.

---

## Managing & billing

Because your database is managed by Vercel, you can only perform these actions **in the Vercel dashboard**:

- Change plan, billing tier, or scale settings (compute size, autoscaling, scale-to-zero)
- View or modify database configuration via **Storage → Settings → Change Configuration**
- Monitor usage via **Storage → Usage** (also available in Neon Console)
- Create additional databases (each becomes a new Neon project)
- Rename or delete a database (deleting removes the underlying Neon project permanently)
- Manage members / collaborators (handled through Vercel "Members", not the Neon Console) - (see [FAQ](https://neon.com/docs/guides/vercel-managed-integration#frequently-asked-questions-faq) for details)
- Delete the Neon organization (only happens automatically if you uninstall the integration)
- Update connection-string environment variables (prefix changes, etc.)

Everything else (querying data, branching, monitoring usage) works exactly the same in the Neon Console.

### Team member synchronization

Team membership changes in Vercel automatically sync to your Neon organization:

- **Role changes**: When a team member's role changes in Vercel, their Neon role updates based on Vercel's JWT token mapping (see [FAQ](https://neon.com/docs/guides/vercel-managed-integration#why-do-vercel-team-members-with-member-role-have-the-admin-role-in-neon) for details). Most Vercel roles (Owner, Admin, Member) map to 'Admin' in Neon, while read-only roles (Viewer, Billing) map to 'Member' in Neon.
- **Removals**: When a user is removed from your Vercel team, they're automatically removed from the associated Neon organization.

This ensures both platforms stay aligned for security and access control.

### Project transfers between teams

When you transfer a Vercel project to another team, the linked Neon project automatically moves to the new team's Neon organization:

- The linked Neon project moves from the old organization to the new one.
- Environment variables and settings transfer with it.
- If the destination's plan doesn't support the project's requirements (autoscaling limits, point-in-time restore window, etc.), you'll be prompted to upgrade.

This eliminates the need to manually reconfigure integrations when reorganizing projects.

---

## Common operations

### Add another database (project)

1. Go to **Integrations → Neon Postgres → Manage → More Products → Install**
2. Select region, scale settings, and plan
3. Specify a **Database Name** and click **Create**

### Change compute / scale settings

**Storage → Settings → Change Configuration** lets you resize compute, adjust scale-to-zero, or switch Neon plan tiers. Changes apply to _all_ databases in the installation.

   **Important**: Changing your plan affects **all databases** in this integration, not just the current one.

### Delete the database

Deleting from Vercel permanently removes the Neon project and all data. This cannot be undone.
To delete:

1. Vercel Dashboard → Storage → Settings
2. Select your database
3. Find Delete Database section and confirm

### Disconnect a project from database

To disconnect a Vercel project without deleting the database:

1. Go to **Storage → `<your database>` → Projects**
2. Select your project and choose **Remove Project Connection**

This removes database environment variables from your Vercel project but keeps the database intact. Previously created preview branches remain but new ones won't be created.

### Manage branches created by the integration

Preview branches are automatically deleted when their deployments expire, but you can also manually delete branches via:

- [Neon Console](https://neon.com/docs/manage/branches#delete-a-branch) - Individual or bulk deletion
- [Neon CLI](https://neon.com/docs/reference/cli-branches#delete) - Command line management
- [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api) - Programmatic cleanup

   **Note** Unused branches are archived: Branches you don't delete are eventually archived, consuming archive storage space. See [Branch archiving](https://neon.com/docs/guides/branch-archiving).

---

## Environment variables set by the integration

| Variable                                                          | Purpose                                                             |
| :---------------------------------------------------------------- | :------------------------------------------------------------------ |
| `DATABASE_URL`                                                    | Pooled connection string (PgBouncer)                                |
| `DATABASE_URL_UNPOOLED`                                           | Direct connection string                                            |
| `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGDATABASE`, `PGPASSWORD` | Raw pieces to build custom strings                                  |
| `POSTGRES_*` (legacy)                                             | Provided for backwards compatibility with Vercel Postgres templates |
| `NEXT_PUBLIC_STACK_PROJECT_ID`, `STACK_SECRET_SERVER_KEY`, etc.   | Neon Auth variables for drop-in authentication                      |

> **Neon Auth variables** automatically sync user profiles to your database in the `neon_auth.users_sync` table, enabling authentication without additional setup. Learn more in the [Neon Auth guide](https://neon.com/docs/guides/neon-auth).

---

## Limitations

- You cannot use this integration with the **Neon-Managed integration** in the same Vercel project
- **Neon CLI access**: Requires API key authentication (the `neon auth` command won't work since the account is Vercel-managed)
- Cannot install if you currently use Vercel Postgres (deprecated) - contact Vercel about transitioning
- **Preview deployment environment variables**: Branch-specific connection variables cannot be accessed or viewed in your Vercel project's environment variable settings (they're injected at deployment time only and not stored to avoid manual cleanup when branches are deleted)

## Frequently Asked Questions (FAQ)

### Why can't I see Vercel team members in the Neon Console?

Users added to your Vercel team aren't automatically visible in the Neon organization. Team members only appear in Neon when they:

1. Click the **Open in Neon** button from the Vercel integration page
2. Complete the authentication flow

### Why do Vercel team members with 'Member' role have the 'Admin' role in Neon?

This occurs due to how Vercel's JWT tokens map roles to the integration. According to [Vercel's documentation](https://vercel.com/docs/integrations/create-integration/marketplace-api#user-authentication), the JWT token's `user_role` claim doesn't directly map Vercel team roles:

- **ADMIN role in JWT**: Granted to users capable of installing integrations (includes Vercel Owner, Admin, and Member roles) → maps to Admin in Neon.
- **USER role in JWT**: Only granted to users with read-only Vercel roles (includes Billing and Viewer roles) → maps to Member in Neon.

As a result, most active Vercel team members receive Admin access in the Neon organization. This is expected behavior and ensures team members can fully manage database resources.