将 Prisma ORM 添加到现有的 SQLite 项目

SQLite 是一个轻量级的基于文件的数据库，非常适合开发、原型设计和小规模应用。无需任何设置，并将数据存储在本地文件中。在本指南中，你将学习如何将 Prisma ORM 添加到现有的 TypeScript 项目中，将其连接到 SQLite 数据库，检查现有数据库模式，并使用类型安全的 Prisma Client 开始查询。

¥SQLite is a lightweight, file-based database that's perfect for development, prototyping, and small applications. It requires no setup and stores data in a local file. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to SQLite, introspect your existing database schema, and start querying with type-safe Prisma Client.

先决条件

¥Prerequisites

你需要：

¥You need:

• 你的机器上已安装 Node.js v20.19+、v22.12+ 或 v24.0+ 版本

  ¥Node.js v20.19+, v22.12+, or v24.0+ installed on your machine

• 具备 JavaScript 或 TypeScript 的基础知识

  ¥Basic knowledge of JavaScript or TypeScript

1. 设置 Prisma ORM

¥ Set up Prisma ORM

进入现有项目目录并安装所需的依赖：

¥Navigate to your existing project directory and install the required dependencies:

npm install prisma @types/node @types/better-sqlite3 --save-dev
npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv

以下是每个包的功能：

¥Here's what each package does:

• prisma - 用于运行 prisma init、prisma db pull 和 prisma generate 等命令的 Prisma CLI

  ¥prisma - The Prisma CLI for running commands like prisma init, prisma db pull, and prisma generate

• @prisma/client - 用于查询数据库的 Prisma 客户端库

  ¥@prisma/client - The Prisma Client library for querying your database

• @prisma/adapter-better-sqlite3 - 将 Prisma Client 连接到数据库的 SQLite 驱动程序适配器

  ¥@prisma/adapter-better-sqlite3 - The SQLite driver adapter that connects Prisma Client to your database

• @types/better-sqlite3 - better-sqlite3 的 TypeScript 类型定义

  ¥@types/better-sqlite3 - TypeScript type definitions for better-sqlite3

• dotenv - 从你的 .env 文件加载环境变量

  ¥dotenv - Loads environment variables from your .env file

2. 初始化 Prisma ORM

¥ Initialize Prisma ORM

使用以下命令创建 Prisma 模式 文件，设置你的 Prisma ORM 项目：

¥Set up your Prisma ORM project by creating your Prisma Schema file with the following command:

npx prisma init --datasource-provider sqlite --output ../generated/prisma

此命令执行以下几项操作：

¥This command does a few things:

• 创建一个名为 prisma/ 的目录，其中包含一个 schema.prisma 文件，该文件包含数据库连接配置

  ¥Creates a prisma/ directory with a schema.prisma file containing your database connection configuration

• 在根目录中创建一个用于环境变量的 .env 文件

  ¥Creates a .env file in the root directory for environment variables

• 创建一个用于 Prisma 配置的 prisma.config.ts 文件

  ¥Creates a prisma.config.ts file for Prisma configuration

生成的 prisma.config.ts 文件如下所示：

¥The generated prisma.config.ts file looks like this:

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

生成的 schema 使用带有自定义输出路径的 ESM 优先的 prisma-client 生成器：

¥The generated schema uses the ESM-first prisma-client generator with a custom output path:

prisma/schema.prisma

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "sqlite"
}

应创建一个 .env 文件，并包含以下值：

¥A .env file should be created with the following value:

.env

DATABASE_URL="file:./dev.db"

3. 连接你的数据库

¥ Connect your database

更新 .env 文件，使其指向你现有的 SQLite 数据库文件：

¥Update the .env file to point to your existing SQLite database file:

.env

DATABASE_URL="file:./path/to/your/database.db"

4. 检查你的数据库

¥ Introspect your database

运行以下命令检查现有数据库：

¥Run the following command to introspect your existing database:

npx prisma db pull

此命令读取 DATABASE_URL 环境变量，连接到你的数据库，并检查数据库模式。然后，它将数据库架构从 SQL 转换为 Prisma 架构中的数据模型。

¥This command reads the DATABASE_URL environment variable, connects to your database, and introspects the database schema. It then translates the database schema from SQL into a data model in your Prisma schema.

