Next.js + Postgres + Drizzle 起步模板实战：用 postgres-drizzle 快速搭建数据驱动应用

Next.js Postgres Drizzle 起步模板实战用 postgres-drizzle 快速搭建数据驱动应用【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples本篇文章围绕当前仓库中的storage/postgres-drizzle模板展开系统讲解如何将一个以Postgres 为数据库、Drizzle 为 ORM的 Next.js 应用从零跑起来并深入其源码剖析数据库连接、表结构定义、自动建表与种子数据、服务端数据读取、客户端刷新等核心链路。读完本文你将掌握这套模板的完整运行机制并能在自己的 Next.js 项目中复用同样的数据接入模式。模板概览什么是 postgres-drizzlestorage/postgres-drizzle是一个简洁的 Next.js 起步模板核心定位是用 Postgres 数据库 Drizzle可以看到它的技术选型framework: Next.jsuseCase: Starter起步模板css: Tailwinddatabase: PostgresrelatedTemplates: postgres-starter、postgres-prisma、postgres-kysely同系列其他 ORM 对照模板在功能上模板实现了最近用户列表演示页面从 Postgres 读取profiles表中的用户数据并渲染同时在 storage/postgres-drizzle/package.json 中可以看到完整的依赖组合drizzle-ormdrizzle-kitORM 运行时与迁移工具postgrespostgres-js 驱动Drizzle 底层使用的数据库客户端nextreactreact-domApp Router 模式tailwindcss页面样式ms用于时间差格式化快速开始两种使用方式README 给出了两条上手路径任选其一即可。方式一一键部署One-Click Deploy通过 frontmatter 中的deployUrl可以在 Vercel 控制台以一键克隆方式把模板部署上线。该方式会自动创建项目、关联 Git 仓库并完成构建配置适合只想快速看到运行效果、或者直接以该模板为起点开始迭代的场景。方式二本地克隆并启动使用create-next-app以该模板为蓝本初始化项目。--example参数既支持指向远端仓库路径也支持指向本地目录例如指向本仓库中的模板目录pnpm create next-app --example /path/to/storage/postgres-drizzle初始化完成后进入项目目录并安装依赖该模板使用 pnpm 管理依赖仓库内包含 storage/postgres-drizzle/pnpm-lock.yaml然后启动开发服务器pnpm dev启动后访问本地开发地址即可看到Recent Users示例页面。pnpm dev对应 package.json 中的next dev脚本同文件还提供了pnpm buildnext build、pnpm startnext start、pnpm lintnext lint等标准脚本用于生产构建、启动与代码检查。环境变量POSTGRES_URL模板通过环境变量POSTGRES_URL读取数据库连接串这是连接 Postgres 的唯一入口。在 storage/postgres-drizzle/lib/drizzle.ts 和 storage/postgres-drizzle/lib/seed.ts 中都有如下关键行const sql postgres(process.env.POSTGRES_URL!, { ssl: require })其中process.env.POSTGRES_URL!非空断言声明该环境变量必须在运行时存在{ ssl: require }强制以 SSL 方式连接数据库。对于 Vercel Postgres 等托管数据库这是默认要求的安全策略postgres(...)来自 postgres-js 驱动返回一个可直接执行标签模板 SQL 的客户端实例。本地开发时需要在.env.local文件中配置POSTGRES_URLpostgres://user:passwordhost:port/database?sslmoderequire数据库连接与表结构定义lib/drizzle.ts模板把连接与表结构统一收敛在 storage/postgres-drizzle/lib/drizzle.ts 中这是整个数据层的核心文件职责可以拆解为三部分。1. 定义 profiles 表使用 Drizzle 的pgTable定义一张名为profiles的表export const UsersTable pgTable( profiles, { id: serial(id).primaryKey(), name: text(name).notNull(), email: text(email).notNull(), image: text(image).notNull(), createdAt: timestamp(createdAt).defaultNow().notNull(), }, (users) { return { uniqueIdx: uniqueIndex(unique_idx).on(users.email), } } )各列说明列名Drizzle 类型约束含义idserial主键自增整数 IDnametextnotNull用户昵称emailtextnotNull邮箱配合唯一索引imagetextnotNull头像图片地址createdAttimestampdefaultNow().notNull()创建时间默认取当前时间第三个参数是表级配置回调这里通过uniqueIndex(unique_idx).on(users.email)为email列建立了唯一索引unique_idx防止重复邮箱数据。2. 导出类型基于表定义自动推导出入参/出参类型便于服务端组件获得完整的类型提示export type User InferSelectModeltypeof UsersTable export type NewUser InferInsertModeltypeof UsersTableUser查询返回的行类型NewUser插入数据所需的类型。3. 创建 db 实例export const db drizzle(sql)drizzle(sql)将 postgres-js 客户端包装为 Drizzle 查询构建器实例后续所有查询如db.select().from(UsersTable)都通过它发起。初始化建表与种子数据lib/seed.tsstorage/postgres-drizzle/lib/seed.ts 负责建表与写入演示数据全部使用 postgres-js 的标签模板 SQL未依赖 Drizzle 的 schema API适合在表不存在时直接执行 DDL。建表语句CREATE TABLE IF NOT EXISTS profiles ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, email VARCHAR(255) UNIQUE NOT NULL, image VARCHAR(255), createdAt TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP );注意createdAt使用了双引号包裹以精确匹配 Drizzle 定义中的驼峰列名Postgres 会把未加引号的标识符折叠为小写。UNIQUE约束与 drizzle.ts 中的unique_idx唯一索引在语义上保持一致。种子数据插入随后并发插入三条演示用户记录使用ON CONFLICT (email) DO NOTHING保证幂等——重复执行 seed 不会产生重复数据INSERT INTO profiles (name, email, image) VALUES (Guillermo Rauch, rauchgvercel.com, ...) ON CONFLICT (email) DO NOTHING;seed()函数执行完成后返回{ createTable, insertedUsers }便于调用方确认建表与插入结果。由于头像图片托管在images.ctfassets.net域storage/postgres-drizzle/next.config.js 中为next/image显式放行了该图片域const nextConfig { images: { domains: [images.ctfassets.net], }, }服务端读取数据与自动初始化components/table.tsxstorage/postgres-drizzle/components/table.tsx 是一个异步服务端组件展示了查询即渲染的 App Router 数据模式其关键逻辑如下。查询与兜底建表首次访问时profiles表可能尚未创建组件通过 try/catch 捕获 Drizzle 查询抛出的错误并判断错误信息users await db.select().from(UsersTable) } catch (e: any) { if (e.message relation profiles does not exist) { await seed() users await db.select().from(UsersTable) } else { throw e } }这是一个很实用的容错模式表不存在时自动执行seed()建表并填充演示数据然后重新查询让模板在拿到POSTGRES_URL后无需任何额外初始化步骤即可直接运行。渲染与性能反馈组件渲染Recent Users卡片展示Fetched {users.length} users in {duration}ms通过记录查询前后的Date.now()差值给出单次查询耗时每条用户记录渲染头像、姓名、邮箱并用timeAgo(user.createdAt)展示注册的相对时间。timeAgo工具位于 storage/postgres-drizzle/lib/utils.ts内部基于ms库计算时间差并格式化为 3 hours ago 之类的可读文本。页面级配合storage/postgres-drizzle/app/page.tsx 声明了export const dynamic force-dynamic强制每次请求都走服务端渲染确保展示的数据始终是最新从数据库读取的页面用 React 的Suspense fallback{TablePlaceholder /}包裹Table /在数据库查询完成前显示骨架屏storage/postgres-drizzle/components/table-placeholder.tsx 是纯展示的加载占位组件用animate-pulse实现骨架动画。客户端数据刷新components/refresh-button.tsxstorage/postgres-drizzle/components/refresh-button.tsx 是模板中唯一的客户端组件演示了如何在不重载页面的前提下刷新服务端数据use client const router useRouter() const [isPending, startTransition] useTransition() onClick{() { startTransition(() { router.refresh() }) }}router.refresh()会重新请求当前路由的 RSC 数据流从而重新执行Table组件里的数据库查询useTransition让刷新过程不阻塞 UI按钮在 pending 状态显示 Refreshing... 并禁用点击。布局与元数据app/layout.tsxstorage/postgres-drizzle/app/layout.tsx 定义了根布局引入globals.css与 Inter 字体并导出metadata标题为 Postgres Demo with Drizzle、含页面描述与metadataBase供搜索引擎与社交分享使用。生产部署模板面向 Vercel 平台设计frontmatter 中同时提供了deployUrl一键部署入口与demoUrl在线演示。生产部署流程与常规 Next.js 应用一致把项目推送到 Git 仓库并在 Vercel 导入在项目环境变量中配置POSTGRES_URL可在 Vercel 控制台直接创建 Postgres 数据库并自动注入连接串执行pnpm buildnext build完成生产构建访问分配到的正式域名即可。由于表不存在时会自动执行seed()建表首次访问生产环境页面即可完成数据库初始化无需手工执行迁移命令如果后续业务需要演进表结构则建议引入drizzle-kit的迁移能力模板依赖中已包含drizzle-kit来管理 schema 变更。从模板到业务可以借鉴的四个模式阅读完源码这套模板实际上浓缩了四个可复用的工程模式适合直接迁移到自己的 Next.js 项目中单一数据入口连接、schema、类型、db 实例统一收敛在lib/drizzle.ts业务代码只需import { db, UsersTable }幂等初始化seed()用CREATE TABLE IF NOT EXISTSON CONFLICT DO NOTHING保证重复执行安全服务端直查数据库异步服务端组件中直接await db.select()配合force-dynamic与Suspense获得查询即渲染 骨架屏体验RSC 局部刷新客户端组件通过router.refresh()useTransition实现不丢滚动位置、不重载页面的数据更新。与同目录下的 storage/postgres-starter、storage/postgres-kysely 等模板对照使用可以在同一套 Next.js 数据接入框架下横向比较 Drizzle 与其他数据访问层的写法差异帮助你在真实项目中做出更合适的技术选型。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考