Microsoft SQL Server

Microsoft SQL Server 資料來源聯結器將 Prisma ORM 連線到 Microsoft SQL Server 資料庫伺服器。

示例

要連線到 Microsoft SQL Server 資料庫，你需要在 Prisma schema 中配置一個 datasource 塊。

schema.prisma

datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

傳遞給 datasource 塊的欄位是：

• provider: 指定 sqlserver 資料來源聯結器。
• url: 指定 Microsoft SQL Server 資料庫的連線 URL。在這種情況下，使用了環境變數來提供連線 URL。

使用 node-mssql 驅動

從 v5.4.0 起，你可以將 Prisma ORM 與 JavaScript 生態系統中的資料庫驅動（而不是使用 Prisma ORM 的內建驅動）一起使用。你可以透過使用驅動介面卡來實現這一點。

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

本節解釋瞭如何將其與 Prisma ORM 和 @prisma/adapter-mssql 驅動介面卡一起使用。

1. 啟用 driverAdapters 預覽功能標誌

由於驅動介面卡目前處於預覽階段，你需要在 Prisma schema 中的 datasource 塊上啟用其功能標誌。

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

將功能標誌新增到 schema 後，重新生成 Prisma Client。

npx prisma generate

2. 安裝依賴項

接下來，安裝 Prisma ORM 用於 node-mssql 的驅動介面卡。

npm install @prisma/adapter-mssql

3. 使用驅動介面卡例項化 Prisma Client

最後，當你例項化 Prisma Client 時，需要將 Prisma ORM 驅動介面卡的一個例項傳遞給 PrismaClient 建構函式。

import { PrismaMssql } from '@prisma/adapter-mssql'
import { PrismaClient } from '@prisma/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

引數

引數名稱	必需	預設	註釋
database initial catalog	否	master	要連線到的資料庫。
username user uid userid	否 - 見註釋		SQL Server 登入名（例如 sa）或，如果 integratedSecurity 設定為 true（僅限 Windows），則為有效的 Windows (Active Directory) 使用者名稱。
password pwd	否 - 見註釋		SQL Server 登入名密碼或，如果 integratedSecurity 設定為 true（僅限 Windows），則為 Windows (Active Directory) 使用者名稱密碼。
encrypt	否	true	配置是否始終使用 TLS，或僅用於登入過程，可能的值：true（始終使用），false（僅用於登入憑據）。
integratedSecurity	否		啟用Windows 身份驗證（整合安全性），可能的值：true, false, yes, no。如果設定為 true 或 yes 並且 username 和 password 存在，則透過 Windows Active Directory 執行登入。如果未透過單獨的引數提供登入詳細資訊，則使用當前登入的 Windows 使用者登入到伺服器。
connectionLimit	否	num_cpus * 2 + 1	連線池的最大大小
connectTimeout	否	5	等待新連線的最大秒數
schema	否	dbo	如果 schema 名稱不是預設值，則作為字首新增到所有查詢中。
loginTimeout connectTimeout connectionTimeout	否		等待登入成功的最長秒數。
socketTimeout	否		等待每個查詢成功的最長秒數。
isolationLevel	否		設定事務隔離級別。
poolTimeout	否	10	等待連線池中新連線的最大秒數。如果所有連線都在使用中，資料庫將在等待給定時間後返回 PoolTimeout 錯誤。
ApplicationName 應用程式名稱 (不區分大小寫)	否		設定連線的應用程式名稱。自 2.28.0 版本起。
trustServerCertificate	否	false	配置是否信任伺服器證書。
trustServerCertificateCA	否		證書頒發機構檔案的路徑，用於替代系統證書以授權伺服器證書。必須是 pem、crt 或 der 格式。不能與 trustServerCertificate 引數一起使用。

使用整合安全性（僅限 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;

連線到命名例項

以下示例使用整合安全性連線到 Microsoft SQL Server 的命名例項（mycomputer\sql2019）。

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

Microsoft SQL Server 與 Prisma schema 之間的型別對映

有關按 Prisma ORM 型別組織的型別對映，請參閱Prisma schema 參考文件。

支援的版本

請參閱支援的資料庫。

限制和已知問題

Prisma Migrate 注意事項

Prisma Migrate 在 2.13.0 及更高版本中受支援，但存在以下注意事項：