自省后，你的 Prisma 模式将包含表示现有数据库表的模型。

¥After introspection, your Prisma schema will contain models that represent your existing database tables.

5. 为数据库设定基线

¥ Baseline your database

要将 Prisma Migrate 与现有数据库一起使用，你需要使用 数据库的基线。

¥To use Prisma Migrate with your existing database, you need to baseline your database.

首先，创建一个 migrations 目录：

¥First, create a migrations directory:

mkdir -p prisma/migrations/0_init

接下来，生成包含 prisma migrate diff 的迁移文件：

¥Next, generate the migration file with prisma migrate diff:

npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql

检查生成的迁移文件，确保其与你的数据库架构匹配。

¥Review the generated migration file to ensure it matches your database schema.

然后，将迁移标记为已应用：

¥Then, mark the migration as applied:

npx prisma migrate resolve --applied 0_init

你现在已经有了当前数据库架构的基线。

¥You now have a baseline for your current database schema.

6. 生成 Prisma ORM 类型

¥ Generate Prisma ORM types

根据你内省的 schema 生成 Prisma Client：

¥Generate Prisma Client based on your introspected schema:

npx prisma generate

这将在 generated/prisma 目录中创建一个针对你的数据库模式定制的类型安全的 Prisma 客户端。

¥This creates a type-safe Prisma Client tailored to your database schema in the generated/prisma directory.

7. 实例化 Prisma 客户端

¥ Instantiate Prisma Client

创建一个用于实例化 Prisma Client 的实用程序文件。你需要将 Prisma ORM 的驱动程序适配器实例传递给 PrismaClient 构造函数：

¥Create a utility file to instantiate Prisma Client. You need to pass an instance of Prisma ORM's driver adapter to the PrismaClient constructor:

lib/prisma.ts

import "dotenv/config";
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "../generated/prisma/client";

const connectionString = `${process.env.DATABASE_URL}`;

const adapter = new PrismaBetterSqlite3({ url: connectionString });
const prisma = new PrismaClient({ adapter });

export { prisma };

使用 Bun 的 SQLite

Bun 不支持 better-sqlite3 所依赖的原生 SQLite 驱动程序（请参阅 node:sqlite 参考）。以 Bun 为目标平台时，请使用 @prisma/adapter-libsql 适配器：

¥Bun doesn't support the native SQLite driver that better-sqlite3 relies on (see the node:sqlite reference). When targeting Bun, use the @prisma/adapter-libsql adapter instead:

import 'dotenv/config';
import { PrismaLibSql } from '@prisma/adapter-libsql';
import { PrismaClient } from '../generated/prisma/client';

const adapter = new PrismaLibSql({
  url: process.env.DATABASE_URL ?? '',
});

const prisma = new PrismaClient({ adapter });

export { prisma };

8. 查询数据库

¥ Query your database

现在你可以使用 Prisma Client 查询数据库。创建 script.ts 文件：

¥Now you can use Prisma Client to query your database. Create a script.ts file:

script.ts

import { prisma } from './lib/prisma'

async function main() {
  // Example: Fetch all records from a table
  // Replace 'user' with your actual model name
  const allUsers = await prisma.user.findMany()
  console.log('All users:', JSON.stringify(allUsers, null, 2))
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

运行脚本：

¥Run the script:

npx tsx script.ts

9. 发展你的架构

¥ Evolve your schema

要更改数据库架构：

¥To make changes to your database schema:

9.1.更新 Prisma schema 文件

¥9.1. Update your Prisma schema file

更新你的 Prisma schema 文件，以反映你想要对数据库架构所做的更改。例如，添加一个新模型：

¥Update your Prisma schema file to reflect the changes you want to make to your database schema. For example, add a new model:

prisma/schema.prisma

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
  posts Post[]
}

9.2.创建并应用迁移

¥9.2. Create and apply a migration:

npx prisma migrate dev --name your_migration_name

该命令将：

¥This command will:

• 创建一个新的 SQL 迁移文件

  ¥Create a new SQL migration file

• 将迁移应用到你的数据库

  ¥Apply the migration to your database

• 重新生成 Prisma 客户端

  ¥Regenerate Prisma Client

