连接选项

  • 项目

下载 PHP 驱动程序

本主题列出了关联阵列中允许的选项（当在 SQLSRV 驱动程序中使用 sqlsrv_connect 时）或数据源名称 (dsn) 中允许的关键字（当在PDO_SQLSRV 驱动程序中使用 PDO::__construct 时）。

连接选项表

密钥 值 说明 默认
AccessToken 字符串 从 OAuth JSON 响应中提取的 Microsoft Entra 访问令牌的字节字符串。

连接字符串不得包含用户 ID、密码或 Authentication 关键字。 有关详细信息，请参阅使用 Microsoft Entra 身份验证进行连接。		 未设置。
APP 字符串 指定跟踪中所使用的应用程序名称。 未设置。
ApplicationIntent 字符串 连接到服务器时声明应用程序工作负荷类型。 可能的值为 ReadOnly 和 ReadWrite 。

有关 Always On 可用性组的 Microsoft Drivers for PHP for SQL Server 支持的详细信息，请参阅高可用性、灾难恢复的支持。		 ReadWrite
AttachDBFileName 字符串 指定服务器应附加的数据库文件。 未设置。
身份验证 以下字符串之一：

SqlPassword

ActiveDirectoryPassword

ActiveDirectoryMsi

ActiveDirectoryServicePrincipal		 指定身份验证模式。

有关详细信息，请参阅使用 Microsoft Entra 身份验证进行连接。		 未设置。
CharacterSet

（在 PDO_SQLSRV 驱动程序中不受支持）		 字符串 指定用于将数据发送到服务器的字符集。

可能的值为 SQLSRV_ENC_CHAR 和 UTF-8。 有关详细信息，请参阅操作说明：使用内置 UTF-8 支持发送和检索 UTF-8 数据。		 SQLSRV_ENC_CHAR
ColumnEncryption 以下字符串之一：

已启用

已禁用

用于标识证明协议和 URL 来证明 enclave 的字符串		 指定 Always Encrypted 功能是否已启用。 如果指定了证明协议和 URL，则只要满足此处所述的其他要求，就会启用具有安全 enclave 的 Always Encrypted。 已禁用
ConnectionPooling 1 或 true ，表示启用连接池。

0 或 false ，表示禁用连接池。		 指定是否从连接池分配连接（1 或 true 表示是，0 或 false 表示否） 1。 true (1)
ConnectRetryCount 介于 0 和 255 之间（含限值）的整数 在连接断开时最多尝试重新建立多少次连接后放弃。 在连接断开时，默认尝试一次重新建立连接。 值 0 表示不会尝试重新建立连接。 1
ConnectRetryInterval 介于 1 和 60 之间（含限值）的整数 尝试重新建立连接的时间间隔（以秒为单位）。 应用程序在检测到连接断开后立即尝试重新连接，然后在等待 ConnectRetryInterval 秒后重试。 如果 ConnectRetryCount 等于0，则忽略此关键字。 10
数据库 字符串 指定用于建立连接的数据库名称2。 供登录时使用的默认数据库。
DecimalPlaces

（在 PDO_SQLSRV 驱动程序中不受支持）		 介于 0 和 4 之间（含 0 和 4）的整数 指定设置提取的 Money 值格式时的小数位数。

仅当 FormatDecimals 为 true 时此选项才起作用。 将忽略任何负整数或大于 4 的值。		 默认精度和确定位数
驱动程序 字符串 指定用于与 SQL Server 进通信的 Microsoft ODBC 驱动程序。

可能的值包括：
ODBC Driver 18 for SQL Server
适用于 SQL Server 的 ODBC 驱动程序 17
ODBC Driver 13 for SQL Server
ODBC Driver 11 for SQL Server（仅限 Windows）。		 如果 Driver 关键字未指定，Microsoft Drivers for PHP for SQL Server 会尝试在系统中查找受支持的一个或多个 Microsoft ODBC 驱动程序，从最新版 ODBC 开始查找。
加密 1 或 true ，表示启用加密。

0 或 false ，表示禁用加密。		 指定是加密（1 或 true）还是解密（0 或 false）与 SQL Server 的通信3 。 false (0)
Failover_Partner 字符串 指定要在主服务器不可用时使用的服务器和数据库镜像的实例（如果已启用且已配置）。

结合使用 Failover_Partner 与 MultiSubnetFailover 存在一些限制。 有关详细信息，请参阅 对高可用性和灾难恢复的支持。

