Neon Postgres 是做什么的?
数据库是可选集成的(AGENTS.md §0.5):仅在应用需要存储超出浏览器会话期限或在设备间共享的数据时使用。否则,不要添加迁移,不要导入 @/lib/db,并使用 localStorage / zustand 保持状态。
此模板提供了一个现成的双模式数据库集成:
- 已配置(环境变量已设置,例如已部署):真实 Neon Postgres。
- 未配置(沙盒实时预览):数据库回退到本地 PGLite(嵌入式 WASM Postgres),因此预览始终能渲染。针对
@/lib/db辅助工具进行开发;两种模式使用相同的 API。
相关包已预安装,无需通过 npm install 安装:pg(node-postgres,常规 Postgres 驱动)和 @electric-sql/pglite(本地数据库回退)。
关于用户账户、登录和读取当前用户,请参见独立的 auth 技能——此技能仅涉及数据库。
开启数据库
在 .grok/app-env.json 中将 deploy.database 设置为 true:
{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
这将通知平台为已部署的应用配置 Neon;如果保持 false,则部署不会获得 DATABASE_URL,应用将静默运行在可丢弃的 PGLite 上,其数据在重启后丢失。如果存在 migrations/*.sql 或登录功能,则无论此标志如何都会配置数据库;此标志适用于那些查询 @/lib/db 但不包含迁移或登录的应用。它不是 VITE_ 键,也不会传递到浏览器。
环境变量——不要创建 .env 文件
永远不要为数据库编写 .env / .env.local / .env.example 文件。 在沙盒实时预览中,保持 DATABASE_URL 未设置——@/lib/db 会自动使用嵌入式 PGLite。当应用部署后,平台会注入 DATABASE_URL(Neon);您不需要自己配置或编写它。
| 变量 | 位置 | 用途 |
|---|---|---|
DATABASE_URL | 服务器 | 部署时的 Neon 连接字符串(可选——若未设置则使用 PGLite 回退) |
切勿硬编码它;切勿将非 VITE_ 的变量暴露给客户端。
数据库(仅服务器端)
@/lib/db 导出了 getSql() 和 dbSource:当设置了 DATABASE_URL 时,使用常规 Postgres 驱动(node-postgres,pg);当未设置时,使用本地 PGLite 回退。两种方式共享相同的 API——一个标签模板(以及 .query()),返回 rows[]。仅在 createServerFn 处理器或服务器加载器中调用,绝不要在客户端组件中调用。在 migrations/ 中定义模式,不要内联。
import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";
export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
const sql = await getSql();
// 指定行的类型——服务器函数的返回值必须是可证明可序列化的。
return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
// 或者:return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});
每个用户的数据(仅在应用拥有登录功能后使用)。 常规驱动具有完全数据库访问权限,因此请在服务器端将每个查询限定为已认证的用户——永远不要信任客户端发送的 ID。使用预置的 authMiddleware 来获取已验证的 context.userId,然后基于它进行过滤。完整模式(中间件、从客户端代码调用、失败即关闭语义)在 auth 技能中:
import { authMiddleware } from "@/lib/auth/middleware";
export const listTodos = createServerFn({ method: "GET" })
.middleware([authMiddleware])
.handler(async ({ context }) => {
const sql = await getSql();
return sql<{ id: number; title: string }>`select id, title from todos where user_id = ${context.userId} order by id desc`;
});
// 写入操作也必须限定作用域:`... where id = ${id} and user_id = ${context.userId}`
在没有登录功能的情况下(默认情况),不要使用 authMiddleware / requireUserId。 它们回退到的开发者用户仅是一个预览用的便利。已部署应用的 VITE_AUTH_ENABLED 由平台设置,而非此工作区设置(目前部署器始终将其设为 "true"),因此一旦部署,两者都会拒绝所有访客——而一个未启用认证的应用也没有为其提供登录路由。仅使用数据库的应用应保持其数据无归属:没有 user_id 列,或使用一个常量值。作为开启登录功能(auth 技能中的升级步骤)的一部分,请添加中间件,并在此过程中重新限定或删除这些行。
在无归属模式下,行通过您的公共服务器函数是全局可读和全局可写的:绝不要在此模式下持久化个人或敏感数据(姓名、电子邮件、关于个人的自由文本),并避免具有破坏性的批量写入操作(全部删除、全部覆盖)——如果应用需要这些操作,请建议开启登录功能。
迁移
migrations/*.sql 是唯一的模式来源。它们会应用于部署时的 Neon(npm run build 会针对 DATABASE_URL 运行 db:migrate,因此 Vercel 部署时模式已就绪)以及启动时自动应用于 PGLite 预览,因此开发环境与生产环境保持一致。
两个应用器都不会进入子目录,因此位于 migrations/auth/0001_auth.sql 的 Better Auth 模式不会被应用,除非应用开启登录功能并将其复制到上层(不要编辑它——参见 auth 技能)。将您的应用的模式放在从 0002 开始的新序号文件中:
-- migrations/0002_schema.sql —— 示例用于待办事项应用;请使用您的应用的表
create table if not exists todos (
id serial primary key,
user_id text not null,
title text not null,
done boolean not null default false,
created_at timestamptz not null default now()
);
create index if not exists todos_user_id_idx on todos (user_id);
永远不要编辑已应用的文件——它通过名称在 _migrations 表中跟踪,不会重新运行(而是添加一个新文件;新文件会在下一次请求时应用于正在运行的预览)。优先使用幂等语句(... if not exists)。包含每个用户数据的表应具有 user_id text not null 列(TEXT 类型,而非 UUID——预览开发用户 ID 是字符串 'dev-user')。
预览 ↔ 生产一致性
getSql() 会规范化结果类型,以使两个后端返回一致的、JSON 安全的形状:bigint/count(*) → number,date → 'YYYY-MM-DD' 字符串,interval → 文本,numeric → 字符串。需要尊重的其他差异:
- 超过 2^53 的
bigint作为数字会丢失精度——如果您需要极大的整数,请将其转换为::text(行计数没问题)。 - 预览数据库在内存中运行:在开发服务器重启时清除,单连接(无锁争用或并发写入冲突),并且不加载任何扩展——不要使用
create extension;坚持使用核心 Postgres。 - Neon 的池化端点不保留会话状态——不要依赖
SET、LISTEN/NOTIFY或会话级咨询锁。 - 保持
user_id列为text类型——预览使用'dev-user',生产环境使用 Better Auth 的文本 ID;uuid列会破坏预览的插入操作。 - 部署的 Neon 查询会经过网络(并且可能会冷启动恢复)——避免那些在进程内预览数据库中感觉轻松但会带来 N+1 查询性能问题的模式。