Prisma ORM 與 SQL Server 快速入門
Microsoft SQL Server 是一款企業級關聯式資料庫。在本指南中，您將學習如何從零開始建立一個 TypeScript 專案，使用 Prisma ORM 連接到 SQL Server，並產生 Prisma Client 以實現簡單且型別安全的資料庫存取。
先決條件
您需要
- Node.js v20.19+、v22.12+ 或 v24.0+ 已安裝於您的機器上
- JavaScript 或 TypeScript 的基礎知識
您還需要
- 一個 Microsoft SQL Server 資料庫
- 資料庫連接詳細資訊（主機、連接埠、使用者名稱、密碼、資料庫名稱）
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/mssql --save-dev
npm install @prisma/client @prisma/adapter-mssql dotenv
以下是各個套件的功能說明
prisma- 用於執行指令（如prisma init、prisma migrate和prisma generate）的 Prisma CLI@prisma/client- 用於查詢資料庫的 Prisma Client 函式庫@prisma/adapter-mssql- 將 Prisma Client 連接到您資料庫的 SQL Server 驅動程式介面卡@types/mssql- mssql 的 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
您現在可以透過在前方加上 npx 來呼叫 Prisma CLI
npx prisma
接下來，透過以下指令建立您的 Prisma Schema 檔案來設定 Prisma ORM 專案
npx prisma init --datasource-provider sqlserver --output ../generated/prisma
此指令會執行以下幾個步驟：
- 建立一個
prisma/目錄，其中包含一個schema.prisma檔案，定義了您的資料庫連接與 Schema 模型 - 在根目錄建立一個用於環境變數的
.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 = "sqlserver"
}
使用您的 SQL Server 連接字串詳細資訊更新您的 .env 檔案
.env
DATABASE_URL="sqlserver://:1433;database=mydb;user=username;password=password;encrypt=true"
DB_USER="username"
DB_PASSWORD="password"
DB_NAME="mydb"
HOST="localhost"
將佔位符替換為您實際的資料庫認證資訊
localhost:1433: 您的 SQL Server 主機名稱與連接埠mydb：您的資料庫名稱username: 您的 SQL Server 使用者名稱password: 您的 SQL Server 密碼
5. 定義您的資料模型
開啟 prisma/schema.prisma 並新增下列模型
prisma/schema.prisma
generator client {
provider = "prisma-client"
output = "../generated/prisma"
}
datasource db {
provider = "sqlserver"
}
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 { PrismaMssql } from '@prisma/adapter-mssql';
import { PrismaClient } from '../generated/prisma/client';
const sqlConfig = {
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
server: process.env.HOST,
pool: {
max: 10,
min: 0,
idleTimeoutMillis: 30000
},
options: {
encrypt: true, // for azure
trustServerCertificate: false // change to true for local dev / self-signed certs
}
}
const adapter = new PrismaMssql(sqlConfig)
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. 使用 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 上與其他開發者交流