> This page location: Integrations & tooling > Integrations (3rd party) > Deploy > Vercel > Vercel-Managed (Native Integration)
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: The Vercel-Managed Integration (also called Neon Postgres Native Integration) provisions a Lakebase Postgres database from the Vercel Marketplace and routes all billing through your Vercel invoice, injecting DATABASE_URL and related environment variables automatically. Choose this path over the Neon-Managed Integration when you have no existing Neon account or want a single Vercel bill; it does not support the `neon login` CLI command. Automated Preview Branching creates an isolated copy-on-write Lakebase Postgres branch for each Git branch you deploy as a Vercel Preview Deployment, with branches cleaned up according to Vercel's 6-month default deployment retention policy.

# Connecting with the Vercel-Managed Integration

Create and manage Neon databases directly from your Vercel dashboard

Last updated: 2026-11-18

**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)
- [How to choose which branch feeds Vercel Production](https://neon.com/docs/guides/vercel-managed-integration#choose-a-production-branch)
- [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 Lakebase 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 each Git branch you preview, 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**.

## Choose a team

Under **Choose Team**, select the Vercel team to install Neon to, then click **Continue**. If Neon is already installed for that team, you can still continue: the new database joins the existing installation.

## Complete Vercel's configuration

Under **Configuration and Plan**, choose a region and set the optional services:

- **Auth** (on by default): provisions [Managed Better Auth](https://neon.com/docs/auth/overview) for your app's users, with profiles synced to Postgres.
- **Realtime** (off by default): enables [Neon Realtime](https://neon.com/docs/realtime/overview) (beta) on the database's default branch. Preview branches get their own. You can only turn on Realtime when you create a database, not for an existing one.

Auth and Realtime apply only to the database you're creating. Under **Installation Plan**, choose a plan. The plan applies to every database in this installation. Click **Continue**.

## Confirm and create

On the **Confirmation** step, review the **Resource Name** and the parameters, then click **Create**. The resource name becomes the database name in Vercel and the project name in Neon. (Remember: a "Database" in Vercel is a **Project** in Neon.) If you go back to an earlier step, check the parameters again before you click **Create**, because going back resets your choices and generates a new name.

When **Your Neon database is ready to use** appears, click **Continue**.

## Connect a project

The **Connect a Project** step lets you connect the database to a Vercel project right away. See [Connecting the database to a Vercel project](https://neon.com/docs/guides/vercel-managed-integration#connecting-the-database-to-a-vercel-project) for the options, or click **Skip** to connect later.

## View storage settings

You'll land on the database's page in Vercel **Storage**, which shows its status, plan, connected projects, and quickstart snippets for connecting.

## Optionally open the project in the Neon Console

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

---

## Connecting the database to a Vercel project

You can connect a project during installation (the **Connect a Project** step) or later from **Storage → `<your database>` → Connect to Project**.

1. Choose the Vercel **Project** and the **Environments** that should receive database variables. **Production** and **Preview** are selected by default. Add **Development** if you also want the variables in that environment.
2. (Optional) Under **Create database branch for deployment**, select **Preview** to turn on _Preview Branching_ (see next section). Leave **Production** unchecked: production deployments use your [production branch](https://neon.com/docs/guides/vercel-managed-integration#choose-a-production-branch).
3. (Optional) Set a **Custom Prefix** for the environment variables. You only need one if your Vercel project already uses the unprefixed variable names, for example from a database you connected earlier.
4. (Optional) Leave **Sensitive** on (the default) to store the variables as [sensitive environment variables](https://vercel.com/docs/environment-variables/sensitive-environment-variables), which can't be read back from the Vercel dashboard or CLI. Turn it off if you need to view or pull the values.
5. Click **Connect**.

To change these settings later, open **Storage → `<your database>` → Projects**, then select **Update Project Connection** from the **⋮** menu next to your project.

---

## Enable automated preview branching (recommended)

Preview branching creates an isolated Neon branch (copy-on-write) for each Git branch that gets a Vercel Preview Deployment, so database schema changes can be tested safely. Later preview deployments of the same Git branch reuse that Neon branch, so its data and schema carry over from one deployment to the next.

**Tip: Managed Better Auth support for preview deployments**

If you've enabled [Managed Better Auth](https://neon.com/docs/auth/overview) on your production branch, it's automatically provisioned on preview branches too. Preview deployments receive `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` environment variables, letting you test authentication in isolated environments. Auth data branches with your database, so each preview has its own independent user profiles and sessions.

To enable it, select **Preview** under **Create database branch for deployment** when you connect the project (step above).

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>` from your default branch, or reuses it if it already exists.
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.

   ![Vercel build commands](https://neon.com/docs/guides/vercel_build_command.png)

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

   1. Go to **Vercel Dashboard → Settings → Build and Deployment Settings**
   2. 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.

**Note: Preview branches count toward your active compute limit**

Each preview branch gets its own compute, and every running compute counts toward your [concurrently active compute limit](https://neon.com/docs/reference/glossary#concurrently-active-compute-limit). If many preview deployments run at once, computes beyond the limit stay suspended and connections to them fail. Preview computes [scale to zero](https://neon.com/docs/introduction/scale-to-zero) when idle, and [cleaning up stale preview branches](https://neon.com/docs/guides/vercel-branch-cleanup) keeps the count down. If your team regularly runs into the limit, [contact Support](https://neon.com/docs/introduction/support) to request an increase.

### 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 the new branch: `git push -u origin test-feature`
4. Check Vercel deployments and Neon Console branches to confirm the preview branch was created

---

## Choose a production branch

Your Vercel Production deployments use a dedicated **production branch** in Neon. When the integration creates your database, the production branch is your project's default branch. Preview branches are always created from the default branch.

The production branch is independent of the default branch. If you later change the project's default branch, Production keeps using the same production branch. To point Production at a different branch, for example a protected `production` branch:

1. In the Neon Console, open your project and go to **Integrations**.
2. Under **Added**, click **Settings** next to **Vercel**.
3. Under **Production branch**, select the branch you want and click **Save**. If a production branch is already set, confirm the change.
4. Redeploy your production deployment in Vercel so it picks up the new branch's credentials.

The branch you choose can't be a preview branch or have [branch expiration](https://neon.com/docs/guides/branch-expiration) set, and it needs a read-write compute. Branches created before January 14, 2024 aren't listed.

While the integration is connected, the production branch and its read-write compute can't be deleted. To delete that branch, choose a different production branch first.

---

## Automatic branch cleanup

Preview branches are automatically deleted when their corresponding Vercel deployments are removed. The timing of this cleanup depends on [Vercel's deployment retention policy](https://vercel.com/docs/deployment-retention), which retains preview deployments for 6 months by default.

**Important: Preview branches may not be deleted for months**

Because of Vercel's default retention settings, preview branches can persist long after a PR is closed. To understand the full timeline, reduce your retention policy, or set up immediate cleanup, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

---

## 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)
- Delete a database (see [Delete the database](https://neon.com/docs/guides/vercel-managed-integration#delete-the-database))
- Manage members / collaborators (handled through Vercel "Members", not the Neon Console) - (see [FAQ](https://neon.com/docs/guides/vercel-managed-integration#frequently-asked-questions) for details)
- Delete the Neon organization (this happens automatically when you [uninstall the integration](https://neon.com/docs/guides/vercel-managed-integration#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.

You can rename a database from either side. Renaming the project in the Neon Console or with the Neon API also renames the database in Vercel, so the names stay in sync.

If you're on Neon's Scale plan, you can open support tickets for any Neon issue directly from the Neon Console. See [Support tickets](https://neon.com/docs/introduction/support#support-tickets) for details.

### Team member synchronization

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

- **Initial access**: Team members must click **Open in Neon** from the Vercel integration page and complete authentication before they appear in the Neon organization. This one-time step links their Vercel identity to Neon.
- **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.

**Note:** Organizations managed through the Vercel-managed integration use Neon's legacy roles (Admin and Member), as described above. The newer [organization roles and per-project permissions](https://neon.com/docs/manage/user-permissions) don't apply to Vercel-managed organizations.

### 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 [history window](https://neon.com/docs/introduction/history-window), etc.), you'll be prompted to upgrade.

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

This is separate from Neon's [project transfer](https://neon.com/docs/manage/orgs-project-transfer) feature, which doesn't support Vercel-managed organizations as a source or destination.

### Move a database to a Neon-managed organization

You can't transfer a project out of a Vercel-managed organization, for example to move billing from Vercel to Neon. Instead, copy your data into a new project in a Neon-managed organization:

1. Get the source connection string. In the Neon Console, open your project in the `Vercel: <team-name>` organization, click **Connect**, and turn off **Connection pooling** to copy the direct connection string. If the integration stored your variables as **Sensitive**, you can't copy them from Vercel.
2. Switch to (or [create](https://neon.com/docs/manage/orgs-manage#create-an-organization)) a Neon-managed organization, and copy your data with one of these options. The first two are one-time copies, so plan a short write freeze before you cut over.
   - **Import Data Assistant**: For databases under 10 GB. On the **Projects** page, click **Import data**, paste the connection string, and follow the steps. The assistant creates the new project for you. Choose the same Postgres version as your source or newer (new Vercel-managed databases use Postgres 18). If the checks list `plpgsql` as an unsupported extension, continue anyway: it's a false warning for Postgres 18 sources. The data lands on a new root branch named `import`, not the project's default branch, so after the import, [set `import` as the default branch](https://neon.com/docs/manage/branches#set-a-branch-as-default) and [delete](https://neon.com/docs/manage/branches#delete-a-branch) the empty one. See [Import Data Assistant](https://neon.com/docs/import/import-data-assistant).
   - **Dump and restore**: [Create a project](https://neon.com/docs/manage/projects#create-a-project) in the region and Postgres version you want, then copy the data with `pg_dump` and `pg_restore`. Works for any size. See [Migrate data from another Neon project](https://neon.com/docs/import/migrate-from-neon).
   - **Logical replication**: Keeps the new project in sync while your app still writes to the old one, so you can cut over with minimal downtime. See [Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon).
3. Point your app at the new project. In Vercel, [disconnect the project from the database](https://neon.com/docs/guides/vercel-managed-integration#disconnect-a-project-from-database), then connect the new Neon project with the [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration) or a [manual connection](https://neon.com/docs/guides/vercel-manual), and redeploy.
4. After you confirm the new project works, [delete the old database](https://neon.com/docs/guides/vercel-managed-integration#delete-the-database) in Vercel.

---

## Common operations

### Add another database (project)

1. Go to **Integrations → Neon → Manage**, then under **More Products**, click **Install** on the Neon card
2. Choose a region and the Auth and Realtime settings for the new database
3. On the **Confirmation** step, check the **Resource Name** and parameters, then click **Create**
4. Connect it to a project. Both **Create database branch for deployment** options start unchecked, and if the project already uses another database's variables, set a **Custom Prefix**

### 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 a database in Vercel deletes the underlying Neon project and all of its data. To delete:

1. In the Vercel dashboard, go to **Storage** and select your database.
2. Open the database's **Settings** page.
3. In the **Delete Database** section, click **Delete Database**, type the database and team names, and confirm.

Vercel warns that this can't be undone, but Neon keeps the deleted project for 7 days. During that time you can [recover it](https://neon.com/docs/manage/projects#recover-a-deleted-project) from the Neon Console, CLI, or API, as long as the Vercel integration for the organization still exists. Recovery adds the database back to Vercel without its project connections, so [connect it to your projects](https://neon.com/docs/guides/vercel-managed-integration#connecting-the-database-to-a-vercel-project) again and redeploy. If the Neon organization was deleted too, recovery requires Support.

### Disconnect a project from database

To disconnect a Vercel project without deleting the database:

1. Go to **Storage → `<your database>` → Projects**
2. Open the **⋮** menu next to your project, select **Remove Project Connection**, and confirm

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.

### Uninstall the integration

**Warning: Uninstalling deletes your databases**

Uninstalling the Neon integration from your Vercel team deletes the `Vercel: <team-name>` organization in Neon, including every project and all of its data. To keep your data, [move it to a Neon-managed organization](https://neon.com/docs/guides/vercel-managed-integration#move-a-database-to-a-neon-managed-organization) first.

If you only want to stop a Vercel project from using a database, [disconnect the project](https://neon.com/docs/guides/vercel-managed-integration#disconnect-a-project-from-database) instead. To remove a single database, [delete the database](https://neon.com/docs/guides/vercel-managed-integration#delete-the-database). Both leave the integration and your other databases in place.

### Manage branches created by the integration

You can manually delete preview branches at any time via the [Neon Console](https://neon.com/docs/manage/branches#delete-a-branch), [Neon CLI](https://neon.com/docs/cli/branches#delete), or [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api). For automated cleanup options, including GitHub Actions, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

**Note: Unused branches are archived**

Branches you don't delete are eventually [archived](https://neon.com/docs/guides/branch-archiving), reducing storage costs but still consuming archive storage space.

---

## 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 |
| `NEON_PROJECT_ID` | ID of the Neon project behind the database |
| `NEON_AUTH_BASE_URL`, `VITE_NEON_AUTH_URL` | Managed Better Auth endpoints (when enabled on production branch) |
| `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET` | [Neon Realtime](https://neon.com/docs/realtime/overview) endpoint and secret (when Realtime is enabled). Preview deployments get their own branch's values. |

---

## 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 login` command won't work since the account is Vercel-managed)
- Cannot install if you currently use Vercel Postgres (deprecated) - contact Vercel about transitioning
- **Project transfer**: Neon's [project transfer](https://neon.com/docs/manage/orgs-project-transfer) doesn't work into or out of a Vercel-managed organization. To move between Vercel teams, [transfer the Vercel project to another team](https://neon.com/docs/guides/vercel-managed-integration#project-transfers-between-teams). To move out of Vercel billing, [migrate to a Neon-managed organization](https://neon.com/docs/guides/vercel-managed-integration#move-a-database-to-a-neon-managed-organization).
- **Postgres version**: You can't choose a Postgres version when you create a database from Vercel. New databases use Neon's default version.
- **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)

## Troubleshooting

### Database environment variables are missing from a deployment

Check how the database is connected under **Storage → `<your database>` → Projects**:

- **Environment not selected**: The integration only sets variables for the environments (Development, Preview, Production) you selected when you [connected the project](https://neon.com/docs/guides/vercel-managed-integration#connecting-the-database-to-a-vercel-project).
- **Custom prefix**: If you set a **Custom Prefix**, the variable names include it (for example, `MYDB_DATABASE_URL` instead of `DATABASE_URL`). Update your code or remove the prefix.
- **Preview branching off**: Without **Preview** selected under **Create database branch for deployment**, preview deployments use the same database variables as other environments instead of a dedicated branch.
- **Branch-specific values not visible**: With preview branching on, each preview deployment's branch credentials are injected at deployment time. They don't appear in your Vercel project's environment variable settings. Check the Neon Console **Branches** page to confirm a `preview/<git-branch>` branch was created.

Variables only apply to deployments created after you change the connection, so redeploy after updating it.

### Connecting another database fails with a prefix error

If a Vercel project already uses a database's unprefixed variables, connecting a second database to the same environments fails with this message:

```text
Resource "<database>" is already connected to this project without a prefix in one of the chosen environments. Choose a prefix.
```

Set a **Custom Prefix** for the second database. For example, the prefix `RT` gives variables such as `RT_DATABASE_URL` and `RT_NEON_REALTIME_URL`.

### Realtime shows as off in Vercel

The database's **Settings** page in Vercel can show **Realtime** as **False** for a database you created with Realtime on, and turning it on there has no effect. You can only turn on Realtime when you create a database. To check whether it's on, look for the `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET` variables in your Vercel project.

### Preview deployments can't connect to the database

If preview deployments start failing to connect while many previews are active, you may have hit the [concurrently active compute limit](https://neon.com/docs/reference/glossary#concurrently-active-compute-limit). See [Preview branches count toward your active compute limit](https://neon.com/docs/guides/vercel-managed-integration#enable-automated-preview-branching-recommended).

## Frequently asked questions

### 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.

---

## Related docs (Vercel)

- [Integration Overview](https://neon.com/docs/guides/vercel-overview)
- [Neon-Managed (Connectable Account)](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Managing preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup)
- [Manual Setup](https://neon.com/docs/guides/vercel-manual)
- [Connecting to Neon from Vercel](https://neon.com/docs/guides/vercel-connection-methods)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/guides/vercel-managed-integration"}` to https://feedback.neon.tech/ (no auth required).
