Skip to main content

Prisma ORM 和 SQLite 快速入门

SQLite 是一个轻量级的基于文件的数据库，非常适合开发、原型设计和小规模应用。无需任何设置，并将数据存储在本地文件中。

¥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.

在本指南中，你将学习如何从零开始创建一个新的 TypeScript 项目，使用 Prisma ORM 将其连接到 SQLite，并生成一个 Prisma 客户端，以便轻松、类型安全地访问你的数据库。

¥In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to SQLite using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database.

先决条件​

¥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. 创建一个新项目​

¥ Create a new project

创建一个项目目录并导航到它：

¥Create a project directory and navigate into it:

mkdir hello-prisma
cd hello-prisma

初始化 TypeScript 项目：

¥Initialize a TypeScript project:

npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

2. 安装所需依赖​

¥ Install required dependencies

安装此快速入门所需的软件包：

¥Install the packages needed for this quickstart:

npm install prisma @types/node @types/better-sqlite3 --save-dev 
npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv
使用 SQLite 的 pnpm 用户

如果使用 pnpm 10+ 和 pnpx，由于 SQLite 的原生依赖要求，运行 Prisma Studio 时需要 --allow-build=better-sqlite3 标志。

¥If using pnpm 10+ with pnpx, you'll need the --allow-build=better-sqlite3 flag when running Prisma Studio due to SQLite's native dependency requirements.

以下是每个包的功能：

¥Here's what each package does:

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

    ¥prisma - The Prisma CLI for running commands like prisma init, prisma migrate, 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

3. 配置 ESM 支持​

¥ Configure ESM support

更新 tsconfig.json 以兼容 ESM：

¥Update tsconfig.json for ESM compatibility:

tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0"
  }
}

更新 package.json 以启用 ESM：

¥Update package.json to enable ESM:

package.json
{
  "type": "module",
}

4. 初始化 Prisma ORM​

¥ Initialize Prisma ORM

你现在可以通过添加 npx 前缀来调用 Prisma CLI：

¥You can now invoke the Prisma CLI by prefixing it with npx:

npx prisma

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

¥Next, 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 and schema models

  • 在根目录中创建一个用于环境变量的 .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"

5. 定义你的数据模型​

¥ Define your data model

打开 prisma/schema.prisma 文件并添加以下模型：

¥Open prisma/schema.prisma and add the following models:

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

datasource db {
  provider = "sqlite"
}

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

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

6. 创建并应用你的第一个迁移​

¥ Create and apply your first migration

创建第一个迁移以设置数据库表：

¥Create your first migration to set up the database tables:

npx prisma migrate dev --name init

此命令根据你的架构创建数据库表。

¥This command creates the database tables based on your schema.

现在运行以下命令来生成 Prisma 客户端：

¥Now run the following command to generate the Prisma Client:

npx prisma generate

7. 实例化 Prisma 客户端​

¥ Instantiate Prisma Client

现在你已安装所有依赖，可以实例化 Prisma Client 了。你需要将 Prisma ORM 的驱动程序适配器实例传递给 PrismaClient 构造函数：

¥Now that you have all the dependencies installed, you can 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 为目标平台时，请使用 @prisma/adapter-libsql 适配器而不是 @prisma/adapter-better-sqlite3。Bun 不支持 better-sqlite3 所依赖的原生 SQLite 驱动程序（请参阅 node:sqlite 参考）。按如下方式实例化 Prisma Client：

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

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. 编写你的第一个查询​

¥ Write your first query

创建 script.ts 文件以测试你的设置：

¥Create a script.ts file to test your setup:

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

async function main() {
  // Create a new user with a post
  const user = await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: {
          title: 'Hello World',
          content: 'This is my first post!',
          published: true,
        },
      },
    },
    include: {
      posts: true,
    },
  })
  console.log('Created user:', user)

  // Fetch all users with their posts
  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
    },
  })
  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

你应该在控制台中看到已创建的用户以及所有用户！

¥You should see the created user and all users printed to the console!

9. 使用 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

  • 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:./dev.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