跳到正文
Drizzle

框架集成

在 Next.js、SvelteKit、Remix、Astro、Nuxt、Expo 与 tRPC 中接入 Drizzle:初始化位置、查询示例与各自的坑。

Drizzle 与框架无关:核心模式都是在服务端模块里创建一次 db 实例,到处复用。下面按框架给出初始化位置、一个可运行查询与最容易踩的坑。示例统一假设有 users 表与 schema 定义,驱动选择见连接管理。

Next.js

初始化放在 lib/db.ts(服务端专用模块)。Route Handler 与 Server Action 都直接 import:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client, { schema });
import { db } from '@/lib/db';
import { users } from '@/lib/schema';

export async function GET() {
  const rows = await db.select().from(users).limit(50);
  return Response.json(rows);
}
'use server';
import { db } from '@/lib/db';
import { users } from '@/lib/schema';

export async function createUser(name: string) {
  await db.insert(users).values({ name });
}

坑:Edge Runtime 驱动选择

postgres-js / node-postgres 依赖 TCP,只能在 Node.js runtime 使用。Route Handler 声明 export const runtime = 'edge' 时要换 HTTP 驱动(如 drizzle-orm/neon-http、drizzle-orm/vercel-postgres)。另外开发环境热更新会重复创建连接,建议把 client 挂到 globalThis 缓存。

SvelteKit

初始化放在 $lib/server/db.ts——$lib/server/ 目录保证不会被打包进客户端:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import { DATABASE_URL } from '$env/static/private';

const client = postgres(DATABASE_URL);
export const db = drizzle(client);
import { db } from '$lib/server/db';
import { users } from '$lib/server/schema';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async () => {
  return { users: await db.select().from(users).limit(50) };
};

页面里用 data.users 渲染;写入放在 +page.server.ts 的 actions 或 +server.ts 端点。

坑:只在服务端文件里用 db

+page.ts( universal load)与组件运行在浏览器,import 服务端 db 会报错或泄漏凭据。数据库访问只放 +page.server.ts、+server.ts、+layout.server.ts 与 $lib/server/。

Remix / React Router

初始化放在 app/db.server.ts——.server.ts 后缀让 Remix 保证该模块只在服务端加载:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
import { useLoaderData, Form } from 'react-router';
import { db } from '~/db.server';
import { users } from '~/schema.server';
import type { Route } from './+types/users';

export async function loader() {
  return { users: await db.select().from(users).limit(50) };
}

export async function action({ request }: Route.ActionArgs) {
  const form = await request.formData();
  await db.insert(users).values({ name: String(form.get('name')) });
  return { ok: true };
}

export default function Users() {
  const { users } = useLoaderData<typeof loader>();
  return (
    <div>
      <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
      <Form method="post"><input name="name" /><button>添加</button></Form>
    </div>
  );
}

坑:模块后缀与部署目标

忘记 .server 后缀会把数据库代码打进客户端 bundle。部署到 Cloudflare Workers 等 edge 环境时同样要换 HTTP 驱动(D1 用 drizzle-orm/d1)。

Astro

初始化放在 src/db.ts。静态页面在构建时查询;API endpoint 与 SSR 页面在请求时查询:

import type { APIRoute } from 'astro';
import { db } from '../../db';
import { users } from '../../schema';

// 需要运行时数据时关闭预渲染(配合 SSR adapter)
export const prerender = false;

export const GET: APIRoute = async () => {
  const rows = await db.select().from(users).limit(50);
  return new Response(JSON.stringify(rows), {
    headers: { 'content-type': 'application/json' },
  });
};

.astro 页面的 frontmatter 里同样可以直接 await db.select()...,把结果渲染进模板。

坑:静态与 SSR 的边界

纯静态输出(本站模式)下 frontmatter 的查询发生在构建时,数据不会随请求更新;需要运行时数据要启用 SSR adapter 并设 export const prerender = false。endpoint 里不要复用构建时的连接假设,serverless 部署优先 HTTP 驱动。

Nuxt

初始化放在 server/utils/db.ts(Nitro 自动 import),API 放 server/api/ 或 server/routes/:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
import { db } from '../utils/db';
import { users } from '../utils/schema';

export default defineEventHandler(async () => {
  return await db.select().from(users).limit(50);
});

组件里 const { data } = await useFetch('/api/users') 消费。

坑:db 只属于 Nitro 服务端

不要在 Vue 组件或 composables/(客户端会执行)里 import db;数据库凭据用 runtimeConfig 注入而非硬编码。部署到 edge preset 时换对应 HTTP 驱动。

Expo / React Native

移动端用本地 SQLite:expo-sqlite 打开数据库文件,drizzle-orm/expo-sqlite 包装,迁移用内置 migrator hook:

import { Text } from 'react-native';
import { Stack } from 'expo-router';
import { drizzle } from 'drizzle-orm/expo-sqlite';
import { openDatabaseSync } from 'expo-sqlite';
import { useMigrations } from 'drizzle-orm/expo-sqlite/migrator';
import migrations from '../drizzle/migrations';

const expoDb = openDatabaseSync('app.db');
export const db = drizzle(expoDb);

export default function Layout() {
  const { success, error } = useMigrations(db, migrations);
  if (error) return <Text>迁移失败:{error.message}</Text>;
  if (!success) return <Text>迁移中…</Text>;
  return <Stack />;
}
// 任意组件中同步查询本地库
const rows = db.select().from(users).all();

迁移文件由 drizzle-kit generate 产出、经 metro 配置打包进应用,完整流程见 SQLite 驱动与迁移。

坑:本地库不是远程库

Expo SQLite 是设备上的文件,没有网络与并发服务端语义;需要云同步时用 Turso/libSQL 的 embedded replicas 方案。expo-sqlite 需要 development build,Expo Go 里不可用。

tRPC

在 router 的 procedure 里直接用 db,输入用 zod 校验(schema 复用见 zod 集成):

import { z } from 'zod';
import { eq } from 'drizzle-orm';
import { initTRPC } from '@trpc/server';
import { db } from '../db';
import { users } from '../schema';

const t = initTRPC.create();

export const usersRouter = t.router({
  list: t.procedure
    .input(z.object({ limit: z.number().int().min(1).max(100).default(20) }))
    .query(async ({ input }) => {
      return await db.select().from(users).limit(input.limit);
    }),
  create: t.procedure
    .input(z.object({ name: z.string().min(1) }))
    .mutation(async ({ input }) => {
      const [row] = await db.insert(users).values(input).returning();
      return row;
    }),
});

坑:把校验放在边界

tRPC 的 input 校验只保证形状,业务约束(唯一性、外键)仍要靠数据库约束兜底;context 里按请求创建 db 时注意连接池复用,不要每个 procedure 新建连接。

通用清单

  • db 实例模块级单例,凭据走环境变量,绝不进客户端 bundle。
  • serverless / edge 选 HTTP 驱动,长驻 Node 服务选 TCP 驱动 + 连接池。
  • 迁移统一走 Drizzle Kit,见 Drizzle Kit 与迁移。