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 的内置驱动程序）一起使用。您可以通过使用 驱动程序适配器 来实现。

对于 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

参数

参数名称	必需	默认值	注释
数据库 初始目录	否	master	要连接的数据库。
用户名 用户 uid 用户ID	否 - 请参阅评论		SQL Server 登录（例如 sa）或 有效的 Windows (Active Directory) 用户名，如果 integratedSecurity 设置为 true（仅限 Windows）。
密码 pwd	否 - 请参阅评论		SQL Server 登录密码 或 Windows (Active Directory) 用户名密码，如果 integratedSecurity 设置为 true（仅限 Windows）。
加密	否	true	配置是否始终使用 TLS，或仅用于登录过程，可能的值：true（始终使用），false（仅用于登录凭据）。
集成安全	否		启用 Windows 身份验证（集成安全），可能的值：true、false、yes、no。如果设置为 true 或 yes 且 username 和 password 存在，则通过 Windows Active Directory 执行登录。如果未通过单独的参数提供登录详细信息，则使用当前登录的 Windows 用户登录到服务器。
连接限制	否	num_cpus * 2 + 1	连接池的最大大小（Prisma ORM v6 及更早版本）
连接超时	否	5	等待新连接的最大秒数
schema	否	dbo	如果架构名称不是默认值，则添加为所有查询的前缀。
登录超时 连接超时 连接超时	否		等待登录成功的秒数。
套接字超时	否		等待每个查询成功的秒数。
隔离级别	否		设置事务隔离级别。
池超时	否	10	从连接池中等待新连接的最大秒数。如果所有连接都在使用中，数据库将在等待给定时间后返回 PoolTimeout 错误。
应用程序名称 应用程序名称 （不区分大小写）	否		设置连接的应用程序名称。自版本 2.28.0 起。
信任服务器证书	否	false	配置是否信任服务器证书。
信任服务器证书 CA	否		证书颁发机构文件的路径，用于代替系统证书来授权服务器证书。必须是 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;

连接到命名实例

以下示例使用集成安全连接到 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 及更高版本中受支持，但有以下注意事项

数据库架构名称

SQL Server 没有类似于 PostgreSQL 中熟悉的 SET search_path 命令。这意味着在创建迁移时，您必须在连接 URL 中定义与生产数据库使用的架构名称相同的名称。对于大多数用户来说，这是 dbo（默认值）。但是，如果生产数据库使用另一个架构名称，则所有迁移 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 值。如果您不在数据库中创建索引，则尝试将多个 null 值插入到具有 Prisma Client 的列中时，将会收到错误。

但是，创建索引使得无法在数据库中使用 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 能够执行聚集索引查找而不是聚集索引扫描。