資料庫 schema 名稱

SQL Server 沒有與 PostgreSQL 中熟悉的 SET search_path 命令等效的功能。這意味著當你建立遷移時，必須在連線 URL 中定義與生產資料庫使用的相同的 schema 名稱。對於大多數使用者來說，這是 dbo（預設值）。但是，如果生產資料庫使用另一個 schema 名稱，則所有遷移 SQL 必須手動編輯以反映生產環境或在建立遷移之前更改連線 URL（例如：schema=name）。

迴圈引用

當每個模型引用另一個模型，形成閉環時，模型之間可能出現迴圈引用。在使用 Microsoft SQL Server 資料庫時，如果關係的參照操作設定為 NoAction 以外的值，Prisma ORM 將顯示驗證錯誤。

有關更多資訊，請參閱SQL Server 中參照操作的特殊規則。

破壞性更改

某些遷移會引起比你預期更多的更改。例如：

• 新增或刪除 autoincrement()。這無法透過修改列來實現，而是需要重新建立表（包括所有約束、索引和外部索引鍵）並在表之間移動所有資料。
• 此外，無法從表中刪除所有列（PostgreSQL 或 MySQL 可以）。如果遷移需要重新建立所有表列，它也將重新建立表。

不支援共享預設值

在某些情況下，使用者可能希望將預設值定義為共享物件。

default_objects.sql

CREATE DEFAULT catcat AS 'musti';

CREATE TABLE cats (
    id INT IDENTITY PRIMARY KEY,
    name NVARCHAR(1000)
);

sp_bindefault 'catcat', 'dbo.cats.name';

使用儲存過程 sp_bindefault，預設值 catcat 可以在多個表中使用。Prisma ORM 管理預設值的方式是按表進行的。

default_per_table.sql

CREATE TABLE cats (
    id INT IDENTITY PRIMARY KEY,
    name NVARCHAR(1000) CONSTRAINT DF_cat_name DEFAULT 'musti'
);

最後一個示例，在內省時，會生成以下模型：

schema.prisma

model cats {
  id   Int     @id @default(autoincrement())
  name String? @default("musti")
}

而第一個示例則沒有內省到預設值。

schema.prisma

model cats {
  id   Int     @id @default(autoincrement())
  name String?
}

如果將 Prisma Migrate 與共享預設物件一起使用，則對它們的更改必須手動完成到 SQL。

資料模型限制

不能將具有 UNIQUE 約束和過濾索引的列用作外部索引鍵

Microsoft SQL Server 只允許在一個具有 UNIQUE 約束的列中包含一個 NULL 值。例如：

• 使用者表有一個名為 license_number 的列
• license_number 欄位具有 UNIQUE 約束
• license_number 欄位只允許一個 NULL 值

解決此問題的標準方法是建立一個過濾後的唯一索引，該索引排除 NULL 值。這允許你插入多個 NULL 值。如果你未在資料庫中建立索引，則嘗試使用 Prisma Client 向列中插入多個 null 值時會收到錯誤。

然而，建立索引使得無法在資料庫中將 license_number 用作外部索引鍵（或在相應的 Prisma Schema 中用作關係標量欄位）。

原生查詢注意事項

帶有 String @db.VarChar(n) 欄位 / VARCHAR(N) 列的原生查詢

在原生查詢中，String 查詢引數總是被編碼為 SQL Server 的 NVARCHAR(4000)（如果你的 String 長度小於等於 4000）或 NVARCHAR(MAX)。如果你將 String 查詢引數與型別為 String @db.VarChar(N)/VARCHAR(N) 的列進行比較，這可能導致 SQL Server 上的隱式轉換，從而影響索引效能並可能導致高 CPU 使用率。

例如：

model user {
  id Int @id
  name String @db.VarChar(40)
}

此查詢將受到影響。

await prisma.$queryRaw`SELECT * FROM user WHERE name = ${"John"}`

為避免此問題，我們建議你始終在原生查詢中手動將 String 查詢引數轉換為 VARCHAR(N)。

await prisma.$queryRaw`SELECT * FROM user WHERE name = CAST(${"John"} AS VARCHAR(40))`

這使得 SQL Server 能夠執行聚集索引查詢而不是聚集索引掃描。