快速入门

在本快速入门指南中，您将学习如何使用一个简单的 TypeScript 项目和一个本地 SQLite 数据库文件从头开始使用 Prisma ORM。它涵盖了 数据建模、迁移和 查询数据库。

如果您想将 Prisma ORM 与您自己的 PostgreSQL、MySQL、MongoDB 或任何其他支持的数据库一起使用，请改为转到此处

• 从头开始使用 Prisma ORM
• 将 Prisma ORM 添加到现有项目

先决条件

本指南需要 Node.js v16.13.0 或更高版本（了解有关 系统要求 的更多信息）。

1. 创建 TypeScript 项目并设置 Prisma ORM

第一步，创建一个项目目录并导航到该目录

mkdir hello-prisma
cd hello-prisma

接下来，使用 npm 初始化一个 TypeScript 项目

npm init -y
npm install typescript ts-node @types/node --save-dev

这将创建一个包含 TypeScript 应用程序初始设置的 package.json 文件。

信息

查看 安装说明 了解如何使用不同的包管理器安装 Prisma。

现在，初始化 TypeScript

npx tsc --init

然后，将 Prisma CLI 作为开发依赖项安装到项目中

npm install prisma --save-dev

最后，使用 Prisma CLI 的 init 命令设置 Prisma ORM

npx prisma init --datasource-provider sqlite

这将在 prisma 目录中创建一个新的 prisma 目录，其中包含您的 Prisma 模式文件，并将 SQLite 配置为您的数据库。现在您已准备好对数据进行建模并使用一些表创建您的数据库。

2. 在 Prisma 模式中对您的数据进行建模

Prisma 模式提供了一种直观的方式来对数据进行建模。将以下模型添加到您的 schema.prisma 文件中

prisma/schema.prisma

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
}

Prisma 模式中的模型有两个主要目的

• 表示底层数据库中的表
• 作为生成的 Prisma Client API 的基础

在下一节中，您将使用 Prisma Migrate 将这些模型映射到数据库表。

3. 使用 Prisma Migrate 运行迁移以创建您的数据库表

此时，您有一个 Prisma 模式，但还没有数据库。在您的终端中运行以下命令以创建 SQLite 数据库以及由您的模型表示的 User 和 Post 表

npx prisma migrate dev --name init

此命令执行了三件事

1. 它在 prisma/migrations 目录中为此次迁移创建了一个新的 SQL 迁移文件。
2. 它针对数据库执行了 SQL 迁移文件。
3. 它在幕后运行了 prisma generate（它安装了 @prisma/client 包并根据您的模型生成了定制的 Prisma Client API）。

由于 SQLite 数据库文件之前不存在，因此该命令还在 prisma 目录中创建了它，名称为 dev.db，如 .env 文件中的环境变量定义的那样。

恭喜，您现在已经准备好了数据库和表格。让我们学习如何发送查询来读取和写入数据！

4. 使用 Prisma Client 探索如何向您的数据库发送查询

要向数据库发送查询，您需要一个 TypeScript 文件来执行您的 Prisma Client 查询。为此，创建一个名为 script.ts 的新文件

touch script.ts

然后，将以下样板代码粘贴到其中

script.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  // ... you will write your Prisma Client queries here
}

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

此代码包含一个在脚本末尾调用的 main 函数。它还实例化了 PrismaClient，它代表您数据库的查询接口。

4.1. 创建一个新的 User 记录

让我们从一个小的查询开始，在数据库中创建一个新的 User 记录，并将结果对象记录到控制台。将以下代码添加到您的 script.ts 文件中

script.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  const user = await prisma.user.create({
    data: {
      name: 'Alice',
      email: '[email protected]',
    },
  })
  console.log(user)
}

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

您可以直接在编辑器中输入代码，而不是复制它，这样可以体验 Prisma Client 提供的自动补全功能。您也可以通过按下键盘上的 CTRL+SPACE 键来主动调用自动补全功能。

