使用本指南打开连接,验证PHP接收到的值,并在工作完成后释放连接。 这些程序使用 SQL Server 身份验证连接本地或远程的 SQL Server 测试数据库。 对于无密码的 Azure 和 Fabric 连接,可以使用 Connect to Azure SQL and Fabric SQL。
SQLSRV 接受服务器名称和作为关联数组提供的连接选项作为参数。 PDO_SQLSRV实现了PHP数据对象(PDO),并接受数据源名称(DSN)字符串、独立的凭证参数和一系列PDO属性。 两者都使用 Microsoft ODBC Driver for SQL Server。 一个可与一个 API 配合使用的连接,并不意味着另一个 API 的选项名称或 PHP 类型可以互换。
连接之前
- 安装支持的PHP运行时和Microsoft ODBC驱动,并加载你打算使用的PHP扩展。
- 检查运行你应用的PHP进程。 运行
php --ini以查找命令行配置并php -m列出其加载的扩展。 SQLSRV 要求sqlsrv。 PDO_SQLSRV需要PDO和pdo_sqlsrv。 网络服务器可以使用与终端不同的php.ini运行时和账户。 - 获取服务器地址、数据库名称和具有连接权限的身份凭据。 数据库登录并不会自动授予对所有表的权限。
- 配置网络访问和受信任的服务器证书。 这些程序会明确要求加密和证书验证。 使用证书上的主机名进行连接,而不要改用证书未涵盖的 IP 地址进行连接。
在PHP进程的环境中设置这些变量,使用你的shell、开发工具或托管配置。 不要提交密码文件或输出环境变量。
| 变量 | Value |
|---|---|
SQL_SERVER |
服务器主机名称,可选地以 tcp: 为前缀,后接 ,<port>。 |
SQL_DATABASE |
一个现有的数据库,你的登录用户可以访问。 |
SQL_USER |
一个 SQL Server 登录名。 |
SQL_PASSWORD |
该登录名的密码通过受保护的配置提供。 |
读取服务器和数据库设置时,是基于可信应用配置,而非网页请求参数。 PDO的例子是把这些设置放在DSN里的。 将其连接关键字置于应用程序控制之下。
把实际的数据库名称、用户名和密码存储在环境变量里,不用自己添加或加倍大括号。 这两个 PHP 扩展即使在 SQLSRV 数组选项和 PDO 构造参数中也需要类似 ODBC 的转义:将每个右大括号加倍,并将值用大括号括起来。 每个程序在将这些值传递给驱动程序之前,都会先执行一次此操作。 最外层花括号保留值开头和结尾的字面花括号字符,并防止数据库名称内的分号分隔 PDO DSN 设置。 这种转义与 Transact-SQL(T-SQL)参数绑定是分开的。
用 SQLSRV 打开、查询并关闭
将该程序保存为 connect-sqlsrv.php,并运行 php connect-sqlsrv.php。 它执行 T-SQL 查询时不创建表或更改数据。
CharacterSet 选择 UTF-8 作为字符数据;它不会改变数据库的列类型或排序方式。
<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException("Set $name before running this example.");
}
$config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
$config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
'Database' => $config['SQL_DATABASE'],
'UID' => $config['SQL_USER'],
'PWD' => $config['SQL_PASSWORD'],
'Encrypt' => true,
'TrustServerCertificate' => false,
'LoginTimeout' => 30,
'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
$sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
. "CAST(NULL AS int) AS Missing";
$stmt = sqlsrv_query($conn, $sql, [], ['QueryTimeout' => 30]);
if ($stmt === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
if ($row !== ['Value' => 42, 'Label' => "caf\u{00e9}", 'Missing' => null]) {
throw new RuntimeException('Unexpected SQLSRV values or PHP types.');
}
echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
if (is_resource($stmt)) {
sqlsrv_free_stmt($stmt);
}
sqlsrv_close($conn);
}
预期输出:
{"Value":42,"Label":"caf\u00e9","Missing":null}
连接和语句是 PHP 资源,是你传递给 sqlsrv_* 函数的句柄。 在使用任一句柄之前,请检查 false。 失败后立即检索 sqlsrv_errors() ,因为后续的 SQLSRV 调用可以替换错误集合。
SQLSRV_FETCH_ASSOC 返回一个以列名为键的关联数组。
SQLSRV_FETCH_NUMERIC 返回基于零的数字键;默认 SQLSRV_FETCH_BOTH 包含两种形式。 对于 sqlsrv_fetch_array(),null 表示没有更多的行,false 表示错误。 行内的 SQL NULL 是 PHP null;这并不意味着该行缺失。 区分这些数值时使用 === 。
开启、查询并关闭 PDO_SQLSRV
将这个独立程序保存为 connect-pdo.php,并在相同环境下运行 php connect-pdo.php 。
sqlsrv: 选择PDO_SQLSRV,而不是 PHP 的通用 PDO_ODBC 驱动。
<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException("Set $name before running this example.");
}
$config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
$config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
"sqlsrv:Server=$server;Database=$database;Encrypt=true;"
. "TrustServerCertificate=false;LoginTimeout=30",
$config['SQL_USER'],
$config['SQL_PASSWORD'],
[
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
]
);
$stmt = null;
try {
$sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
. "CAST(NULL AS int) AS Missing";
$stmt = $pdo->prepare($sql, [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]);
$stmt->execute();
$row = $stmt->fetch();
if ($row !== ['Value' => '42', 'Label' => "caf\u{00e9}", 'Missing' => null]) {
throw new RuntimeException('Unexpected PDO_SQLSRV values or PHP types.');
}
echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
$stmt = null;
$pdo = null;
}
预期输出:
{"Value":"42","Label":"caf\u00e9","Missing":null}
PDO_SQLSRV默认将该 整数 列作为PHP字符串返回。 要请求支持的数值列的 PHP 数值类型,请设 PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE 为 true。 不要对小数类型值随意使用 PHP 类型转换;浮点转换可能会丢失精度。
PDO 属性是连接或语句对象上的设置。
PDO::ATTR_ERRMODE 与 PDO::ERRMODE_EXCEPTION 一起会使数据库操作失败时抛出 PDOException。 无论该设置如何,连接构造在失败时都会抛出异常。
PDO::FETCH_ASSOC 给出命名键, PDO::FETCH_NUM 给出基于零的数值键,且 PDO::FETCH_BOTH 两者皆给出。
fetch() 在结果末尾返回 false;行内的 SQL NULL 值仍为 PHP null。
这些命令行程序会在失败时停止执行。 在网页应用中,捕捉处理请求的代码中的异常。 在受保护日志中记录诊断细节,并返回通用错误响应。 不要向浏览器发送 sqlsrv_errors()、异常堆栈跟踪、连接字符串或令牌。
选择身份验证模式
| 模式 | 用于 | 请参阅 |
|---|---|---|
| SQL Server 身份验证 | 当 Microsoft Entra ID 不可用时,本地 SQL Server、容器和 Azure SQL | 使用 SQL Server 认证连接 |
| 集成认证(连接设置中没有用户名或密码) | Windows 标识,或为 Kerberos 配置的 Linux/macOS 客户端 | 使用 Windows 身份验证连接 |
Microsoft Entra ID (Authentication 或 AccessToken keyword) |
为 Microsoft Entra ID 配置的 Azure SQL 和 Fabric SQL 目标 | 使用 Microsoft Entra 身份验证进行连接 |
对于 SQL 身份验证,SQLSRV 在其连接选项数组中使用 UID 和 PWD。 PDO_SQLSRV 将用户名和密码作为 new PDO() 的第二个和第三个参数传入,而不是作为 DSN 关键字。 对于访问令牌,SQLSRV 在选项数组中采用 AccessToken,而 PDO_SQLSRV 在 DSN 中采用它。
如果省略用户名、密码、Authentication 和 AccessToken,两个驱动程序都会通过 Trusted_Connection=Yes 向 ODBC 请求集成身份验证。 在 Linux 和 macOS 上,该请求需要有效的 Kerberos 工单和 ODBC 集成认证配置。 它不会允许任意本地账户访问远程服务器。
配置连接及其语句
连接设置适用于你打开的会话。 语句设置适用于特定的查询。 当应用需要除默认值外的值时,明确设置超时和结果类型。
| Purpose | SQLSRV | PDO_SQLSRV | 行为负责人 |
|---|---|---|---|
| 端点与数据库 | 服务器参数和 Database 选项。 |
Server 以及 Database DSN关键词。 |
ODBC 和 SQL 目标。 |
| SQL 凭据 |
UID 和 PWD 选项。 |
构造器用户名和密码参数。 | 扩展凭证处理和服务器认证。 |
| Microsoft Entra 身份验证 |
Authentication 选项,或者单独 AccessToken 选项。 |
Authentication 或 AccessToken DSN关键字,对于外部令牌,省略凭据。 |
ODBC认证;应用程序获取外部令牌。 |
| Encryption |
Encrypt => true。 |
Encrypt=true 在DSN中。 |
ODBC 传输安全。 |
| 证书验证 |
TrustServerCertificate => false。 |
TrustServerCertificate=false 在DSN中。 |
ODBC 以及操作系统的证书信任配置。 |
| 连接建立超时 |
LoginTimeout 连接(秒)。 |
LoginTimeout DSN 关键词,单位:秒。 |
ODBC。 这不是语句执行超时的问题。 |
| 查询超时 |
QueryTimeout 语句选项(秒)。 |
PDO::SQLSRV_ATTR_QUERY_TIMEOUT,位于连接或语句上。 |
扩展和 ODBC 语句处理。 |
| 字符编码 |
CharacterSet => 'UTF-8' 连接选项。 |
PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8。 |
PHP 扩展转换。 PDO_SQLSRV默认为 UTF-8;SQLSRV 默认为系统编码。 |
| 日期和时间对象 |
ReturnDatesAsStrings 默认处于 false 状态,因此日期和时间列返回 DateTime 对象。 |
默认情况下使用字符串;使用 PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE 请求对象。 |
PHP 扩展类型的转换。 |
| 多个活动的结果集 (MARS) |
MultipleActiveResultSets 连接选项。 |
MultipleActiveResultSets DSN关键词。 |
ODBC 和目标支持。 这两个扩展默认启用;在 Fabric 中的仓库中禁用它。 |
| 空闲恢复 |
ConnectRetryCount 以及 ConnectRetryInterval 连接选项。 |
同样的DSN关键词。 | ODBC。 它们不会重试任意的应用程序操作。 |
有关关键词、允许值和默认值的完整列表,请参见 连接选项。 不要将 CharacterSet、QueryTimeout 或 PDO:: 常量名放入 PDO DSN。
管理连接生命周期
当请求或作业需要数据库工作时,先打开连接。 在整个请求或任务中重复使用它,完成后再释放它。 不要每一行都连接和断开。 在长时间运行的辅助角色中,请在接受下一个作业之前释放语句并完成每个事务。
SQLSRV 在关闭连接时会关闭相关语句对象。 提前显式释放语句可以释放资源而不终止连接。 对于 PDO,分配 $pdo = null 只会移除该变量的引用。 A PDOStatement 或其他变量仍然可以保持连接。 也要释放这些引用。
closeCursor() 释放待处理结果以便复用该语句;它不是连接关闭方法。
这两个 API 都以自动提交模式启动:除非你显式开始事务,否则成功执行的语句会自行提交,无需应用程序另行提交。 对于一组必须共同成功或失败的写入,使用 sqlsrv_begin_transaction() 或 $pdo->beginTransaction(),然后显式提交或回滚。 关闭带有未决事务的连接会尝试回滚,而不是提交。 不要依赖关闭时的清理来实现你的事务策略。 有关完整示例,请参阅执行事务。
释放 PHP 连接句柄不一定会关闭其物理网络连接。 ODBC 池可能会保留它以便复用。 池化并不是无限期保留PHP资源的理由,而且PDO_SQLSRV不支持 PDO::ATTR_PERSISTENT => true。 关于平台特定的池化配置,请参见 连接池。
将指南应用到你的SQL目标上
在受支持的 SQL 目标上,句柄、获取和清理模式适用于这两个扩展。 连接端点、认证、网络访问和SQL能力各不相同。
| 目标 | 适应 |
|---|---|
| SQL Server | 这些程序使用 SQL 登录名。 在配置PHP进程身份时,集成认证也是另一种选择。 |
| Azure SQL 数据库 | 使用逻辑服务器主机名和显式数据库。 在这些程序中,建议使用Microsoft Entra认证,而不是SQL凭证。 |
| Azure SQL 托管实例 | 使用实例端点及其网络访问要求。 不要假设你的工作站可以访问专用终结点。 |
| Azure Synapse Analytics | 使用 SQL 池终结点,并在改编创建或修改对象的查询之前,检查其 T-SQL 支持情况。 |
| Microsoft Fabric 中的 SQL 数据库 | 使用其数据库连接信息和 Microsoft Entra 认证。 不要改用 SQL 分析终结点。 |
| Microsoft Fabric 中的仓库 | 使用其仓库端点和数据库,Microsoft Entra认证,以及 MultipleActiveResultSets=false。 |
关于服务特定的设置,请参见 Azure 和 Fabric 连接。
排查连接问题
从失败的步骤开始。 成功的传输控制协议(TCP)检查并不证明认证或证书验证成功。
| 症状 | 检查 |
|---|---|
Call to undefined function sqlsrv_connect() |
正在执行的PHP进程没有加载 sqlsrv。 检查它的 php.ini 和启动警告。 |
PDO报告 could not find driver |
确认 pdo_sqlsrv 已加载在该进程中,并确认 sqlsrv 出现在 PDO::getAvailableDrivers() 中。 |
| 找不到ODBC驱动 | 安装 Microsoft ODBC 驱动并检查其注册和体系结构。 安装PHP扩展并不会安装ODBC。 |
| 连接超时或服务器未找到 | 检查服务器名称、端口、名称解析、路由、防火墙规则,以及 SQL Server 是否监听 TCP。 |
| 证书链或主机名验证失败 | 安装正确的信任链,并使用证书的主机名称。 不要把 TrustServerCertificate=true 当作生产环境修复。 |
| 登录失败或数据库无法打开 | 检查认证模式、数据库名称、登录/用户映射和权限。 省略凭证表示请求使用集成身份验证;它不会选择 SQL 身份验证。 |
| 终端成功,但 Web 请求失败 | 比较PHP运行时、加载扩展、进程身份、环境变量和网络访问。 不要暴露包含配置细节的公共 phpinfo() 页面。 |
| 后续操作在已关闭的句柄上失败 | 在整个语句处理期间保持连接。 关闭连接后创建新连接;旧的句柄不会自行重新打开。 |