Keep a stable local connection while switching Neon branches
Local development
Neon · Const
Neon Local
Neon Local is a Docker proxy that exposes a local Postgres endpoint for a Neon cloud branch. It can target an existing branch or create and clean up an ephemeral branch automatically.
How it works
Neon Local runs as a Docker proxy between a local Postgres endpoint and a Neon cloud database. It authenticates and routes requests to either an existing branch identified by BRANCH_ID or a temporary branch based on PARENT_BRANCH_ID, keeping the application's connection endpoint unchanged when branches change.
Syntax
docker run --rm -p 5432:5432 -e NEON_API_KEY=$NEON_API_KEY -e NEON_PROJECT_ID=$NEON_PROJECT_ID -e PARENT_BRANCH_ID=$PARENT_BRANCH_ID neonlocal/neon-localParameters
| Name | Type | Description |
|---|---|---|
PARENT_BRANCH_ID | environment variable | Branch used as the basis for an automatically created ephemeral branch. |
BRANCH_ID | environment variable | Existing Neon branch to which the proxy routes connections. |
DELETE_BRANCH | environment variable | Controls whether an automatically created branch is removed when the container stops. |
DRIVER | environment variable | Selects the database client mode used by the container. |
Returns
A local Postgres endpoint that routes connections to the selected Neon branch.
Key points
- It provides a local interface for applications that need to access a Neon cloud database through Docker.
- The application connects locally; Neon Local performs cloud routing and authentication.
- Use PARENT_BRANCH_ID for the default temporary-branch workflow, rather than specifying an existing branch directly.
- Branch changes do not require rewriting the application’s database connection string.
- A single connection string can serve applications using either supported Postgres client style.
Example: Start Neon Local with an ephemeral branch
docker run --rm -p 5432:5432 -e NEON_API_KEY=$NEON_API_KEY -e NEON_PROJECT_ID=$NEON_PROJECT_ID -e PARENT_BRANCH_ID=br-main neonlocal/neon-localRun the proxy locally; the application can connect through the exposed Postgres endpoint while the container manages an ephemeral branch.
When to use it
Create isolated ephemeral database branches for test runs
Automated testing
Use standard Postgres or Neon serverless clients through the same proxy
Client compatibility
Interview questions
QWhat problem does Neon Local solve?
Neon Local is a Docker proxy that exposes a local Postgres endpoint and routes traffic to a Neon branch. The application uses the local endpoint while Neon Local manages authentication and branch routing.
Follow-up: How can it target a specific existing branch? Set BRANCH_ID to the desired branch identifier instead of using the ephemeral-branch configuration.
QHow does ephemeral-branch mode work?
Set PARENT_BRANCH_ID to choose the source branch for an automatically created ephemeral branch. The branch is created when the container starts and removed when the container stops by default.
Follow-up: How would you retain that branch? Configure DELETE_BRANCH=false so shutdown does not delete it.
QWhich database clients can use Neon Local?
Neon Local supports both the standard postgres driver and Neon’s serverless driver through one Docker configuration. This lets applications use either client while connecting through the same local endpoint.
Follow-up: What remains stable when switching branches? The application’s local connection string does not need to change.
Related
Neon serverless driverpostgres driverDockerephemeral branchesBRANCH_IDPARENT_BRANCH_IDDELETE_BRANCH