[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. It supports two main use cases: 1. **Connecting to existing Neon branches** - Connect your app to any existing branch in your Neon project 2. **Connecting to ephemeral Neon branches** - Connect your app to a new ephemeral database branch that is instantly created when the Neon Local container starts and deleted 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. ## Connect to existing Neon branch To connect to an existing Neon branch, provide the `BRANCH_ID` environment variable to the container. This allows you to work with a specific branch without creating a new one. ### Docker run ```bash docker run \ --name db \ -p 5432:5432 \ -e NEON_API_KEY= \ -e NEON_PROJECT_ID= \ -e BRANCH_ID= \ neondatabase/neon_local:latest ``` ### Docker Compose ```yaml db: image: neondatabase/neon_local:latest ports: - '5432:5432' environment: NEON_API_KEY: ${NEON_API_KEY} NEON_PROJECT_ID: ${NEON_PROJECT_ID} BRANCH_ID: ${BRANCH_ID} ``` ## Ephemeral database branches for development and testing To create ephemeral branches (default behavior), provide the `PARENT_BRANCH_ID` environment variable instead of `BRANCH_ID`. 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. ### Docker run ```bash docker run \ --name db \ -p 5432:5432 \ -e NEON_API_KEY= \ -e NEON_PROJECT_ID= \ -e PARENT_BRANCH_ID= \ neondatabase/neon_local:latest ``` ### Docker Compose ```yaml db: image: neondatabase/neon_local:latest ports: - '5432:5432' environment: NEON_API_KEY: ${NEON_API_KEY} NEON_PROJECT_ID: ${NEON_PROJECT_ID} PARENT_BRANCH_ID: ${PARENT_BRANCH_ID} ``` ## Docker run instructions Run the Neon Local container using the following `docker run` command: ```bash docker run \ --name db \ -p 5432:5432 \ -e NEON_API_KEY= \ -e NEON_PROJECT_ID= \ neondatabase/neon_local:latest ``` ## Docker Compose instructions Add Neon Local to your `docker-compose.yml`: ```yaml db: image: neondatabase/neon_local:latest ports: - '5432:5432' environment: NEON_API_KEY: ${NEON_API_KEY} NEON_PROJECT_ID: ${NEON_PROJECT_ID} ``` ## Multi-driver support The Neon Local container now supports both the `postgres` and Neon `serverless` drivers simultaneously through a single connection string. You no longer need to specify a driver or configure different connection strings for different drivers. ## Connecting your app (Postgres driver) Connect to Neon Local using a standard Postgres connection string. ### Docker run ```bash postgres://neon:npg@localhost:5432/?sslmode=require ``` ### Docker compose ```bash postgres://neon:npg@${db}$:5432/?sslmode=require # where {db} is the name of the Neon Local service in your compose file ``` :::callout{intent="note"} For javascript applications The Neon Local container uses an automatically generated self-signed certificate to secure communication between your app and the container. Javascript applications using the `pg`or `postgres` postgres libraries to connect to the Neon Local proxy will also need to add the following configuration to allow your app to connect using the self-signed certificate. ```bash ssl: { rejectUnauthorized: false } ``` ::: ## Connecting your app (Neon serverless driver) Connect using the Neon [serverless driver](/guides/postgres-serverless-serverless-driver). :::callout{intent="note"} The Neon Local container only supports HTTP-based communication using the Neon Serverless driver, not websockets. The following configurations will enable your app to communicate using only HTTP traffic with your Neon database. ::: ### Docker run ```javascript import { neon, neonConfig } from '@neondatabase/serverless'; neonConfig.fetchEndpoint = 'http://localhost:5432/sql'; neonConfig.useSecureWebSocket = false; neonConfig.poolQueryViaFetch = true; const sql = neon('postgres://neon:npg@localhost:5432/'); ``` ### Docker compose ```javascript import { neon, neonConfig } from '@neondatabase/serverless'; neonConfig.fetchEndpoint = 'http://{db}:5432/sql'; neonConfig.useSecureWebSocket = false; neonConfig.poolQueryViaFetch = true; const sql = neon('postgres://neon:npg@{db}:5432/'); // where {db} is the name of the Neon Local service in your compose file ``` No additional environment variables are needed - the same Docker configuration works for both drivers: ```bash docker run \ --name db \ -p 5432:5432 \ -e NEON_API_KEY= \ -e NEON_PROJECT_ID= \ neondatabase/neon_local:latest ``` ## Environment variables and configuration options | Variable | Description | Required | Default | | ------------------ | --------------------------------------------------------------------------------- | -------- | ----------------------------- | | `NEON_API_KEY` | Your Neon API key. [Manage API Keys](/guides/manage-operate-manage-api-keys) | Yes | N/A | | `NEON_PROJECT_ID` | Your Neon project ID. Found under Project Settings → General in the Neon console. | Yes | N/A | | `BRANCH_ID` | Connect to an existing Neon branch. Mutually exclusive with `PARENT_BRANCH_ID`. | No | N/A | | `PARENT_BRANCH_ID` | Create ephemeral branch from parent. Mutually exclusive with `BRANCH_ID`. | No | your project's default branch | | `DRIVER` | **Deprecated** - Both drivers now supported simultaneously. | No | N/A | | `DELETE_BRANCH` | Set to `false` to persist branches after container shutdown. | No | `true` | ## Persistent Neon branch per Git branch To persist a branch per Git branch, add the following volume mounts: ```yaml 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 ``` :::callout{intent="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. ::: ## Git integration using Docker on Mac 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. Docker Desktop are set to gRPC FUSE ## Related pages - [AI tools for Agents](./ai-agents-on-neon-index.md) - [APIs & SDKs](./apis-sdks-index.md) - [Changelog](../changelog.md) - [Integrating with Neon](./building-on-neon-index.md) - [Lakebase Postgres](./postgres-index.md) - [Managed Better Auth](./auth-index.md) - [More](./more-index.md) - [Neon AI Gateway](./ai-gateway-index.md) - [Neon community](./community-index.md) - [Neon documentation](./neon-docs-index.md) - [Neon VS Code Extension](./integrations-tooling-local-vscode-extension.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.