netlify-db

Netlify DB

Netlify DB 会自动配置托管的 Neon Postgres 数据库。无需 Neon 账户。

何时使用 DB，何时使用 Blobs

在以下情况下使用 Netlify DB：

• 存储结构化的关系型数据
• 数据会随时间增长
• 需要查询、筛选、联接或聚合

在以下情况下改用 Netlify Blobs：

• 存储文件（图像、文档、导出文件）
• 只有少量记录，且预计不会增长
• 只需简单的键值存储，无需关系型功能
• 希望除 @netlify/blobs 外不引入其他依赖

有关 Blobs 的用法，请参阅 netlify-blobs 技能。

设置

npm install @netlify/neon
netlify db init    # Provisions database and sets up Drizzle ORM

前提条件：已登录 Netlify CLI，并已关联站点（netlify link）。

通过 @netlify/neon 使用原始 SQL

@netlify/neon 封装了 @neondatabase/serverless。无需连接字符串——它会自动配置。

import { neon } from "@netlify/neon";
const sql = neon();

const users = await sql("SELECT * FROM users");
await sql("INSERT INTO users (name) VALUES ($1)", ["Jane"]);
await sql("UPDATE users SET name = $1 WHERE id = $2", ["Jane", 1]);
await sql("DELETE FROM users WHERE id = $1", [1]);

Drizzle ORM 集成

对于大多数项目，建议在 Netlify DB 上使用 Drizzle ORM。

drizzle.config.ts

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  dbCredentials: { url: process.env.NETLIFY_DATABASE_URL! },
  schema: "./db/schema.ts",
  out: "./migrations",
  migrations: { prefix: "timestamp" }, // Avoids conflicts across branches
});

db/index.ts

import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import * as schema from "./schema";

const sql = neon(process.env.NETLIFY_DATABASE_URL!);
export const db = drizzle(sql, { schema });
export * from "./schema";

架构示例

// db/schema.ts
import { integer, pgTable, varchar, text, boolean, timestamp } from "drizzle-orm/pg-core";

export const items = pgTable("items", {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  title: varchar({ length: 255 }).notNull(),
  description: text(),
  isActive: boolean("is_active").notNull().default(true),
  createdAt: timestamp("created_at").defaultNow(),
  updatedAt: timestamp("updated_at").defaultNow(),
});

export type Item = typeof items.$inferSelect;
export type NewItem = typeof items.$inferInsert;

查询模式

import { db, items } from "../db";
import { eq } from "drizzle-orm";

const all = await db.select().from(items);
const [one] = await db.select().from(items).where(eq(items.id, id)).limit(1);
const [created] = await db.insert(items).values({ title: "New" }).returning();
const [updated] = await db.update(items).set({ title: "Updated" }).where(eq(items.id, id)).returning();
await db.delete(items).where(eq(items.id, id));

迁移

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "netlify dev:exec drizzle-kit migrate",
    "db:push": "netlify dev:exec drizzle-kit push",
    "db:studio": "netlify dev:exec drizzle-kit studio"
  }
}

工作流：修改架构，运行 db:generate，然后运行 db:migrate。

部署预览分支

Netlify DB 支持分支：生产分支使用生产数据库，所有其他分支和部署预览使用独立的预览分支。在预览分支上开发并测试迁移，合并到 main，然后应用到生产环境。

环境变量

• NETLIFY_DATABASE_URL — Netlify 配置数据库后会自动设置
• 手动获取：netlify env:get NETLIFY_DATABASE_URL

本地开发

运行 netlify dev 或使用 @netlify/vite-plugin，即可在本地访问数据库。使用 netlify dev:exec 在正确的环境中运行迁移命令。