接下来，使用以下命令执行脚本

npx ts-node script.ts

显示 CLI 结果

干得好，您刚刚使用 Prisma Client 创建了您的第一个数据库记录！🎉

在下一节中，您将学习如何从数据库中读取数据。

4.2. 检索所有 User 记录

Prisma Client 提供了各种查询来从您的数据库中读取数据。在本节中，您将使用 findMany 查询，该查询返回给定模型的数据库中的所有记录。

删除之前的 Prisma Client 查询，并添加新的 findMany 查询

script.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  const users = await prisma.user.findMany()
  console.log(users)
}

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

再次执行脚本

npx ts-node script.ts

显示 CLI 结果

请注意，控制台中单个 User 对象现在用方括号括起来。这是因为 findMany 返回了一个包含单个对象的数组。

4.3. 使用 Prisma Client 探索关系查询

Prisma Client 的主要功能之一是轻松处理关系。在本节中，您将学习如何在嵌套写入查询中创建User和Post记录。之后，您将了解如何使用include选项从数据库中检索关系。

首先，调整您的脚本以包含嵌套查询

script.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  const user = await prisma.user.create({
    data: {
      name: 'Bob',
      email: '[email protected]',
      posts: {
        create: {
          title: 'Hello World',
        },
      },
    },
  })
  console.log(user)
}

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

再次执行脚本以运行查询

npx ts-node script.ts

显示 CLI 结果

默认情况下，Prisma Client 仅在查询的结果对象中返回标量字段。因此，即使您也为新的User记录创建了一个新的Post记录，控制台也只打印了一个包含三个标量字段的对象：id、email和name。

为了检索属于User的Post记录，您可以通过posts关系字段使用include选项

script.ts

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  const usersWithPosts = await prisma.user.findMany({
    include: {
      posts: true,
    },
  })
  console.dir(usersWithPosts, { depth: null })
}

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

再次运行脚本以查看嵌套读取查询的结果

npx ts-node script.ts

显示 CLI 结果

这次，您将看到打印了两个User对象。它们都有一个posts字段（对于"Alice"为空，而对于"Bob"则填充了一个Post对象），表示与它们关联的Post记录。

请注意，usersWithPosts数组中的对象也完全类型化。这意味着您将获得自动完成，并且 TypeScript 编译器将阻止您意外地对其进行类型化。

5. 下一步

在本快速入门指南中，您学习了如何在纯 TypeScript 项目中开始使用 Prisma ORM。您可以自由地自行探索 Prisma Client API，例如，通过在findMany查询中包含过滤、排序和分页选项，或探索更多操作，例如update和delete查询。

在 Prisma Studio 中探索数据

Prisma ORM 带有一个内置的 GUI 来查看和编辑数据库中的数据。您可以使用以下命令打开它

npx prisma studio

使用您自己的数据库设置 Prisma ORM

如果您想使用您自己的 PostgreSQL、MySQL、MongoDB 或任何其他支持的数据库继续使用 Prisma ORM，请遵循设置 Prisma ORM 指南

• 从头开始使用 Prisma ORM
• 将 Prisma ORM 添加到现有项目

探索可运行的 Prisma ORM 示例

查看 prisma-examples GitHub 上的仓库，了解如何将 Prisma ORM 与您喜欢的库一起使用。该仓库包含使用 Express、NestJS、GraphQL 的示例，以及使用 Next.js 和 Vue.js 的完整堆栈示例，以及更多内容。

使用 Prisma ORM 构建应用程序

Prisma 博客提供了关于 Prisma ORM 的全面教程，查看我们最新的教程

• 使用 Remix 构建完整堆栈应用程序（5 部分，包括视频）
• 使用 NestJS 构建 REST API

加入 Prisma 社区 💚

Prisma 拥有庞大的 开发者社区。加入我们 Discord 或使用 GitHub Discussions 提出问题。