Linux 或 macOS 不支持此选项，因为 Linux 或 macOS 上的 ODBC 驱动程序不支持数据库镜像。 请改用 AlwaysOn 可用性组，并设置 MultiSubnetFailover 和 TransparentNetworkIPResolution 选项。		 未设置。
FormatDecimals

（在 PDO_SQLSRV 驱动程序中不受支持）		 1 或 true （为提取的十进制字符串设置格式）。

0 或 false （默认十进制格式设置行为）。		 指定是否在合适时向十进制字符串添加前导零，并启用用于设置 Money 类型格式的 DecimalPlaces 选项。 如果保留 false，使用的默认行为是返回精确的精度，并为小于 1 的值省略前导零。

有关详细信息，请参阅设置十进制字符串和 Money 值格式。		 false (0)
KeyStoreAuthentication KeyVaultPassword

KeyVaultClientSecret		 用于访问 Azure Key Vault 的身份验证方法。 控制与 KeyStorePrincipalId 和 KeyStoreSecret 一起使用的凭据类型。 有关详细信息，请参阅使用 Azure Key Vault。 未设置。
KeyStorePrincipalId 字符串 试图访问 Azure Key Vault 的帐户的标识符。

如果 KeyStoreAuthentication 为 KeyVaultPassword，则此值须为 Microsoft Entra 用户名。

如果 KeyStoreAuthentication 是 KeyVaultClientSecret，此值必须为应用程序客户端 ID。		 未设置。
KeyStoreSecret 字符串 试图访问 Azure Key Vault 的帐户的凭据密码。

如果 KeyStoreAuthentication 为 KeyVaultPassword，则此值须为 Microsoft Entra 密码。

如果 KeyStoreAuthentication 是 KeyVaultClientSecret，此值必须为应用程序客户端机密。		 未设置。
语言 字符串 指定服务器返回的消息的语言。 sys.syslanguages 表中列出了可用语言。

此选项既不会影响驱动程序本身使用的语言，因为驱动程序目前只有英语版，也不会影响基础 ODBC 驱动程序的语言，因为驱动程序的语言是由客户端系统上安装的本地化版本确定。 因此，更改此设置可能会导致消息以不同的语言返回，具体视来自 PHP 驱动程序、ODBC 驱动程序还是 SQL Server 而定。		 默认为 SQL Server 中设置的语言。
LoginTimeout 整数（SQLSRV 驱动程序）

字符串（PDO_SQLSRV 驱动程序）		 指定在连接尝试失败前等待的秒数。 无超时。
MultipleActiveResultSets 1 或 true ，表示使用多个活动的结果集。

0 或 false ，表示禁用多个活动的结果集。		 禁用或显式启用支持多重活动结果集 (MARS)。

有关详细信息，请参阅如何：禁用多重活动结果集 (MARS)。		 true (1)
MultiSubnetFailover 字符串 在连接到 SQL Server 2012 (11.x) 可用性组侦听器或 SQL Server 2012 (11.x) 故障转移群集实例的可用性组侦听器时，应始终指定 multiSubnetFailover=yes。 multiSubnetFailover=yes 配置 Microsoft Drivers for PHP for SQL Server，以提供对（当前）活动服务器的更快检测和连接。 可能的值为 Yes 和 No。

有关 Always On 可用性组的 Microsoft Drivers for PHP for SQL Server 支持的详细信息，请参阅高可用性、灾难恢复的支持。		 否
PWD

（在 PDO_SQLSRV 驱动程序中不受支持）		 字符串 指定与使用 SQL Server 身份验证进行连接时使用的用户 ID 关联的密码4。 未设置。
QuotedId 1 或 true，表示使用 SQL-92 规则 。

0 或 false ，表示使用旧规则。		 指定对带引号的标识符是使用 SQL-92 规则（1 或 true）还是使用旧的 Transact-SQL 规则（0 或 false） 。 true (1)
ReturnDatesAsStrings

（在 PDO_SQLSRV 驱动程序中不受支持）		 1 或 true ，表示以字符串的形式返回日期和时间类型。

0 或 false ，表示以 PHP DateTime 的形式返回日期和时间类型。		 以字符串或 PHP 类型的形式检索日期和时间类型（datetime、smalldatetime、date、time、datetime2 和 datetimeoffset）。 有关详细信息，请参阅操作说明：使用 SQLSRV 驱动程序检索日期和时间类型作为字符串。

