neondatabase/neon_local

Neon Local

什么是Neon Local？

Neon Local是一个代理服务，为Neon云数据库创建本地接口。它支持两个主要用例：

1. 连接现有Neon分支 - 将应用连接到Neon项目中的任何现有分支
2. 连接临时Neon分支 - 容器启动时自动创建新的临时数据库分支，容器停止时自动删除，应用连接此临时分支

您的应用连接到本地Postgres端点，而Neon Local负责路由和认证到正确的项目和分支。这消除了在不同数据库分支间工作时更新连接字符串的需求。

更多配置选项请参见文档：Neon Local文档

连接现有Neon分支

要连接现有Neon分支，需向容器提供BRANCH_ID环境变量。这允许您使用特定分支而无需创建新分支。

Docker运行

shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<您的_neon_api_key> \
  -e NEON_PROJECT_ID=<您的_neon_project_id> \
  -e BRANCH_ID=<您的_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}

用于开发和测试的临时数据库分支

要创建临时分支（默认行为），提供PARENT_BRANCH_ID环境变量而非BRANCH_ID。Neon Local容器在启动时自动创建数据库的新临时分支，停止时自动删除。这确保每次通过Docker Compose部署应用时都有一个全新的数据库副本，无需手动清理或编排脚本。数据库分支生命周期直接与Docker环境绑定。

Docker运行

shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<您的_neon_api_key> \
  -e NEON_PROJECT_ID=<您的_neon_project_id> \
  -e PARENT_BRANCH_ID=<父_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}

用于开发和测试的每个Git分支的持久数据库

如果希望跨测试运行保留临时数据库分支，可以禁用自动分支删除并将项目的Git元数据挂载到容器中。Neon Local会自动为您工作的每个Git分支创建对应的Neon数据库分支。

在CI pipeline中使用Neon Local容器，只需执行docker compose up命令即可立即创建并连接到全新的 staging 或测试数据库副本，无需额外自动化（如GitHub Actions）。

Docker运行说明

使用以下docker run命令运行Neon Local容器：

shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<您的_neon_api_key> \
  -e NEON_PROJECT_ID=<您的_neon_project_id> \
  neondatabase/neon_local:latest

Docker Compose说明

将Neon Local添加到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}

多驱动支持

Neon Local容器支持postgres和Neon serverless驱动。
如果未配置驱动，默认使用postgres。

通过DRIVER环境变量设置驱动：

• postgres
• serverless

连接应用（Postgres驱动）

使用标准Postgres连接字符串连接Neon Local。

Docker运行

shell
postgres://neon:npg@localhost:5432/<数据库名称>?sslmode=no-verify

Docker Compose

shell
postgres://neon:npg@db:5432/<数据库名称>?sslmode=no-verify

连接应用（Neon无服务器驱动）

使用Neon 无服务器驱动连接。

Docker运行

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

const sql = neon('postgres://neon:npg@localhost:5432/<数据库名称>');

Docker Compose

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

const sql = neon('postgres://neon:npg@db:5432/<数据库名称>');

使用无服务器驱动时，设置DRIVER=serverless：

shell
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

或在Compose中：

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

环境变量和配置选项

每个Git分支的持久Neon分支

要为每个Git分支保留一个分支，添加以下卷挂载：

yaml
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

注意：这将在项目中创建.neon_local目录以存储元数据。
请务必将.neon_local/添加到.gitignore中，避免提交数据库信息。

在Mac上使用Docker的Git集成

如果使用Mac版Docker Desktop，请确保VM设置使用gRPC FUSE而非VirtioFS。
目前VirtioFS存在已知bug，会阻止容器内正确的分支检测和实时更新。

!https://raw.githubusercontent.com/neondatabase-labs/neon_local/refs/heads/main/img/disc.png