NeonDB
Neon is serverless Postgres — scales to zero, branches like git, instant provisioning. Perfect for AI agents needing databases without ops overhead.
Why Neon for Agents?
- - Instant databases — Create in seconds, no server setup
- Branching — Fork your database like git (test without affecting prod)
- Scale-to-zero — Pay nothing when idle
- Connection pooling — Built-in, no PgBouncer needed
- Generous free tier — 0.5 GB storage, 190 compute hours/month
Quick Start
1. Install CLI
CODEBLOCK0
2. Authenticate
CODEBLOCK1
3. Create Your First Project
CODEBLOCK2
Core Commands
Projects (top-level container)
CODEBLOCK3
Branches (database snapshots)
CODEBLOCK4
Databases
CODEBLOCK5
Connection Strings
CODEBLOCK6
Roles (database users)
CODEBLOCK7
Executing Queries
Using psql
CODEBLOCK8
Using the connection string in code
CODEBLOCK9
Context (Avoid Repeating Project ID)
Set context to avoid passing --project-id every time:
CODEBLOCK10
Agent Workflow Examples
Create org database with branches
CODEBLOCK11
Create leads table
CODEBLOCK12
Branch for experiments
CODEBLOCK13
Output Formats
CODEBLOCK14
Environment Variables
CODEBLOCK15
Common Patterns
Check if neonctl is configured
CODEBLOCK16
Quick database query
CODEBLOCK17
Export to CSV
CODEBLOCK18
Import from CSV
CODEBLOCK19
Troubleshooting
"Connection refused"
- - Check if branch compute is active (scale-to-zero may have paused it)
- Use
--pooled connection string for serverless workloads
"Permission denied"
- - Verify API key: INLINECODE2
- Re-authenticate: INLINECODE3
Slow first connection
- - Normal for scale-to-zero. First connection wakes the compute (~1-2 seconds)
- Use connection pooling to maintain warm connections
Links
NeonDB
Neon是无服务器Postgres——可缩放到零，像Git一样分支，即时配置。非常适合需要数据库且无需运维开销的AI代理。
为什么Neon适合代理？
- - 即时数据库——秒级创建，无需服务器设置
- 分支功能——像Git一样分叉数据库（测试不影响生产）
- 缩放到零——空闲时无需付费
- 连接池——内置，无需PgBouncer
- 慷慨的免费套餐——0.5 GB存储，每月190计算小时
快速开始
1. 安装CLI
bash
Homebrew（推荐）
brew install neonctl
或npm
npm i -g neonctl
2. 身份验证
bash
交互式（打开浏览器）
neonctl auth
或使用API密钥（从console.neon.tech获取）
export NEON
APIKEY=your
apikey_here
3. 创建您的第一个项目
bash
neonctl projects create --name my-agent-db
核心命令
项目（顶级容器）
bash
列出所有项目
neonctl projects list
创建项目
neonctl projects create --name project-name
删除项目
neonctl projects delete
获取项目详情
neonctl projects get
分支（数据库快照）
bash
列出分支
neonctl branches list --project-id
创建分支（从main分叉）
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
比较模式
neonctl branches schema-diff --project-id --base-branch main --compare-branch dev
数据库
bash
列出数据库
neonctl databases list --project-id --branch
创建数据库
neonctl databases create --project-id --branch --name mydb
删除数据库
neonctl databases delete --project-id --branch
连接字符串
bash
获取连接字符串（默认分支）
neonctl connection-string --project-id
获取特定分支的连接字符串
neonctl connection-string --project-id
池化连接（推荐用于无服务器）
neonctl connection-string --project-id --pooled
扩展格式（包含所有详情）
neonctl connection-string --project-id --extended
角色（数据库用户）
bash
列出角色
neonctl roles list --project-id --branch
创建角色
neonctl roles create --project-id --branch --name app_user
执行查询
使用psql
bash
获取连接字符串并连接
neonctl connection-string --project-id | xargs psql
或直接连接
psql $(neonctl connection-string --project-id )
在代码中使用连接字符串
bash
获取字符串
CONNECTION_STRING=$(neonctl connection-string --project-id --pooled)
在任何Postgres客户端中使用
psql $CONNECTION_STRING -c SELECT * FROM users LIMIT 5;
上下文（避免重复项目ID）
设置上下文以避免每次传递--project-id：
bash
设置项目上下文
neonctl set-context --project-id
现在命令自动使用该项目
neonctl branches list
neonctl databases list
neonctl connection-string
代理工作流示例
创建带分支的组织数据库
bash
为组织创建项目
neonctl projects create --name website-org-db -o json
创建生产分支（默认创建main）
创建用于测试的开发分支
neonctl branches create --name dev --project-id
获取连接字符串
neonctl connection-string main --project-id --pooled # 用于生产
neonctl connection-string dev --project-id --pooled # 用于开发
创建潜在客户表
bash
连接并创建模式
psql $(neonctl cs --project-id ) <
CREATE TABLE leads (
id SERIAL PRIMARY KEY,
business_name VARCHAR(255) NOT NULL,
category VARCHAR(100),
location VARCHAR(255),
phone VARCHAR(50),
email VARCHAR(255),
website VARCHAR(255),
status VARCHAR(50) DEFAULT identified,
priority VARCHAR(20) DEFAULT medium,
notes TEXT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idxleadsstatus ON leads(status);
CREATE INDEX idxleadscategory ON leads(category);
EOF
用于实验的分支
bash
创建分支以测试模式更改
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
输出格式
bash
JSON（用于解析）
neonctl projects list -o json
YAML
neonctl projects list -o yaml
表格（默认，人类可读）
neonctl projects list -o table
环境变量
bash
API密钥（如果未使用neonctl auth则需要）
export NEONAPIKEY=your_key
默认项目（替代set-context）
export NEONPROJECTID=yourprojectid
常见模式
检查neonctl是否已配置
bash
neonctl me -o json 2>/dev/null && echo 已验证 || echo 需要运行：neonctl auth
快速数据库查询
bash
单行查询
psql $(neonctl cs) -c SELECT COUNT(*) FROM leads WHERE status=contacted;
导出到CSV
bash
psql $(neonctl cs) -c COPY (SELECT * FROM leads) TO STDOUT WITH CSV HEADER > leads.csv
从CSV导入
bash
psql $(neonctl cs) -c \COPY leads(business_name,category,location) FROM import.csv WITH CSV HEADER
故障排除
连接被拒绝
- - 检查分支计算是否活跃（缩放到零可能已暂停）
- 对无服务器工作负载使用--pooled连接字符串
权限被拒绝
- - 验证API密钥：neonctl me
- 重新验证：neonctl auth
首次连接慢
- - 缩放到零的正常现象。首次连接唤醒计算（约1-2秒）
- 使用连接池保持热连接
链接
