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

See our documentation for more configuration options: Neon Local Documentation

By default, the Neon Local container automatically creates a new ephemeral branch of your database when the container starts, and deletes it when the container stops. This ensures that each time you deploy your app via Docker Compose, you have a fresh copy of your database — without needing manual cleanup or orchestration scripts. Your database branch lifecycle is tied directly to your Docker environment.

If you prefer to persist database branches across test runs, you can disable automatic branch deletion and mount your project's Git metadata into the container. Neon Local will automatically create a new Neon database branch corresponding to each Git branch you work on.

Using the Neon Local container in your CI pipeline allows you to instantly create and connect to fresh copies of your staging or test database with a simple docker compose up command — no additional automation (like GitHub Actions) required.

Run the Neon Local container using the following docker run command:

docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  neondatabase/neon_local:latest

Add Neon Local to your 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}

The Neon Local container supports both the postgres and Neon serverless drivers.
If no driver is configured, postgres is used by default.

Set the driver using the DRIVER environment variable:

• postgres
• serverless

Connect to Neon Local using a standard Postgres connection string.

postgres://neon:npg@localhost:5432/<database_name>?sslmode=no-verify

postgres://neon:npg@db:5432/<database_name>?sslmode=no-verify

Connect using the Neon serverless driver.

import { neon, neonConfig } from '@neondatabase/serverless';
neonConfig.fetchEndpoint = 'http://localhost:5432/sql';

const sql = neon('postgres://neon:npg@localhost:5432/<database_name>');

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

const sql = neon('postgres://neon:npg@db:5432/<database_name>');

When using the serverless driver, set DRIVER=serverless:

docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  -e DRIVER=serverless \
  neondatabase/neon_local:latest

Or in Compose:

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

To persist a branch per Git branch, add the following volume mounts:

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

Note: This will create a .neon_local directory in your project to store metadata. Be sure to add .neon_local/ to your .gitignore to avoid committing database information.

If using Docker Desktop for Mac, ensure that your VM settings use gRPC FUSE instead of VirtioFS.
There is currently a known bug with VirtioFS that prevents proper branch detection and live updates inside containers.