如果使用的是 PDO_SQLSRV 驱动程序，除非另行指定，否则日期以字符串的形式返回。 有关详细信息，请参阅操作说明：使用 PDO_SQLSRV 驱动程序检索日期和时间类型作为 PHP Datetime 对象。		 false
可滚动 字符串 “缓冲”表示你希望使用客户端（缓冲）游标，这将允许你将整个结果集缓存到内存。 有关详细信息，请参阅游标类型（SQLSRV 驱动程序）。 只进游标
服务器

（在 SQLSRV 驱动程序中不受支持）		 字符串 要连接到的 SQL Server 实例。

你还可以指定要连接到 Always On 可用性组的虚拟网络名称。 有关 Always On 可用性组的 Microsoft Drivers for PHP for SQL Server 支持的详细信息，请参阅高可用性、灾难恢复的支持。		 Server 是必需的关键字（尽管它不必是连接字符串中的第一个关键字）。 如果服务器名称未传递给该关键字，将尝试连接到本地实例。

传递给 Server 的值可以是 SQL Server 实例的名称，也可以是该实例的 IP 地址。 你可以选择指定一个端口号（例如 sqlsrv:server=(local),1033）。

从 Microsoft Drivers for PHP for SQL Server 的版本 3.0 开始，你还可以指定带有 server=(localdb)\instancename的 LocalDB 实例。 有关详细信息，请参阅 LocalDB 支持。
TraceFile 字符串 指定用于跟踪数据的文件的路径。 未设置。
TraceOn 1 或 true ，表示启用跟踪。

0 或 false ，表示禁用跟踪。		 指定对正在建立的连接是启用（1 或 true）还是禁用（0 或 false）ODBC 跟踪 。 false (0)
TransactionIsolation SQLSRV 驱动程序使用以下值：

SQLSRV_TXN_READ_UNCOMMITTED

SQLSRV_TXN_READ_COMMITTED

SQLSRV_TXN_REPEATABLE_READ

SQLSRV_TXN_SNAPSHOT

SQLSRV_TXN_SERIALIZABLE

PDO_SQLSRV 驱动程序使用以下值：

PDO::SQLSRV_TXN_READ_UNCOMMITTED

PDO::SQLSRV_TXN_READ_COMMITTED

PDO::SQLSRV_TXN_REPEATABLE_READ

PDO::SQLSRV_TXN_SNAPSHOT

PDO::SQLSRV_TXN_SERIALIZABLE		 指定事务隔离级别。

有关事务隔离的详细信息，请参阅 SQL Server 文档中的 设置事务隔离级别。		 SQLSRV_TXN_READ_COMMITTED

或

PDO::SQLSRV_TXN_READ_COMMITTED
TransparentNetworkIPResolution 启用或禁用 如果第一个解析的主机名 IP 未响应，且存在多个与主机名关联的 IP，就会影响连接序列。

它与 MultiSubnetFailover 交互，以提供不同的连接序列。 有关详细信息，请参阅透明网络 IP 解析或使用透明网络 IP 解析。		 已启用
TrustServerCertificate 1 或 true ，表示信任证书。

0 或 false ，表示不信任证书。		 指定客户端是应信任（1 或 true）还是应拒绝（0 或 false）自签名的服务器证书 。 false (0)
UID

（在 PDO_SQLSRV 驱动程序中不受支持）		 字符串 指定在使用 SQL Server 身份验证进行连接时要使用的用户 ID4。 未设置。
WSID 字符串 指定用于跟踪的计算机的名称。 未设置。

  1. 在 Linux 和 macOS 中，不能使用 ConnectionPooling 属性来启用/禁用连接池。 请参阅连接池 (Microsoft Drivers for PHP for SQL Server)。

  2. 所有在已建立的连接上执行的查询都是针对 Database 属性指定的数据库进行。 不过，如果用户具有相应权限，则可以使用完全限定的名称访问其他数据库中的数据。 例如，如果 master 数据库使用 Database 连接属性进行设置，仍可以使用完全限定的名称执行可访问 AdventureWorks.HumanResources.Employee 表的 Transact-SQL 查询。

  3. 因为加密数据需要计算开销，所以启用 Encryption 可能会影响某些应用程序的性能。

  4. 使用 SQL Server 身份验证进行连接时，必须同时设置 UID 和 PWD 属性。

许多支持的键都是 ODBC 连接字符串属性。 有关 ODBC 连接字符串的信息，请参阅 将连接字符串关键字用于 SQL Native Client。

另请参阅

连接到服务器