Microsoft SQL Server

Microsoft SQL Server 資料來源連接器可將 Prisma ORM 連接到 Microsoft SQL Server 資料庫伺服器。

範例

若要連接到 Microsoft SQL Server 資料庫，您需要在 Prisma schema 中配置一個 datasource 區塊。

schema.prisma

datasource db {
  provider = "sqlserver"
}

資料庫連接 URL 在 prisma.config.ts 中進行配置。

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

資訊

使用 Prisma CLI 命令時，環境變數不會自動載入。您需要使用像 dotenv 這樣的套件從 .env 檔案載入環境變數，或確保您的環境變數已在您的 shell 中設定。

傳遞給 datasource 區塊的欄位有：

provider：指定 sqlserver 資料來源連接器。
url 欄位是在 prisma.config.ts 中配置，並指定 Microsoft SQL Server 資料庫的連接 URL。

使用 `node-mssql` 驅動程式

自 v5.4.0 起，您可以將 Prisma ORM 與來自 JavaScript 生態系統的資料庫驅動程式搭配使用（而不是使用 Prisma ORM 內建的驅動程式）。您可以透過使用驅動程式轉接器 (driver adapter) 來達成此目的。

對於 SQLite 以外的場景，node-mssql 是 JavaScript 生態系統中最受歡迎的驅動程式之一。

本節說明如何將其與 Prisma ORM 及 @prisma/adapter-mssql 驅動程式適配器結合使用。

1. 安裝相依套件

首先，安裝 Prisma ORM 用於 node-mssql 的驅動程式適配器。

npm install @prisma/adapter-mssql

2. 使用驅動程式轉接器實例化 Prisma Client

現在，當您實例化 Prisma Client 時，您需要將 Prisma ORM 驅動程式轉接器的實例傳遞給 PrismaClient 建構函式。

import 'dotenv/config'
import { PrismaMssql } from '@prisma/adapter-mssql'
import { PrismaClient } from '../prisma/generated/client'

const config = {
  server: 'localhost',
  port: 1433,
  database: 'mydb',
  user: 'sa',
  password: 'mypassword',
  options: {
    encrypt: true, // Use this if you're on Windows Azure
    trustServerCertificate: true, // Use this if you're using self-signed certificates
  },
}

const adapter = new PrismaMssql(config)
const prisma = new PrismaClient({ adapter })

連接詳情

用於連接 Microsoft SQL Server 資料庫的連接 URL 遵循 JDBC 標準。

以下範例使用 SQL 身分驗證（使用者名稱與密碼）並啟用 TLS 加密連接。

sqlserver://HOST[:PORT];database=DATABASE;user=USER;password=PASSWORD;encrypt=true

警告

注意：如果您在連接字串中使用以下任何字元，您需要對它們進行跳脫處理。

:\=;/[]{}  # these are characters that will need to be escaped

要跳脫這些字元，請在包含特殊字元的數值周圍使用大括號 {}。例如：

sqlserver://HOST[:PORT];database=DATABASE;user={MyServer/MyUser};password={ThisIsA:SecurePassword;};encrypt=true

引數

參數名稱	必填	預設值	註解
`資料庫` `initial catalog`	否	`master`	要連接的資料庫名稱。
`username` `user` `uid` `userid`	無 - 請參閱註解		SQL Server 登入帳號（例如 `sa`），或者若 `integratedSecurity` 設為 `true`，則為有效的 Windows (Active Directory) 使用者名稱（僅限 Windows）。
`password` `pwd`	無 - 請參閱註解		SQL Server 登入密碼，或者若 `integratedSecurity` 設為 `true`，則為 Windows (Active Directory) 使用者密碼（僅限 Windows）。
`encrypt`	否	`true`	配置是否始終使用 TLS，或僅在登入過程中配置。可選值：`true`（始終使用）、`false`（僅用於登入憑證）。
`integratedSecurity`	否		啟用 Windows 身分驗證（整合安全性）。可選值：`true`, `false`, `yes`, `no`。若設為 `true` 或 `yes` 且提供了 `username` 和 `password`，則透過 Windows Active Directory 進行登入。若未透過個別參數提供登入資訊，則使用目前已登入的 Windows 使用者登入伺服器。
`connectionLimit`	否	`num_cpus * 2 + 1`	連線池 (connection pool) 的最大大小（Prisma ORM v6 及更早版本）
`connectTimeout`	否	`5`	等待新連接的最長秒數。
`schema`	否	`dbo`	若架構 (schema) 名稱非預設值，則作為所有查詢的前綴。
`loginTimeout` `connectTimeout` `connectionTimeout`	否		等待登入成功的秒數。
`socketTimeout`	否		等待每個查詢成功的秒數。
`isolationLevel`	否		設定交易隔離層級。
`poolTimeout`	否	`10`	從連接池等待新連接的最長秒數。如果所有連接都在使用中，資料庫會在等待指定時間後返回 `PoolTimeout` 錯誤。
`ApplicationName` `應用程式名稱` （不區分大小寫）	否		設定連接的應用程式名稱。自 2.28.0 版本起可用。
`trustServerCertificate`	否	`false`	配置是否信任伺服器憑證。
`trustServerCertificateCA`	否		用於驗證伺服器憑證的憑證授權檔案路徑，用以取代系統憑證。必須為 `pem`、`crt` 或 `der` 格式。不能與 `trustServerCertificate` 參數同時使用。

Prisma ORM v7 連線池

在 Prisma ORM v7 中，驅動程式適配器是關聯式資料庫的預設選項。連接池由您提供的 Node.js 驅動程式（例如 mssql）處理，而非 Prisma 的連接 URL 參數。請參閱連接池指南以了解 v7 的預設值與配置。

使用整合安全性 (僅限 Windows)

以下範例使用目前已登入的 Windows 使用者來登入 Microsoft SQL Server。

sqlserver://:1433;database=sample;integratedSecurity=true;trustServerCertificate=true;

以下範例使用特定的 Active Directory 使用者來登入 Microsoft SQL Server。

sqlserver://:1433;database=sample;integratedSecurity=true;username=prisma;password=aBcD1234;trustServerCertificate=true;

連接到具名執行個體 (Named Instance)

以下範例使用整合安全性連接到 Microsoft SQL Server 的具名執行個體 (mycomputer\sql2019)。

sqlserver://mycomputer\sql2019;database=sample;integratedSecurity=true;trustServerCertificate=true;