Prisma ORM 和 CockroachDB 快速入门

CockroachDB 是一个专为云应用程序构建的分布式 SQL 数据库。在本指南中，您将学习如何从头开始设置新的 TypeScript 项目，使用 Prisma ORM 将其连接到 CockroachDB，并生成 Prisma Client 以便轻松、类型安全地访问数据库。

先决条件

您需要

• 您的机器上安装了 Node.js v20.19+、v22.12+ 或 v24.0+
• JavaScript 或 TypeScript 基础知识

您还需要

• 一个 CockroachDB 数据库
• 来自 CockroachDB 的数据库连接字符串

1. 创建新项目

创建一个项目目录并进入该目录

mkdir hello-prisma
cd hello-prisma

初始化一个 TypeScript 项目

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

2. 安装所需的依赖项

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

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

每个包的作用如下

• prisma - 用于运行 prisma init、prisma migrate 和 prisma generate 等命令的 Prisma CLI
• @prisma/client - 用于查询数据库的 Prisma Client 库
• @prisma/adapter-pg - node-postgres 驱动程序适配器，用于将 Prisma Client 连接到您的数据库（CockroachDB 兼容 PostgreSQL）
• pg - node-postgres 数据库驱动程序
• @types/pg - node-postgres 的 TypeScript 类型定义
• dotenv - 从您的 .env 文件加载环境变量

3. 配置 ESM 支持

更新 tsconfig.json 以兼容 ESM

tsconfig.json

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

更新 package.json 以启用 ESM

package.json

{
  "type": "module",
}

4. 初始化 Prisma ORM

现在，您可以通过在 Prisma CLI 前面加上 npx 来调用它

npx prisma

接下来，使用以下命令创建 Prisma Schema 文件，设置您的 Prisma ORM 项目

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

此命令执行以下操作

• 创建一个 prisma/ 目录，其中包含一个 schema.prisma 文件，其中包含您的数据库连接和模式模型
• 在根目录中创建一个 .env 文件用于环境变量
• 创建一个 prisma.config.ts 文件用于 Prisma 配置

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

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 生成器

prisma/schema.prisma

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

datasource db {
  provider = "cockroachdb"
}

使用您的 CockroachDB 连接字符串更新您的 .env 文件

.env

DATABASE_URL="postgresql://username:password@host:26257/mydb?sslmode=require"

替换为您的集群仪表板中实际的 CockroachDB 连接字符串。

5. 定义您的数据模型

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

prisma/schema.prisma

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

datasource db {
  provider = "cockroachdb"
}

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. 创建并应用您的第一个迁移

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

npx prisma migrate dev --name init

此命令根据您的模式创建数据库表。

现在运行以下命令生成 Prisma Client

npx prisma generate

7. 实例化 Prisma Client

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

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 }

8. 编写您的第一个查询

创建一个 script.ts 文件来测试您的设置

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)
  })

运行脚本

npx tsx script.ts

您应该会在控制台中看到创建的用户和所有用户！

9. 探索你的数据

探索 CockroachDB 建议的选项，以查看和管理您的数据。

Prisma Studio 目前不支持 CockroachDB。未来版本可能会增加支持。有关更多信息，请参阅Prisma Studio 支持的数据库。

后续步骤

您已成功设置 Prisma ORM。接下来您可以探索

• 了解有关 Prisma Client 的更多信息：探索 Prisma Client API 以进行高级查询、筛选和关系操作
• 数据库迁移：了解 Prisma Migrate 以演进您的数据库模式
• 性能优化：发现查询优化技术
• 构建完整的应用程序：查看我们的框架指南，将 Prisma ORM 与 Next.js、Express 等集成
• 加入社区：在 Discord 上与其他开发者联系

更多信息

• CockroachDB 数据库连接器
• Prisma 配置参考
• 数据库连接管理