NeonDB

Neon 是无服务器 Postgres —— 可缩容至零、支持类似 Git 的分支机制、实例秒级创建。非常适合需要数据库能力但又不想承担运维负担的 AI 智能体（AI agents）。

为何为智能体选择 Neon？

• 即时数据库 —— 秒级创建，无需配置服务器
• 分支功能 —— 像 Git 一样 Fork 数据库（测试时不影响生产环境）
• 缩容至零（Scale-to-zero） —— 空闲时零费用
• 内置连接池 —— 无需额外部署 PgBouncer
• 宽裕的免费套餐 —— 0.5 GB 存储空间，每月 190 计算小时

快速开始

1. 安装 CLI

# Homebrew（推荐）
brew install neonctl

# 或使用 npm
npm i -g neonctl

2. 认证登录

# 交互式登录（自动打开浏览器）
neonctl auth

# 或使用 API 密钥登录（密钥可从 console.neon.tech 获取）
export NEON_API_KEY=your_api_key_here

3. 创建首个项目

neonctl projects create --name "my-agent-db"

核心命令

Projects（顶层容器）

# 列出所有项目
neonctl projects list

# 创建项目
neonctl projects create --name "project-name"

# 删除项目
neonctl projects delete 

# 获取项目详情
neonctl projects get 

Branches（数据库快照）

# 列出分支
neonctl branches list --project-id 

# 创建分支（从 main 分支 Fork）
neonctl branches create --project-id  --name "dev-branch"

# 从指定时间点创建分支
neonctl branches create --project-id  --name "restore-test" --parent main --timestamp "2024-01-15T10:00:00Z"

# 将分支重置为其父分支
neonctl branches reset  --project-id  --parent

# 删除分支
neonctl branches delete  --project-id 

# 对比两个分支的 Schema 差异
neonctl branches schema-diff --project-id  --base-branch main --compare-branch dev

Databases

# 列出数据库
neonctl databases list --project-id  --branch 

# 创建数据库
neonctl databases create --project-id  --branch  --name "mydb"

# 删除数据库
neonctl databases delete  --project-id  --branch 

Connection Strings

# 获取连接字符串（默认分支）
neonctl connection-string --project-id 

# 获取指定分支的连接字符串
neonctl connection-string  --project-id 

# 使用连接池的连接字符串（推荐用于无服务器场景）
neonctl connection-string --project-id  --pooled

# 扩展格式（包含全部字段信息）
neonctl connection-string --project-id  --extended

Roles（数据库用户）

# 列出角色
neonctl roles list --project-id  --branch 

# 创建角色
neonctl roles create --project-id  --branch  --name "app_user"

执行查询

使用 psql

# 获取连接字符串并直接连接
neonctl connection-string --project-id  | xargs psql

# 或直接嵌入调用
psql "$(neonctl connection-string --project-id )"

在代码中使用连接字符串

# 获取连接字符串
CONNECTION_STRING=$(neonctl connection-string --project-id  --pooled)

# 在任意 Postgres 客户端中使用
psql "$CONNECTION_STRING" -c "SELECT * FROM users LIMIT 5;"

上下文设置（避免重复输入 Project ID）

设置上下文后，后续命令将自动使用该 project，无需每次指定 --project-id：

# 设置项目上下文
neonctl set-context --project-id 

# 此后命令将自动使用该 project
neonctl branches list
neonctl databases list
neonctl connection-string

智能体工作流示例

为组织创建带分支的数据库

# 为组织创建项目
neonctl projects create --name "website-org-db" -o json

# 创建生产分支（main 默认已存在）
# 创建用于测试的 dev 分支
neonctl branches create --name "dev" --project-id 

# 获取连接字符串
neonctl connection-string main --project-id  --pooled  # 用于生产环境
neonctl connection-string dev --project-id  --pooled   # 用于开发环境

创建 leads 表

# 连接并创建表结构
psql "$(neonctl cs --project-id )" <
为实验创建分支
# 创建分支用于测试 Schema 变更
neonctl branches create --name "schema-experiment" --project-id 

# 在该分支上测试变更
psql "$(neonctl cs schema-experiment --project-id )" -c "ALTER TABLE leads ADD COLUMN score INT;"

# 若变更成功，则合并至 main；否则直接删除该分支
neonctl branches delete schema-experiment --project-id 

输出格式
# JSON 格式（便于程序解析）
neonctl projects list -o json

# YAML 格式
neonctl projects list -o yaml

# 表格格式（默认，适合人工阅读）
neonctl projects list -o table

环境变量
# API 密钥（若未使用 `neonctl auth` 登录，则必须设置）
export NEON_API_KEY=your_key

# 默认项目 ID（可作为 set-context 的替代方案）
export NEON_PROJECT_ID=your_project_id

常用模式
检查 neonctl 是否已正确配置
neonctl me -o json 2>/dev/null && echo "Authenticated" || echo "Need to run: neonctl auth"

快速执行数据库查询
# 单行查询语句
psql "$(neonctl cs)" -c "SELECT COUNT(*) FROM leads WHERE status='contacted';"

导出为 CSV
psql "$(neonctl cs)" -c "COPY (SELECT * FROM leads) TO STDOUT WITH CSV HEADER" > leads.csv

从 CSV 导入数据
psql "$(neonctl cs)" -c "COPY leads(business_name,category,location) FROM 'import.csv' WITH CSV HEADER"

故障排查
"Connection refused"

检查分支的计算资源是否处于活跃状态（scale-to-zero 可能已暂停）
无服务器工作负载请使用 --pooled 连接字符串

"Permission denied"

验证 API 密钥：运行 neonctl me
重新认证：运行 neonctl auth

首次连接较慢

属于 scale-to-zero 的正常现象；首次连接会唤醒计算资源（约 1–2 秒）
建议启用连接池以维持“热”连接

相关链接

Neon Console — Web 控制台
API Docs — REST API 文档
CLI Reference — CLI 完整文档
GitHub — CLI 源码仓库