跳至主要内容

Microsoft SQL Server

Microsoft SQL Server 数据源连接器将 Prisma ORM 连接到一个 Microsoft SQL Server 数据库服务器。

示例​

要连接到 Microsoft SQL Server 数据库，你需要在你的 Prisma 架构 中配置一个 datasource 块

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

传递给 datasource 块的字段是

连接详细信息​

用于连接到 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如果模式名称不是默认值，则作为所有查询的前缀添加。
  • 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://127.0.0.1:1433;database=sample;integratedSecurity=true;trustServerCertificate=true;

以下示例使用特定的 Active Directory 用户登录 Microsoft SQL Server

sqlserver://127.0.0.1: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 架构的类型映射​

有关按 Prisma ORM 类型组织的类型映射，请参阅 Prisma 架构参考 文档。

支持的版本​

请参见 支持的数据库。

限制和已知问题​

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 中用作关系标量字段）