数据库

Nitro 提供了一个内置的轻量级 SQL 数据库层。

默认数据库连接已通过 SQLite 预配置，可在开发模式和任何兼容 Node.js 的生产部署中开箱即用。默认情况下，数据将存储在 .data/db.sqlite 中。

用法

server.ts

import { defineHandler } from "nitro";
import { useDatabase } from "nitro/database";

export default defineHandler(async () => {
  const db = useDatabase();

  // 创建用户表
  await db.sql`DROP TABLE IF EXISTS users`;
  await db.sql`CREATE TABLE IF NOT EXISTS users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;

  // 添加新用户
  const userId = String(Math.round(Math.random() * 10_000));
  await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;

  // 查询用户
  const { rows } = await db.sql`SELECT * FROM users WHERE id = ${userId}`;

  return {
    rows,
  };
});

`useDatabase`

使用 useDatabase 获取数据库实例。它接受一个可选的连接名称（默认为 "default"）。

import { useDatabase } from "nitro/database";

// 使用默认连接
const db = useDatabase();

// 使用命名连接
const usersDb = useDatabase("users");

当启用 experimental.database 时，useDatabase 会被自动导入，无需显式 import 语句即可使用。

数据库实例在首次使用时惰性创建，并在后续使用相同连接名称的调用中缓存。如果未配置连接名称，将抛出错误。

`db.sql`

使用带标签的模板字面量和自动参数绑定执行 SQL 查询：

const db = useDatabase();

// 使用参数化值插入（防止 SQL 注入）
const id = "1001";
await db.sql`INSERT INTO users VALUES (${id}, 'John', 'Doe', 'john@example.com')`;

// 使用参数查询
const { rows } = await db.sql`SELECT * FROM users WHERE id = ${id}`;

// 结果包含行、变更计数和最后插入的 ID
const result = await db.sql`INSERT INTO posts (title) VALUES (${"Hello"})`;
// result.rows, result.changes, result.lastInsertRowid

`db.exec`

直接执行原始 SQL 字符串：

const db = useDatabase();

await db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");

`db.prepare`

准备 SQL 语句以供重复执行：

const db = useDatabase();

const stmt = db.prepare("SELECT * FROM users WHERE id = ?");
const result = await stmt.bind("1001").all();

配置

你可以使用 database 配置来配置数据库连接：

nitro.config.ts

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  database: {
    default: {
      connector: "sqlite",
      options: { name: "db" }
    },
    users: {
      connector: "postgresql",
      options: {
        url: "postgresql://username:password@hostname:port/database_name"
      },
    },
  },
});

开发数据库

使用 devDatabase 配置来仅在开发模式下覆盖数据库配置。这对于在开发期间使用本地 SQLite 数据库，同时在生产环境中使用不同的数据库非常有用。

nitro.config.ts

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  database: {
    default: {
      connector: "postgresql",
      options: {
        url: "postgresql://username:password@hostname:port/database_name"
      }
    }
  },
  devDatabase: {
    default: {
      connector: "sqlite",
      options: { name: "dev-db" }
    }
  }
});

当启用 experimental.database 且未提供 database 或 devDatabase 配置时，Nitro 会自动配置默认的 SQLite 连接。在开发模式下，数据相对于项目根目录存储。在 Node.js 生产环境中，它使用默认的 SQLite 路径。

连接器

Nitro 支持所有 db0 连接器。数据库配置中的 connector 字段接受以下任意值：

连接器	描述
`sqlite`	Node.js 内置 SQLite（`node-sqlite` 的别名）
`node-sqlite`	Node.js 内置 SQLite
`better-sqlite3`	better-sqlite3
`sqlite3`	sqlite3
`bun` / `bun-sqlite`	Bun 内置 SQLite
`libsql` / `libsql-node`	libSQL (Node.js)
`libsql-http`	通过 HTTP 的 libSQL
`libsql-web`	适用于 Web 环境的 libSQL
`postgresql`	PostgreSQL
`mysql2`	MySQL
`pglite`	PGlite（嵌入式 PostgreSQL）
`planetscale`	PlanetScale 无服务器
`cloudflare-d1`	Cloudflare D1
`cloudflare-hyperdrive-mysql`	Cloudflare Hyperdrive 与 MySQL
`cloudflare-hyperdrive-postgresql`	Cloudflare Hyperdrive 与 PostgreSQL

配置

自定义并扩展 Nitro 默认配置。

生命周期

了解 Nitro 如何运行并为你的应用提供传入请求服务。