配置 Neon（托管 Postgres）

• 选择 Neon 的场景 — 你只需要托管 Postgres，不需要捆绑的认证或存储功能。或者你需要数据库分支（每个 Pull Request 对应一个独立数据库）。或者你希望按使用量计费（空闲数据库几乎零成本）。
• 选择 Supabase，如果你还想在同一套产品中获得认证和存储功能。
• 选择 PlanetScale，如果 MySQL 更符合你的技术栈。
• 选择 AWS RDS / Cloud SQL，如果你已深度依赖 AWS / GCP。

前往 console.neon.tech ↗ 注册。免费，支持 GitHub 或 Google OAuth。

创建项目时配置如下：

• 名称 — 随意填写。
• Postgres 版本 — 推荐选择 17（最新稳定版）。
• 区域 — 选择离你应用服务器最近的区域，支持 AWS 和 Azure。
• 数据库名称 — 默认的 neondb 即可。

配置大约需要 5 秒（这是 Neon 的技术亮点之一 — Postgres 基于写时复制从基础镜像快速启动）。

项目创建完成后，控制台会立即显示连接字符串，格式如下：

postgresql://<user>:<password>@ep-xxxxxx.region.aws.neon.tech/neondb?sslmode=require

复制它，并存入后端的环境变量：

DATABASE_URL=postgresql://user:[email protected]/neondb?sslmode=require

两种连接模式：

• 直连模式（如上所示）— 适用于长时间运行的服务器，例如有连接池的传统 Node.js 应用。
• 连接池模式 — 主机名带有 -pooler 后缀；适用于无服务器函数或边缘运行时（无法持有长连接的场景）。在 Vercel、Cloudflare Workers、AWS Lambda 等环境中使用此模式。

Neon 控制台的"Connection string"面板同时提供两种模式，根据你的运行时选择对应的连接字符串即可。

任何 Postgres 客户端库都可以使用 — 这就是标准的 Postgres。以下是两种常见模式：

传统服务器（Node + pg）：

npm install pg

import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const { rows } = await pool.query("SELECT * FROM users WHERE id = $1", [123]);

无服务器 / 边缘环境（Neon HTTP 驱动 — 无需 TCP）：

npm install @neondatabase/serverless

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL);

const users = await sql`SELECT * FROM users WHERE id = ${123}`;

HTTP 驱动可在 Cloudflare Workers、Vercel Edge Functions 及其他传统 TCP Postgres 客户端无法运行的环境中使用。Neon serverless driver 文档 ↗。

方式 A — Neon SQL 编辑器：在控制台中打开 SQL Editor，粘贴以下语句：

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  created_at TIMESTAMPTZ DEFAULT now()
);

点击运行。

方式 B — 使用你自己的 ORM：由于底层就是标准 Postgres，任何常规工具都可以使用。常见选择：

• Drizzle ORM ↗ — TypeScript 优先，开发体验出色。
• Prisma ↗ — 最流行，提供完整的 Schema 管理功能。
• Kysely ↗ — 类型安全的查询构建器。
• node-postgres (pg) ↗ — 原生 SQL，依赖最小。

按照你喜欢的方式定义 Schema，然后针对 Neon 的连接 URL 运行数据库迁移即可。

Neon 的分支功能类似 Git 分支 — 基于写时复制，可在任意时间点为数据库创建快照副本。创建分支、在其上运行迁移，如果出现问题直接丢弃即可。

在控制台中选择 Branches → Create branch，几秒内新分支即可就绪，并获得独立的连接字符串。

典型使用场景：

• 每个 Pull Request 对应一个分支。 在 CI 中针对从主分支新建的分支运行迁移，在隔离环境中验证新 Schema，PR 合并后直接删除该分支。
• 无需复制数据的 Staging 环境。 从生产环境分支 → 用作 Staging，无需导出/导入数据。
• 时光旅行调试。 从"5 分钟前"创建分支，检查某次错误迁移前数据库的状态。

分支功能文档 ↗。

Neon 不强制使用任何特定的迁移工具，随你选择：

• Drizzle Kit — drizzle-kit generate + drizzle-kit migrate，从 TypeScript Schema 生成 SQL。
• Prisma — prisma migrate dev / prisma migrate deploy。
• node-pg-migrate — 使用纯 SQL 迁移文件，依赖极少。
• Atlas — 声明式 Schema 管理，自动对比差异。atlasgo.io ↗。
• 纯 SQL 文件 — 保存在 Git 中，通过 psql 执行。

Neon 分支功能在迁移安全性方面尤为出色：先创建分支，在分支上运行迁移，验证无误后再应用到主分支。

如果你使用的是无服务器运行时（Vercel、Cloudflare Workers、AWS Lambda），请使用连接池连接字符串：

postgresql://user:[email protected]/neondb?sslmode=require

-pooler 后缀会将请求路由到 Neon 的连接池。如果不使用它，每次冷启动都会建立新连接，很快就会耗尽 Postgres 的连接上限。

注意：连接池模式不支持 Session 级别的特性（如 advisory lock、需要持久化的 SET 语句、prepared statement）。如果需要这些功能，请使用直连模式并配合自己的连接池（如 pgBouncer）。

免费套餐：保留 24 小时历史记录（可从最近一天的任意时间点创建分支）。付费套餐可将历史记录延长至 7 天、30 天或更长。

若要"从备份恢复"，只需从指定时间戳创建一个分支，然后将应用指向该分支的连接字符串即可，比传统的 dump/restore 方式更快。

通过 pg_dump 手动备份同样可行，适合归档到 S3 或冷存储，配合定时任务定期运行即可。

在控制台中打开 Monitoring，可以查看：

• 每个计算节点的 CPU 和内存
• 活跃连接数
• 数据库大小
• 存储历史（随时间写入/变更的数据量）

如需更深入的可观测性（慢查询日志、索引使用统计），可启用 pg_stat_statements ↗，并对其运行标准 Postgres 性能查询。

免费套餐：0.5 GB 存储、24 小时时间点恢复、最多 10 个项目，早期阶段完全够用。

Launch 套餐：19 美元/月 — 10 GB 存储，7 天 PITR。Pro 套餐：69 美元/月 — 50 GB 存储，30 天 PITR，支持自动弹性伸缩。Neon 定价 ↗。

超出免费额度后，计算用量单独计费；缩容到零机制可将空闲成本压至接近零。