NestJs--Prisma 7的安装与数据库配置（超完整）

Ticnix
0 阅读7分钟

前言

在现代后端开发中，NestJS `凭借优雅的架构、TypeScript 强类型支持成为企业级 Node.js 框架首选；Prisma 7 作为新一代 ORM，彻底解决了传统数据库操作的类型不安全、语法繁琐问题。

本文从零到一，超完整讲解 NestJS 集成 Prisma 7 的全流程：安装、初始化、配置、CRUD 实战、连接池优化、生产环境配置，一步到位直接落地项目。

什么是 Prisma 7 ORM?

ORM（Object-Relational Mapping）的本质是把数据库表映射为代码中的对象，让开发者用面向对象方式操作数据库，不用手写原生 SQL。Prisma 7 不是传统 ORM 的 “升级版”，而是重构式新一代 ORM：

  • 核心架构：完全抛弃 Rust 查询引擎，重写为纯 TypeScript 运行时 + 查询编译器，消除 JS 与 Rust 跨进程通信瓶颈，适配 Serverless / 边缘环境（Cloudflare Workers、Vercel Edge）Prisma
  • 工作流：Schema 优先（Schema-First） —— 用 Prisma Schema 定义数据模型 → 自动生成类型安全的 Prisma Client → 用 Client 做 CRUD → 自动生成数据库迁移 → 可视化管理数据
  • 核心价值：全程 TypeScript 类型安全、零冗余 SQL、版本化迁移、极简 API、全环境兼容

ORM 说白了就是：不用写复杂的数据库 SQL 语句，用写代码的方式操作数据库。

你可以把它理解成：

  • 一个自动帮你建表、改表的工具
  • 一个自动帮你写 SQL的工具
  • 一个自带智能提示、几乎不会写错代码的工具
  • 一个自带可视化面板，能直接看库里数据的工具

安装教程

一、环境准备

开始前确保本地已安装必备环境：

  1. Node.js：v18.18.0+ /v20+（LTS 版本）
  2. 包管理器：npm /yarn/pnpm（本文以 npm 为例）
  3. 数据库：MySQL / PostgreSQL / SQLite

二、创建 NestJS 项目

如果没有NestJS 项目，首先初始化一个全新的 NestJS 项目：

# 创建项目 
npx create-next-app@latest 你的项目名称

# 进入项目目录 
cd 你的项目名称

等待依赖安装完成，项目基础结构就搭建好了。

三、安装 Prisma

Prisma 7 分为两部分：

  • prisma：开发依赖，用于生成客户端、执行迁移
  • @prisma/client：生产依赖，项目中操作数据库的核心
# 安装 Prisma 7（开发依赖） 
npm install prisma --save-dev

# 安装 Prisma Client（生产依赖） 
npm install @prisma/client --save

这个prisma依赖安装可能会需要一些时间

四、初始化 Prisma

在 Nest 项目中初始化 Prisma，自动生成配置文件：

npx prisma init

初始化成功后，项目根目录会生成：

  • prisma 文件夹

    • schema.prisma：Prisma 核心配置文件（数据源、模型、生成器）

  • .env 环境变量文件（如果没有这个文件可以手动添加，注意要跟src在同级目录）

    • 存储数据库连接地址

  • prisma.config.ts 配置文件

    • 指定 schema.prisma 文件路径

    • 配置种子文件、格式化、生成器等全局选项

    • 让 prisma 命令自动读取配置，不用每次手动传参

image.png

五、配置 Prisma Schema

1. 配置数据源（database）

打开 prisma/schema.prisma，这是 Prisma 的核心文件，打开会发现系统已经自动生成好了基础的配置，只需按照自己的需求调整一下就好了，在datasource db中选择需要的数据类型，本文用postgresql作为演示。

image.png

这是 Prisma 数据库工具 的两个核心配置说明（辅助大家理解每一个配置的含义）：

1. generator client

作用：告诉 Prisma 如何生成「Prisma Client」—— 这是你在代码里用来操作数据库的 TypeScript/JavaScript 客户端库。

  • 关键字段说明：

1、provider = "prisma-client"：指定使用官方的 Prisma Client 生成器（唯一官方选项）。

2、output = "../src/generated/prisma"：自定义生成的客户端代码的输出路径（默认是 ./node_modules/.prisma/client，这里改到了项目源码目录，方便本地开发调试）。

  • 执行时机：运行 npx prisma generate 命令时，Prisma 会根据这个配置，基于你定义的数据模型，生成类型安全的数据库操作代码
2. datasource db

作用：告诉 Prisma 你要连接的数据库类型和连接信息，是 Prisma 与数据库通信的入口。

  • 关键字段说明：

provider = "postgresql"：指定数据库类型，支持 mysql、postgresql、sqlite、sqlserver、mongodb 等（图中标注了常见的 3 种）。

  • 执行时机：所有 Prisma 命令（prisma migrate dev、prisma db push、prisma studio 等）都会读取这个配置，来连接目标数据库。

注意：这里不要加url(从环境变量读取数据库连接字符串)这个配置，不然会报错，Prisma 7的url配置已经在 prisma.config.ts 里自动配置好了，不需要再手动配置，这是安装Prisma 7依赖时自动生成的，如果没有这个文件的同学可以按照我这个配置手动添加上去。

image.png

2. 修改 .env 数据库连接地址

打开根目录 .env 文件，修改为 PostgreSQL 配置：

# PostgreSQL 配置
# DATABASE_URL="postgresql://用户名:密码@localhost:5432/数据库名?schema=public"

# SQLite 配置（备用） 
DATABASE_URL="file:./dev.db" 

# MySQL 配置（备用） 
# DATABASE_URL="mysql://用户名:密码@localhost:3306/数据库名?schema=public"

3. 创建数据模型（Model）

我们以最常用的 User 表为例，在 schema.prisma 末尾添加模型：

image.png

模型写完后，后续所有数据库操作都有完整的 TypeScript 类型提示。

六、生成 Prisma Client

模型定义完成后，生成 TypeScript 客户端：

npx prisma generate

执行成功后，@prisma/client 会自动生成对应模型的类型和方法，直接在代码中调用。 注意：每次修改了数据模型以后，都需要重新运行这个命令，及时更新客户端代码。

七、创建 Prisma 模块与服务（Nest 标准写法）

Nest 推崇模块化，我们需要创建一个 Prisma 全局模块，方便整个项目调用。 (这一步不一定按照我的写法，自己想怎么调用就怎么调用就行，这里只是给个例子，也跟后续的数据库连接无关)

1. 创建 Prisma Service

创建文件 src/prisma/prisma.service.ts：

import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService
  extends PrismaClient
  implements OnModuleInit, OnModuleDestroy
{
  // 模块初始化时连接数据库
  async onModuleInit() {
    await this.$connect();
  }

  // 模块销毁时断开连接
  async onModuleDestroy() {
    await this.$disconnect();
  }
}

2. 创建 Prisma Module

创建文件 src/prisma/prisma.module.ts：

import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

// 声明为全局模块，无需在其他模块重复导入
@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService], // 导出服务，供全项目使用
})
export class PrismaModule {}

3. 注册到根模块

打开 src/app.module.ts，导入 Prisma 模块：

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { PrismaModule } from './prisma/prisma.module';

@Module({
  imports: [PrismaModule], // 注册 Prisma 全局模块
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

至此，Prisma 7 在 NestJS 中配置完成！

八、数据库迁移（创建表）

我们定义的 User 模型需要同步到数据库，执行迁移命令：

# 生成迁移文件并同步到数据库 
npx prisma migrate dev --name init

执行成功后：

  1. prisma/migrations 生成版本化迁移文件（可追踪表结构变更）
  2. 数据库自动创建 User 表
  3. PostgreSQL 生成 dev.db 文件

小技巧：执行 npx prisma studio 可打开可视化数据库工具，直接查看 / 编辑数据。

image.png

可能出现的错误

image.png 说明你的 Docker PostgreSQL 容器没在运行，或者端口没通，Prisma 连不上数据库 所以迁移的时候别忘检查一下Docker 里的 你的项目名称-db 容器启动没，确保打开以后再运行一遍迁移命令

image.png

也可以用命令查看Docker的运行状态

1、打开 CMD / PowerShell，执行：

docker ps

  • 如果看不到 ai-engine-db 容器，说明容器没运行

  • 如果能看到，但状态不是 Up，说明容器异常

  1. 启动容器（如果没运行）
# 启动之前创建的容器 
docker start ai-engine-db
  1. 再次检查状态
docker ps

具体操作过程如下：

image.png

看到 ai-engine-db 状态为 Up，端口 0.0.0.0:5432->5432/tcp，说明数据库正常运行了

容器启动后，回到项目终端，重新执行迁移命令：

npx prisma migrate dev --name init

成功后会看到：

Your database is now in sync with your schema.

直到没有新的数据需要迁移

image.png 补充：如果容器被误删，重新创建

docker run -d --name ai-engine-db -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=123456 -e POSTGRES_DB=ai_engine pgvector/pgvector:pg16

一键重建数据库容器，然后再执行迁移命令。

排查完这些问题

Prisma 7的安装与数据库配置就已经全部成功了

avatar
文章
阅读
粉丝