Getting started with Neon Local and Neon Local Connect

One of Neon's most powerful features is database branching, the ability to instantly create isolated, copy-on-write clones of your database for any task. Just as you create a Git branch for every new feature or bug fix, you can create a parallel database branch. This eliminates environment drift, prevents developers from overwriting each other's work on shared staging databases, and ensures every development environment is a perfect, isolated replica of production.

But how do you bring this cloud-native power into your local development workflow seamlessly? Constantly switching connection strings for each branch is tedious and error-prone. This is the problem that Neon Local and the Neon Local Connect VS Code extension solve. They act as a smart local proxy to your Neon database in the cloud. Your application connects to a single, static localhost address, while the tools handle all the complexity of routing and branch management behind the scenes.

This guide will walk you through setting up and using both Neon Local and Neon Local Connect to create a powerful, modern development workflow. You'll learn how to:

• Install and configure the Neon Local Connect extension in VS Code.
• Utilize the built-in Schema Viewer, SQL Editor, and Table Editor.
• Connect your local application to a Neon database using a single, static localhost connection string.
• Manage database branches (create, switch, reset) directly from your IDE.
• Use Neon Local with Docker Compose for CI/CD or non-VS Code environments.

Prerequisites

Before you begin, ensure you have the following:

• Neon account: A free Neon account. If you don't have one, sign up at Neon.
• VS Code: Or any compatible editor based on VS Code, such as Cursor or Windsurf.
• Docker: Docker Desktop must be installed and running on your machine. You can download it from docker.com.
• Node.js: Version 18 or later to run the example application.

Neon Local Connect

The easiest way to get started is with the Neon Local Connect VS Code extension. It manages the underlying Docker container for you, providing a full control panel for your Neon database within your editor.

Install the extension

First, install the extension from the Visual Studio Marketplace or OpenVSX.

1. Open your editor and navigate to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X).
2. Search for "Neon Local Connect".
3. Click Install.

You can also install it directly from the marketplace:

• VS Code Marketplace

  For VS Code & compatible editors

• OpenVSX Marketplace

  For Cursor, Windsurf etc.

Connect to your Neon account

Once installed, a new Neon icon will appear in your Activity Bar.

1. Click the Neon icon to open the Neon Local Connect panel.
2. Click Sign in with Neon. This will open a browser window to authenticate your Neon account using OAuth.
3. Authorize the application to connect to your Neon account.

Connect to a Database branch

After authenticating, the extension fetches your Neon projects and branches.

1. Select your Organization and Project.
2. Choose the Branch you want to work on (e.g., development). You can connect to an existing branch or an ephemeral branch that is created on connection and destroyed on disconnection.

   Using ephemeral branches

   For using ephemeral branches, you need to authenticate using a Neon API key. This is recommended to ensure that temporary branches are automatically cleaned up when your session ends. To get started, see Creating API keys. In the Neon Local Connect panel, click Import API Key to add your key.

3. Click Connect.

The extension will now start a Neon Local Docker container in the background and establish a proxy connection to your selected branch. Once connected, the panel will display a static, local connection string.

The connection string will always be the same, regardless of which branch you connect to: postgres://neon:npg@localhost:5432/<database_name>

Extension features

Neon Local Connect turns your IDE into a powerful database management tool, eliminating the need to switch contexts.

Database schema view

Once connected, a Database Schema view appears in the sidebar. This tree view lets you explore your entire database structure: databases, schemas, tables, columns, and relationships (PKs, FKs). Right-click any table for quick actions like Query Table, View Table Data, Truncate, or Drop.

Built-in SQL editor

Execute queries directly in your IDE. Right-click a table and select "Query Table" to open a pre-filled SELECT * query, or open a blank editor from the command palette.

• View results in a filterable, sortable table.

• Export data to CSV/JSON.

• See performance stats and detailed error messages.

  

Table data management

For quick edits, right-click a table and select "View Table Data" to open a spreadsheet-like interface.

• Edit rows by clicking the pen (edit) icon next to any row (requires a primary key).

• Insert and delete rows with dedicated buttons.

• Paginate through large datasets.

• Changes are applied to your database immediately.

  

Branch management from the panel

The Neon Local Connect panel also provides easy branch management:

