连接服务器

下载 PHP 驱动程序

使用本指南打开连接,验证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 类型可以互换。

连接之前

  1. 安装支持的PHP运行时和Microsoft ODBC驱动,并加载你打算使用的PHP扩展。
  2. 检查运行你应用的PHP进程。 运行 php --ini 以查找命令行配置并 php -m 列出其加载的扩展。 SQLSRV 要求 sqlsrv。 PDO_SQLSRV需要 PDO 和 pdo_sqlsrv。 网络服务器可以使用与终端不同的 php.ini运行时和账户。
  3. 获取服务器地址、数据库名称和具有连接权限的身份凭据。 数据库登录并不会自动授予对所有表的权限。
  4. 配置网络访问和受信任的服务器证书。 这些程序会明确要求加密和证书验证。 使用证书上的主机名进行连接,而不要改用证书未涵盖的 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() 页面。
后续操作在已关闭的句柄上失败 在整个语句处理期间保持连接。 关闭连接后创建新连接;旧的句柄不会自行重新打开。

其他连接相关文章