Neon Local is a proxy service that creates a local interface to your Neon cloud database. By default, it automatically creates a new database branch when the container starts and deletes it when the container stops.

Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.

Docker compose instructions

You can add the Neon Local by adding the following to your docker-compose.yml file.

Neon serverless driver
node-postgres
db:
    image: neondatabase/neon_local:latest
    ports:
      - '5432:5432'
    environment:
      NEON_API_KEY: ${NEON_API_KEY}
      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
      DRIVER: serverless

Docker run instructions

You can also run the Neon Local container with the following Docker run command.

Neon serverless driver
node-postgres
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY= <neon_api_key> \
  -e NEON_PROJECT_ID=<neon_project_id> \
  -e DRIVER=serverless \
  neondatabase/neon_local:latest

Connect

Connect using either the Neon serverless driver or any other Postgres client.

Neon serverless driver
node-postgres
import { neon, neonConfig } from '@neondatabase/serverless';
neonConfig.fetchEndpoint = 'http://db:5432/sql';

const sql = neon('postgres://neon:npg@db:5432/neondb');

Configuration options

KeyConfigurationRequiredDefault
NEON_API_KEYGenerate a Neon API key by following instructions at: Manage API KeysYesn/a
NEON_PROJECT_IDYour project ID, found in the Neon console under Settings > GeneralYesn/a
DRIVERThe type of database driver. Options: serverless or postgresNopostgres
PARENT_BRANCH_IDThe parent branch to use when creating a local child branch.Nomain
DELETE_BRANCHWhether to delete the branch when the container stops. Options: true or falseNotrue

Persistent Neon Branch per Git Branch

If you want Neon Local to create a branch that matches your Git branch, provide two volume mounts:

  1. A mount that persists Neon branch metadata within your project
  2. A mount that exposes the current Git branch name

note

This will automatically create a .neon_local folder in your project to store branch metadata. Be sure to add this folder to your .gitignore to avoid committing database connection information to version control.

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

Git integration using Docker on Mac

If using Docker Desktop for Mac, make sure that your Virtual Machine is set to use gRPC FUSE, not VirtioFS. This allows Neon Local to detect git branch changes. There is currently a bug with VirtioFS that can prevent containers from being properly updated when local files change while the container is running.

Docker Desktop are set to gRPC FUSE