• Create a new branch: Click the "Branch" dropdown, select "Create new branch...", give it a name, and choose a parent.
• Switch branches: Simply select a different branch from the dropdown. Your localhost connection will now point to the new branch no code changes needed.
• Reset a branch: Revert a branch to its parent's state to discard changes and get a clean slate. To reset a branch, right click the branch in Database schema view and select "Reset from Parent Branch".

Connect your application

Add the static connection string from the extension panel to your project's .env.local file.

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

Replace <database_name> with your actual database name

Your app now connects to localhost:5432, and Neon Local securely routes traffic to the active cloud branch.

Follow the Typical development workflow section for understanding how to leverage Neon Local effectively.

Neon Local

For non-VS Code users or CI/CD integration, you can use Neon Local directly. This gives you the same power, controlled in a programmatic way.

Neon Local is a Docker-based proxy that connects to your Neon database, allowing you to run a local instance of your cloud database. It provides a static connection string (localhost:5432) that routes to the active branch, making it easy to switch branches without changing your code.

Docker compose configuration

Here is a docker-compose.yml that defines your app and the db (Neon Local) service.

services:
  app:
    build: .
    ports:
      - '${PORT}:${PORT}'
    environment:
      - DATABASE_URL="postgres://neon:npg@db:5432/${DB_NAME}?sslmode=no-verify"
    depends_on:
      - db

  db:
    image: neondatabase/neon_local:latest
    ports:
      - '5432:5432'
    environment:
      - NEON_API_KEY=${NEON_API_KEY}
      - NEON_PROJECT_ID=${NEON_PROJECT_ID}
      # Choose one of the following:
      - BRANCH_ID=${BRANCH_ID} # For existing branches
      # - PARENT_BRANCH_ID=${PARENT_BRANCH_ID} # For ephemeral branches

Key environment variables

If you need to use the docker run command instead of Docker Compose, you can checkout Neon Local Docs for more information.

Advanced configuration

Persistent branches per Git Branch

For a workflow where a database branch's lifecycle matches a Git branch, you can configure Neon Local to persist its state.

Add volumes to your db service in docker-compose.yml:

db:
  image: neondatabase/neon_local:latest
  ports:
    - '5432:5432'
  environment:
    NEON_API_KEY: ${NEON_API_KEY}
    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
    DELETE_BRANCH: false
  volumes:
    - ./.neon_local/:/tmp/.neon_local
    - ./.git/HEAD:/tmp/.git/HEAD:ro,consistent

This configuration uses your current Git branch name to manage a persistent database branch.

Typical development workflow

Neon's branching is designed to integrate seamlessly with modern, Git-based development workflows. By pairing each Git branch with a corresponding database branch, you can ensure complete isolation, prevent conflicts, and maintain a clean production database.

Here’s a practical look at how to use Neon Local in your daily tasks.

The scenario: Starting a new task

You've just been assigned a ticket to build a new user profile page. The first step is always to create a new Git branch to isolate your code changes.

git checkout main
git pull
git checkout -b feature/new-user-profile

Now that your code is isolated, you need to isolate your database. You have two primary options depending on the scope of your task.

Option 1: Long-lived feature

When to use it: This is the standard approach for most feature work, bug fixes that require review, or any task that will span multiple sessions or involve collaboration. You create a persistent database branch that mirrors the lifecycle of your Git branch.

Option 2: Quick experiment or test

When to use it: Perfect for quick bug fixes, running a single test suite, or experimenting with a schema change that you might throw away. An ephemeral branch is created on-the-fly and automatically deleted when you're done.

Connecting your application conditionally

Your application code needs to seamlessly switch between connecting to Neon Local for development and your live Neon database for production. The standard way to manage this is by using the NODE_ENV environment variable.

The core logic is straightforward: when process.env.NODE_ENV is set to 'development', your application should use the static localhost connection string provided by Neon Local. For any other environment (such as 'production' on platforms like Vercel, AWS, or other cloud providers), your app should use the actual Neon database URL, typically stored in your deployment environment's configuration or secrets on your cloud provider.

The implementation details vary slightly depending on the database driver or ORM you are using.

Summary

You've now learned how to integrate Neon local and Neon Local Connect into your workflow. With Neon Local Connect, you get a full-featured database IDE that makes managing branches as easy as managing Git branches. For more advanced or automated setups, Neon Local with Docker provides the same powerful capabilities for any environment, ensuring you always have clean, isolated, and production-like databases for development and testing.

Resources

• Neon Local Documentation
• Neon Local Connect extension guide
• Example application using Neon Local