10 .使用 Prisma Studio 探索你的数据

¥. Explore your data with Prisma Studio

Prisma Studio 是一个用于数据库的可视化编辑器。使用以下命令启动：

¥Prisma Studio is a visual editor for your database. Launch it with:

npx prisma studio --config ./prisma.config.ts

这将打开一个 Web 界面，你可以在其中查看和编辑数据。

¥This opens a web interface where you can view and edit your data.

支持的数据库

Prisma Studio 目前支持 PostgreSQL、MySQL 和 SQLite。详细信息请参见 Prisma 支持的数据库 Studio。

¥Prisma Studio currently supports PostgreSQL, MySQL, and SQLite. For more details, see Databases supported by Prisma Studio.

Prisma Studio 的 SQLite 要求

• 目前，SQLite 数据库 URL 中的文件路径必须包含 file: 协议

  ¥File paths must have a file: protocol right now in the database url for SQLite

• Node.js 22.5+：与内置的 node:sqlite 模块即插即用

  ¥Node.js 22.5+: Works out of the box with the built-in node:sqlite module

  • 可能需要 NODE_OPTIONS=--experimental-sqlite 环境变量

    ¥May require NODE_OPTIONS=--experimental-sqlite environment variable

• Node.js 20：需要安装 better-sqlite3 作为依赖。

  ¥Node.js 20: Requires installing better-sqlite3 as a dependency

  • 如果使用 pnpm 10+ 和 pnpx，则需要 --allow-build=better-sqlite3 标志。

    ¥If using pnpm 10+ with pnpx, you'll need the --allow-build=better-sqlite3 flag

• Deno >= 2.2：通过 内置 SQLite 模块 支持

  ¥Deno >= 2.2: Supported via built-in SQLite module

• Bun：Prisma Studio 与 SQLite 的支持即将推出，目前尚未提供。

  ¥Bun: Support for Prisma Studio with SQLite is coming soon and is not available yet

:::tipnpx with better-sqlite3][使用

如果你的运行时环境中没有 node:sqlite，或者你不想将 better-sqlite3 作为硬性依赖安装（它会增加约 10MB 的空间），你可以使用 npx 临时安装所需的软件包：

¥If you don't have node:sqlite available in your runtime or prefer not to install better-sqlite3 as a hard dependency (it adds ~10MB), you can use npx to temporarily install the required packages:

npx -p better-sqlite3 -p prisma prisma studio --url file:./path/to/your/database.db

这个命令：

¥This command:

• 临时安装 better-sqlite3，但不将其添加到项目依赖中

  ¥Temporarily installs better-sqlite3 without adding it to your project dependencies

• 使用指定的 SQLite 数据库文件运行 Prisma Studio

  ¥Runs Prisma Studio with the specified SQLite database file

• 避免 better-sqlite3 在你的项目中占用 10MB 的额外资源

  ¥Avoids the 10MB overhead of better-sqlite3 in your project

下一步

¥Next steps

你已成功设置 Prisma ORM。接下来你可以探索以下内容：

¥You've successfully set up Prisma ORM. Here's what you can explore next:

• 了解更多关于 Prisma 客户端的信息：探索 Prisma 客户端 API 的高级查询、筛选和关联功能

  ¥Learn more about Prisma Client: Explore the Prisma Client API for advanced querying, filtering, and relations

• 数据库迁移：了解 Prisma 迁移，以便演进你的数据库模式

  ¥Database migrations: Learn about Prisma Migrate for evolving your database schema

• 性能优化：Discover 查询优化技巧

  ¥Performance optimization: Discover query optimization techniques

• 构建完整应用：查看我们的 框架指南，了解如何将 Prisma ORM 与 Next.js、Express 等集成。

  ¥Build a full application: Check out our framework guides to integrate Prisma ORM with Next.js, Express, and more

• 加入社区：通过 Discord 与其他开发者连接

  ¥Join the community: Connect with other developers on Discord

更多信息

¥More info

• SQLite 数据库连接器

  ¥SQLite database connector

• Prisma Config 参考

  ¥Prisma Config reference

• 数据库自省

  ¥Database introspection

• Prisma 迁移

  ¥Prisma Migrate