Neon Local Connect Extension

The Neon Local Connect extension lets you connect to any Neon branch using a familiar localhost connection string. Available for VS Code, Cursor, Windsurf, and other VS Code-compatible editors, the underlying Neon Local service handles the routing, authentication, and branch management behind the scenes. Your app connects to localhost:5432 like a local Postgres instance, but Neon Local routes traffic to your actual Neon branch in the cloud.

You can use this connection string in your app:

DATABASE_URL="postgres://neon:npg@localhost:5432/<database_name>"

Switch branches, and your app keeps using the same connection string.

What you can do

With the Neon Local Connect extension, you can:

• Instantly connect to any Neon branch using a single, static localhost connection string
• Create, switch, or reset branches directly from the extension panel
• Automate ephemeral branch creation and cleanup, no scripts required
• Open the Neon SQL Editor or Table View for your current branch with one click
• Launch a psql shell in your integrated terminal for direct SQL access

All without leaving your editor.
Learn more about branching in Neon and Neon Local.

Requirements

• Docker Desktop installed and running
• VS Code 1.85.0+, Cursor, Windsurf, or other VS Code-compatible editor
• A Neon account and API key (for ephemeral branches only; you can also create new keys from the extension)

1. Install the extension

   The Neon Local Connect extension is available on both marketplaces:

   For VS Code:

   • Open the Neon Local Connect extension page in the VS Code Marketplace.
   • Click Install.

   For Cursor, Windsurf, and other VS Code-compatible editors:

   • Open the Neon Local Connect extension page in the OpenVSX Registry.
   • Click Install or follow your editor's extension installation process.

2. Sign in to Neon

   • Open the Neon Local Connect panel in the VS Code sidebar and click Sign in.

     

   • Authenticate with Neon in your browser when prompted.

     

3. Connect to a branch

   You'll need to make a few selections — organization, project, and then branch — before connecting. If you're new to Neon, this reflects our object hierarchy: organizations contain projects, and projects contain branches. Learn more about how Neon organizes your data.

   You can connect to two types of branches:

   • Existing branch:
     For ongoing development, features, or team collaboration. The branch remains available until you delete it. Use this when you want to keep your changes and collaborate with others.

   • Ephemeral branch:
     For temporary, disposable environments (tests, CI, experiments). The extension creates the branch when you connect and deletes it automatically when you disconnect—no manual cleanup required. In CI or CLI workflows, you’d have to script this yourself. The extension does it for you.

   As part of choosing your connection, you'll also be asked to choose driver type: PostgreSQL for most Postgres connections, or Neon serverless for edge/HTTP. Read more about connection types.

   Existing branchEphemeral branch

   Connect to an existing branch (e.g., main, development, or a feature branch):

   

   note

   Selecting an ephemeral branch will prompt you to create and import API key for authentication.

4. Create a new branch

   Or you can create a new persistent branch for feature development, bug fixes, or collaborative work:

   1. Select your organization and project
   2. Click Create new branch... in the branch dropdown
   3. Enter a descriptive branch name (e.g., feature/user-authentication, bugfix/login-validation)
   4. Choose the parent branch you want to branch from (e.g., production, development)

   The extension creates the new branch and connects you immediately. This branch persists until you manually delete it.

5. Use the static connection string

   After connecting, find your local connection string in the extension panel. Copy it, update with your database name, and add it to your app’s .env or config.

   

   DATABASE_URL="postgres://neon:npg@localhost:5432/<database_name>"

   Your app connects to localhost:5432, while the Neon Local service routes the traffic to your actual Neon branch in the cloud.

   You only need to set this connection string once, no matter how many times you create, switch, or reset branches. Neon Local handles all the routing behind the scenes, so you never have to update your app config again.

6. Start developing

   Your application now connects to localhost:5432 using the driver you selected in the extension (Postgres or Neon serverless). See the quickstart for your language or framework for more details.

   • Framework quickstarts
   • Language quickstarts

Available commands

You can run any command by opening the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and typing “Neon Local Connect: ...”.

All commands below are available under the “Neon Local Connect:” prefix in the Command Palette.

Panel actions

And here's what you can do directly from the Neon panel.

Action	What it does
	Reset from parent branch — Instantly reset your branch to match its parent’s state. Great for rerunning tests or starting fresh. Learn more
	Open SQL Editor — Launch the Neon SQL Editor in your browser for advanced queries and data inspection. Learn more
	Open Table View — Browse your database schema and data in the Neon Console. Learn more
	Launch PSQL — Open a psql shell in your integrated terminal for direct SQL access. Use to test schema changes, run migrations, or debug from your IDE. Learn more

Next steps & resources

• Neon Local documentation
• Branching in Neon
• Serverless driver
• API keys