Prisma ORM 與 Prisma Postgres 快速入門

Prisma Postgres 是一項全託管的 PostgreSQL 資料庫服務，具備縮減至零（scale to zero）的彈性，並能與 Prisma ORM 和 Prisma Studio 無縫整合。在本指南中，您將學習如何從頭開始建立一個 TypeScript 專案，使用 Prisma ORM 將其連接至 Prisma Postgres，並產生 Prisma Client 以進行簡便且具備型別安全（type-safe）的資料庫存取。

先決條件

您需要

• Node.js v20.19+、v22.12+ 或 v24.0+ 已安裝於您的機器上
• JavaScript 或 TypeScript 的基礎知識

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 - 將 Prisma Client 連接至資料庫的 node-postgres 驅動程式轉接器
• 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 Postgres 資料庫

您現在可以透過在前方加上 npx 來呼叫 Prisma CLI

npx prisma

接下來，透過以下指令建立您的 Prisma Schema 檔案來設定 Prisma ORM 專案

npx prisma init --db --output ../generated/prisma

資訊

在設定 Prisma Postgres 資料庫時，您需要回答幾個問題。請選擇離您位置最近的區域，並為您的資料庫取一個好記的名稱。

此指令會執行以下幾個步驟：

• 建立一個 prisma/ 目錄，其中包含一個 schema.prisma 檔案，定義了您的資料庫連接與 Schema 模型
• 建立一個新的 Prisma Postgres 資料庫（使用 --db 旗標時）
• 在根目錄建立一個用於環境變數的 .env 檔案
• 建立一個用於 Prisma 設定的 prisma.config.ts 檔案

產生的 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 = "postgresql"
}

5. 定義您的資料模型

開啟 prisma/schema.prisma 並新增下列模型

prisma/schema.prisma

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

datasource db {
  provider = "postgresql"
}

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

此指令會根據您的 Schema 建立資料庫資料表。

現在執行以下指令來生成 Prisma Client

npx prisma generate

7. 實例化 Prisma Client

現在您已安裝所有相依套件，可以實例化 Prisma Client。您需要將 Prisma ORM 的驅動程式配接器（driver adapter）實例傳遞給 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 }

提示

如果您需要透過邊緣執行環境 (Edge Runtime，如 Cloudflare Workers、Vercel Edge Functions 等) 以 HTTP 方式查詢資料庫，請使用 Prisma Postgres 無伺服器驅動程式 (serverless driver)。

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. 使用 Prisma Studio 探索您的資料

Prisma Studio 是一個資料庫視覺化編輯器。使用以下指令啟動它

npx prisma studio --config ./prisma.config.ts

這將開啟一個網頁介面，您可以在其中檢視和編輯資料。

支援的資料庫

Prisma Studio 目前支援 PostgreSQL、MySQL 和 SQLite。更多詳細資訊，請參閱Prisma Studio 支援的資料庫。

後續步驟

您已成功設定 Prisma ORM。接下來您可以探索以下內容：

• 深入了解 Prisma Client：探索 Prisma Client API 以進行進階查詢、篩選和關聯處理
• 資料庫遷移：了解 Prisma Migrate 以便演進您的資料庫結構
• 效能最佳化：發現查詢最佳化技巧
• 建構完整應用程式：查看我們的框架指南，將 Prisma ORM 整合至 Next.js、Express 等框架
• 加入社群：在 Discord 上與其他開發者交流

更多資訊

• Prisma Postgres 文件
• Prisma Config 參考
• 資料庫連接管理
• 快取您的查詢