> This page location: Integrations & tooling > Integrations (3rd party) > Deploy > Vercel > Neon-Managed (Connectable Account) > Full Neon documentation index: https://neon.com/docs/llms.txt > Summary: The Neon-Managed Vercel Integration connects an existing Neon project to a Vercel project via Connectable Accounts, keeping billing in Neon and automatically creating an isolated database branch named `preview/` for each Vercel preview deployment. Use this integration instead of the Vercel-Managed Integration when you already have a Neon account or need direct billing control. The two integrations cannot coexist in the same Vercel project, and each Neon project maps to exactly one Vercel project. When connecting, you can choose which Neon branch feeds Vercel's Production environment variables. The integration injects `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and legacy `PG*` variables per deployment, with optional automatic branch cleanup when Git branches are deleted. # Connecting with the Neon-Managed Integration Link an existing Neon project to Vercel and keep billing in Neon **What you will learn:** - [The purpose of the Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration#about-this-integration) - [How to install it from Connectable Accounts](https://neon.com/docs/guides/neon-managed-vercel-integration#installation-steps) - [How to choose which branch feeds Vercel Production](https://neon.com/docs/guides/neon-managed-vercel-integration#choose-a-production-branch) - [How automated Preview Branching works](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works) - [How to manage environment variables and branch cleanup](https://neon.com/docs/guides/neon-managed-vercel-integration#managing-the-integration) **Related topics** - [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration) - [Manual Connections](https://neon.com/docs/guides/vercel-manual) --- ## About this integration The **Neon-Managed Integration** links your existing Neon project to a Vercel project while keeping billing in Neon. Instead of sharing a single database across all preview deployments, this integration creates an isolated database branch for each preview deployment. **Key features:** - One-click connection from Vercel Marketplace - Automatic database branches for each preview deployment - Environment variable injection (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `PG*` variables) - Automatic cleanup when branches are deleted **Note: Who should use this integration?** Choose the Neon-Managed Integration if you already have a Neon account/project or prefer to manage billing directly with Neon. --- ## Prerequisites Before you begin, ensure you have: - A Neon account with at least one project and database role - A Vercel account with a project linked to GitHub, GitLab, or Bitbucket --- ## Installation steps ## Connect from Neon Console In the [Neon Console](https://console.neon.tech), navigate to **Integrations** and click **Add** under Vercel. Click **Install from Vercel Marketplace** to open the integration in Vercel. ## Add the integration in Vercel On the Vercel page, click **Install**. This opens the **Install Neon** modal where you can choose between two options. Select **Link Existing Neon Account**, then click **Continue**. ![Install on Existing Neon Account](https://neon.com/docs/guides/vercel_install_neon_modal_existing_account.png) **Tip:** Alternatively, if you're accessing this directly from the Vercel Marketplace, locate the **Connectable Accounts** section, find **Neon**, and click **Add**. This differs from the **Native Integrations** section in the Vercel Marketplace. ![Add Neon from Connectable Accounts](https://neon.com/docs/guides/vercel_add_connected_neon_account.png) ## Configure the connection Choose which Vercel account and projects can use this integration. Each Neon project connects to exactly one Vercel project. Selecting **All projects** makes the integration available to other Vercel projects. ![Connect Neon Account Projects](https://neon.com/docs/guides/vercel_connect_neon_account_projects.png) ## Set up project integration In the **Integrate Neon** dialog: 1. **Select your Vercel project** ![Select a Vercel project](https://neon.com/docs/guides/vercel_select_project.png) 2. **Choose your Neon account, project, production branch, database, and role** ![Connect to Neon](https://neon.com/docs/guides/vercel_connect_neon.png) Under **Production branch**, pick the Neon branch whose credentials Vercel should use for **Production** deployments. If you leave the default selection, Production uses your project's default branch. The read-only **Default branch** field shows the branch that preview branches are created from. The branch you select must: - Belong to the chosen Neon project - Include the database and role you selected - Not be a Vercel preview branch (for example, `preview/`) - Not have branch expiration (TTL) enabled 3. **Configure optional settings:** - Enable **Create a branch for your development environment** to create a persistent `vercel-dev` branch and set Vercel development environment variables for it. The `vercel-dev` branch is a clone of your project's default branch (`main`) that you can modify without affecting data on your default branch. - Enable **Automatically delete obsolete Neon branches** (recommended) to clean up branches when git branches are deleted. 4. Click **Connect**, then **Done** ![Confirm integration settings](https://neon.com/docs/guides/vercel_confirm_settings.png) ![Vercel integration success](https://neon.com/docs/guides/vercel_success.png) ### Choose a production branch By default, Neon uses your project's **default branch** for Vercel's Production environment variables. When your live application data lives on a different branch (for example, a protected `production` branch while `main` remains the default), select that branch during setup instead. | Vercel environment | Neon branch used | | ------------------ | ------------------------------------------------------------------------------------------------ | | **Production** | The branch you choose at connect (or the project default if unchanged) | | **Preview** | A new `preview/` branch per deployment, parented from the project **default** branch | | **Development** | The optional `vercel-dev` branch, created as a clone of the project **default** branch | Only Production credentials come from your chosen branch. Preview and Development environments are unchanged. Neon resolves that branch's read-write compute endpoint and the password for the role you selected on that branch (role passwords can differ across branches). If [Managed Better Auth](https://neon.com/docs/auth/overview) is enabled on your production branch, Production deployments receive `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` from that branch. Preview deployments still get isolated auth on their own preview branches. The production branch is independent of your project's default branch. If you later change the default branch, Production keeps using the branch you chose. To change the production branch after setup, go to **Neon Console → Integrations**, click **Manage** next to **Vercel** under **Added**, and open the **Branches** tab. Select a different branch under **Production branch** and click **Save**. Changing a branch that's already set asks you to confirm first. Redeploy your production deployment in Vercel so it picks up the new branch's credentials. The branch you choose must meet the requirements listed above and have a read-write compute. 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, or disconnect the integration. ### What happens after installation Once connected successfully, you'll see: **In Neon Console:** - A `vercel-dev` branch (if enabled) under **Branches** - Future preview branches will appear here automatically ![Neon branches](https://neon.com/docs/guides/vercel_neon_branches.png) **In Vercel:** - `DATABASE_URL` and other environment variables under **Settings → Environment Variables** ![Vercel environment variables](https://neon.com/docs/guides/vercel_env_variables.png) --- ## How Preview Branching works The integration automatically creates isolated database environments for each preview deployment: **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. Preview branches are always parented from your project's **default branch**, even when Production uses a different branch. ## Developer pushes to feature branch When you push commits to a feature branch, Vercel triggers a preview deployment. ## Integration creates Neon branch The integration receives a webhook from Vercel and creates a new Neon branch named `preview/` using the Neon API. ## Environment variables injected Vercel receives the new connection string and injects it as environment variables for that specific deployment only. This isolation allows you to test data and schema changes safely in each pull request. 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 generate && npx prisma migrate deploy && npm run build ``` This ensures schema changes in your commits are applied to each preview deployment's database branch. ![Vercel build commands](https://neon.com/docs/guides/vercel_build_command.png) ![Neon preview deployment branch](https://neon.com/docs/guides/vercel_deployments.png) ![Neon preview deployment branch](https://neon.com/docs/guides/vercel_neon_app_update.png) ![Vercel preview settings](https://neon.com/docs/guides/vercel_preview_settings.png) --- ## Managing the integration ### Environment variables By default, the integration sets `DATABASE_URL` and `DATABASE_URL_UNPOOLED` for Production and Development environments. You can also select `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGDATABASE`, and `PGPASSWORD`. Preview variables are injected dynamically per deployment. - `DATABASE_URL`: Pooled connection (recommended for most applications). For Production, sourced from the [production branch you chose at connect](https://neon.com/docs/guides/neon-managed-vercel-integration#choose-a-production-branch). - `DATABASE_URL_UNPOOLED`: Direct connection (for tools requiring direct database access) - `NEON_AUTH_BASE_URL`, `VITE_NEON_AUTH_URL`: Managed Better Auth endpoints. For Production, the values come from your production branch. You can select these variables on the **Settings** tab once Managed Better Auth is enabled on your production branch. **To customize which variables are used:** 1. Go to **Neon Console → Integrations**, click **Manage** next to **Vercel**, and open the **Settings** tab 2. Under **Vercel environment variables**, select the variables you want (for example, `PGHOST` or `PGUSER`) 3. Click **Save changes** ![Select Vercel variables](https://neon.com/docs/guides/vercel_select_variables.png) ### Password rotation behavior When you rotate the selected role password in Neon, the integration automatically syncs updated credentials to Vercel environment variables for connected projects. If deployments still use older credentials, open the **Settings** tab (**Neon Console → Integrations → Manage**) and click **Save changes** to force a resync. ### Branch cleanup **Automatic cleanup (recommended):** Enable **Automatically delete obsolete Neon branches** during setup to remove preview branches automatically when the corresponding Git branch is merged or deleted. You can change this setting later on the **Branches** tab (**Neon Console → Integrations → Manage**), under **Automation workflows**. Cleanup runs the next time a preview deployment is created. Unlike the [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration), this cleanup is not affected by Vercel's deployment retention policies. For a full comparison and additional cleanup options, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup). **Manual cleanup:** If needed, you can delete branches manually: - **Neon Console:** delete branches from your project's **Branches** page. See [Delete a branch](https://neon.com/docs/manage/branches#delete-a-branch). - **API/CLI:** Use the [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 programmatic cleanup **Warning: Important cleanup considerations** - **Don't rename branches:** Renaming either the Git branch or Neon branch breaks name-matching logic and may cause unintended deletions - **Avoid child branches:** Creating child branches on preview branches prevents automatic deletion - **Role dependency:** The integration depends on the selected role; removing it will break the integration ### Disconnect integration To disconnect the integration, go to **Neon Console → Integrations**, click **Manage** next to **Vercel**, open the **Disconnect** tab, and click **Disconnect**. This stops Neon from setting environment variables in Vercel. It doesn't remove existing branches or the integration itself. To fully remove the integration, uninstall it from your Vercel project's **Settings**. --- ## Limitations - **One-to-one relationship:** Each Neon project connects to exactly one Vercel project - **Integration exclusivity:** Cannot coexist with the Vercel-Managed Integration in the same Vercel project - **Role dependency:** Integration requires the selected PostgreSQL role to remain active --- ## Next steps ## After Installation - [ ] [Test preview branching](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works) Create a feature branch and push changes to verify preview deployments work correctly - [ ] [Configure build commands](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works) Add migration commands to Vercel's build settings if using an ORM like Prisma - [ ] [Set up branch cleanup](https://neon.com/docs/guides/neon-managed-vercel-integration#branch-cleanup) Enable automatic cleanup or establish a manual cleanup process - [ ] [Customize environment variables](https://neon.com/docs/guides/neon-managed-vercel-integration#environment-variables) Review and adjust which database variables are injected into your deployments --- ## Troubleshooting ### Environment variable conflicts If you see "Failed to set environment variables" during setup, remove conflicting variables in Vercel first: 1. Go to **Vercel → Settings → Environment Variables** 2. Remove or rename existing `DATABASE_URL`, `PGHOST`, `PGUSER`, `PGDATABASE`, or `PGPASSWORD` variables 3. Retry the integration setup ### Integration stops working **Issue:** Preview branches no longer created **Cause:** The PostgreSQL role selected during setup was deleted **Solution:** Reinstall the integration with a valid role, or change the role under **Default database and role** on the **Settings** tab (**Neon Console → Integrations → Manage**) --- ## Related docs (Vercel) - [Integration Overview](https://neon.com/docs/guides/vercel-overview) - [Vercel-Managed (Native Integration)](https://neon.com/docs/guides/vercel-managed-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/neon-managed-vercel-integration"}` to https://feedback.neon.tech/ (no auth required).