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

Prisma Postgres 是一个完全托管的 PostgreSQL 数据库，可缩减至零，并与 Prisma ORM 和 Prisma Studio 无缝集成。在本指南中，你将学习如何将 Prisma ORM 添加到现有的 TypeScript 项目中，将其连接到 Prisma Postgres，检查现有数据库模式，并使用类型安全的 Prisma Client 开始查询。

¥Prisma Postgres is a fully managed PostgreSQL database that scales to zero and integrates smoothly with both Prisma ORM and Prisma Studio. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to Prisma Postgres, 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/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg 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-pg - 将 Prisma Client 连接到数据库的 node-postgres 驱动程序适配器

  ¥@prisma/adapter-pg - The node-postgres driver adapter that connects Prisma Client to your database

• pg - node-postgres 数据库驱动程序

  ¥pg - The node-postgres database driver

• @types/pg - node-postgres 的 TypeScript 类型定义

  ¥@types/pg - TypeScript type definitions for node-postgres

• 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 postgresql --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 = "postgresql"
}

3. 连接你的数据库

¥ Connect your database

使用你的 Prisma Postgres 连接 URL 更新 .env 文件：

¥Update the .env file with your Prisma Postgres connection URL:

.env

DATABASE_URL="postgresql://user:password@host:5432/database?schema=public"

将占位符值替换为你的实际 Prisma Postgres 连接详细信息。

¥Replace the placeholder values with your actual Prisma Postgres connection details.

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 { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '../generated/prisma/client'

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

const adapter = new PrismaPg({ connectionString })
const prisma = new PrismaClient({ adapter })

export { prisma }

提示

如果你需要通过边缘运行时（例如 Cloudflare Workers、Vercel Edge Functions 等）使用 HTTP 查询数据库，请使用 Prisma Postgres 无服务器驱动程序。

¥If you need to query your database via HTTP from an edge runtime (Cloudflare Workers, Vercel Edge Functions, etc.), use the Prisma Postgres serverless driver.

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.

下一步

¥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

• Prisma Postgres 文档

  ¥Prisma Postgres documentation

• Prisma Config 参考

  ¥Prisma Config reference

• 数据库自省

  ¥Database introspection

• Prisma 迁移

  ¥Prisma Migrate

• 缓存查询

  ¥Cache your queries