连接到 Microsoft Azure SQL 数据库

下载 PHP 驱动程序

SQLSRV 和 PDO_SQLSRV 驱动程序使用完全限定的服务器名称以及连接选项中的连接选项,连接到以下 Azure 和 Fabric SQL 目标。 SQLSRV 采用选项数组;PDO_SQLSRV 接收数据源名称(DSN)、需要时的独立凭证参数和 PDO 属性。

目标 服务器名称形式 备注
Azure SQL 数据库 <server>.database.windows.net
Azure SQL 托管实例 你的实例的公共或私有端点 需要通过虚拟网络、虚拟专用网络 (VPN) 或公共终结点进行网络连接。
Azure Synapse Analytics (工作空间中的专用SQL pool) <workspace>.sql.azuresynapse.net 支持的 Transact-SQL(T-SQL)语句与 SQL Server 不同。 有关支持的语法,请参见 Synapse SQL文档。
Microsoft Fabric 中的 SQL 数据库 从数据库项的设置>连接字符串中复制服务器和数据库 使用SQL数据库连接,而不是它的SQL分析端点。 需要Microsoft Entra认证。 有关详细信息,请参阅连接到 Fabric SQL 数据库。
Microsoft Fabric 中的仓库 从Fabric门户复制仓库的SQL 连接字符串 将 Database 设置为仓库名称,并将 MultipleActiveResultSets 设置为 false。 需要Microsoft Entra认证。 有关详细信息,请参阅 仓库连接。

这两个 PHP 扩展默认都启用多重主动结果集(MARS)。 仓库不支持 MARS,所以在 SQLSRV 选项数组或 PDO_SQLSRV DSN 中明确禁用它。 Fabric 和 Warehouse 中的 SQL 数据库是独立产品;不要假设其中一个支持的功能,另一个也支持。

准备端点、身份和PHP主机

你的PHP进程需要对SQL端点的网络访问权限、支持的登录方式以及打开所选数据库的权限。 每个要求都要单独查看。 例如,打开防火墙端口并不会授予数据库访问权。

  1. 在运行PHP的机器或容器上安装PHP扩展和Microsoft ODBC驱动。 在这个流程中验证扩展,而不仅仅是在开发终端里。 更多信息请参见 “加载驱动程序”。
  2. 从目标的连接详情复制服务器和数据库。 不要包含 HTTPS URL 方案。 使用服务提供的主机名,以便证书验证检查的是预期的终结点。 Azure SQL 托管实例 公共端点可以包含非默认端口;保留提供的端口。
  3. 为你的PHP主机配置服务的网络访问。 对于专用终结点,请确认专用名称解析以及来自应用程序网络的路由。 公共防火墙规则不提供指向私有地址的路由。
  4. 选择PHP进程使用的身份。 对于 Azure 托管的应用程序,请启用其托管标识,并确定该标识是系统分配的还是用户分配的。 开发者的 Azure CLI 登录并不是应用的托管身份。
  5. 让数据库管理员授予该身份对所选数据库的访问权限,以及应用所需的最低权限。 对于仓库,还要检查 Fabric 项/工作区访问权限。 Azure 资源管理权限本身不会直接授予查询应用表的权限。
  6. 在应用程序的配置中设置 SQL_SERVER 和 SQL_DATABASE。 管理身份示例中不要存储密码。

这些示例是在不创建表的情况下验证连接。 通过此检查并不能证明该标识可以读取或写入你的应用程序架构。 在同一身份下分别测试实际操作。

使用无密码的 Microsoft Entra 认证

当你的托管环境暴露了一个托管身份端点,且SQL目标授予该身份访问权时,使用托管身份。 以下完整程序使用系统分配的托管身份。 它们不是工作站示例。 在配置好的 Azure 主机上运行它们,并使 SQL_SERVER 和 SQL_DATABASE 可供其 PHP 进程使用。

这两个程序都禁用了MARS系统,因此选择仓库时连接设置也适用。 他们一次只使用一个主动语句。 关于身份设置及其他认证方式,请参见使用 Microsoft Entra 认证连接。

将 SQL_DATABASE 设置为实际的数据库名称。 每个程序通过加倍闭合括号并将名称包裹在大括号中,为连接创建一个独立的转义值。 转义可以防止数据库名称中的特殊字符改变驱动读取连接设置的方式。 程序会保留原始名称,以检查 DB_NAME() 的结果。

SQLSRV

将该程序保存为 connect-azure-sqlsrv.php,并在配置好的主机上运行 php connect-azure-sqlsrv.php 。

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$conn = sqlsrv_connect($server, [
    'Database' => $databaseValue,
    'Authentication' => 'ActiveDirectoryMsi',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'MultipleActiveResultSets' => false,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [],
        ['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 !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

将这个独立程序保存为 connect-azure-pdo.php,并在配置好的主机上运行 php connect-azure-pdo.php 。 它设置了 PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE,因此 int 结果为 PHP int。 如果没有它,PDO_SQLSRV默认会将此列作为字符串返回。 PDO 编码是一个属性,而不是 SQLSRV CharacterSet 选项。

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$databaseValue;Authentication=ActiveDirectoryMsi;"
    . "Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;"
    . "MultipleActiveResultSets=false",
    null,
    null,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
        PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    ]
);

$stmt = null;
try {
    $stmt = $pdo->prepare(
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]
    );
    $stmt->execute();
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

如果 SQL_DATABASE 为 appdb,则每个程序都会输出:

Connected to appdb.

ActiveDirectoryMsi它不使用你本地的 Azure CLI 登录。 对于本地开发或持续集成(CI),请选择PHP扩展和ODBC驱动支持的认证方法。 你可以通过标识库获取 Microsoft Entra 访问令牌,并通过 AccessToken 提供该令牌。 使用令牌时,请省略用户名、密码和 Authentication 设置。 在 SQLSRV 连接选项数组或 PDO_SQLSRV DSN 中设置 AccessToken。 避免让令牌出现在源代码和日志中。 有关详细信息,请参阅 使用 Microsoft Entra 身份验证进行连接。

ActiveDirectoryServicePrincipal 使用客户端ID和客户端秘密;这不是无密码认证。 如果使用它,请从受保护的应用程序配置中读取机密。 SQL认证仅适用于支持它的目标;Fabric中的SQL数据库和仓库都不支持SQL认证。

根据你的环境调整身份验证配置

为每个连接使用一种身份验证机制。 切换到 AccessToken 时,不要保留旧的用户名、密码或 Authentication 设置。

Environment Configuration 责任
具有系统分配的托管标识的 Azure 主机 将 Authentication 设置为 ActiveDirectoryMsi。 不要提供用户名或密码。 ODBC 从主机的身份端点获取令牌。
具有用户分配的托管标识的 Azure 主机 将 Authentication 设置为 ActiveDirectoryMsi。 通过 SQLSRV 的 UID 选项或 PDO 的用户名参数提供该标识的 ID。 不要提供密码。 所需的ID取决于主机服务。 应用服务和容器实例使用客户端 ID;有关其他主机,请参阅 ODBC 标识指导。
带有外部令牌提供程序的工作站或 CI 获取SQL服务的令牌,然后设置 AccessToken。 不要写用户名、密码和 Authentication 设置。 您的应用程序或身份库获取并刷新令牌。 这两个PHP扩展都不会自动使用你的Azure CLI登录。
带有客户端秘密的服务负责人 将 Authentication 设置为 ActiveDirectoryServicePrincipal。 对于 SQLSRV,将 UID 设置为客户端 ID,将 PWD 设置为密钥。 对于PDO,将客户端ID和secret作为构造程序的用户名和密码参数传递。 保护并轮换机密。 这种方法并非无密码。
在支持它的目标实例上登录 SQL SQLSRV 使用 UID/PWD;PDO 使用构造函数参数 2 和 3。 目标端验证 SQL 凭证。 这个选项不适用于任何一款Fabric产品。

请求用于 SQL 服务的令牌,而不是用于 Azure 资源管理的令牌。 令牌的受众标识了接受该令牌的服务。 对于 Azure 公有云,请从标识库请求 https://database.windows.net/.default 作用域。 确认另一个云的相应资源。 将令牌作为字符串传递给 PHP 扩展;不要手动将其转换为 ODBC 访问令牌结构。

辅助角色持续运行时,令牌可能会过期。 在开启另一个连接前获取有效的令牌,并在运行较长时间的工作节点中根据需要刷新令牌。 切勿记录包含访问令牌的DSN。 有关 ODBC 认证的更多信息,请参见《使用 Microsoft Entra ID 配合 ODBC 驱动》。

加密和身份验证应分开进行

Encrypt=true 请求使用加密传输。 TrustServerCertificate=false 要求验证服务器证书,包括其标识。 Microsoft Entra认证确定了你的应用身份;它并不取代服务器证书验证。

使用 SQL 服务提供的终结点,并维护客户端操作系统的证书信任存储。 不要用IP地址替换主机名来绕过名称解析问题。 对于私有端点,在保留服务预期连接名称的同时,修复名称解析和路由。

LoginTimeout 限制连接的建立。 SQLSRV 的 QueryTimeout 和 PDO_SQLSRV 的 PDO::SQLSRV_ATTR_QUERY_TIMEOUT 适用于语句执行。 设置查询超时不会修复缺失的托管身份端点或错误的数据库用户。

按故障阶段排查

失效阶段 需要检查的事项
PHP 无法加载扩展 确认运行时版本、架构、扩展构建、ODBC 安装,以及应用程序进程所使用的 php.ini。
传输控制协议(TCP)连接超时 从 PHP 主机验证复制的终结点和端口、名称解析、防火墙规则、虚拟网络路由以及专用终结点配置。
证书验证失败 检查端点名称、证书链和客户端信任存储。 保持证书验证功能开启。
托管身份无法获取令牌 确认该身份在该主机上已启用,且其身份端点可用。 不要在普通笔记本电脑上测试 ActiveDirectoryMsi,并指望通过 Azure CLI 登录来满足该要求。
令牌认证失败 检查令牌的预期服务、到期时间、租户和身份。 确认该身份的数据库访问权限。 删除任意用户名、密码和 Authentication 设置。
登录成功,但选中的数据库无法打开 确认数据库名称,并确认其管理员已为预期标识创建或授予了访问权限。
连接打开,但应用查询失败 检查对象权限和目标支持的T-SQL特性。 连接测试并不能确立对应用程序架构的访问权限。
仓库会拒绝连接设置 在 SQLSRV 选项数组或 PDO DSN 中将 MultipleActiveResultSets 设置为 false,并使用 Microsoft Entra 认证。

SQLSRV 返回 false 并通过 sqlsrv_errors() 公开错误集合。 PDO 构造抛出 PDOException;示例还为语句失败启用异常。 立即在受限日志中捕获诊断信息,并将 SQLSRV 警告与错误区分开。 不要将原始诊断、令牌或连接信息返回给浏览器。

为中断连接做准备

服务可以在维护或故障切换期间断开空闲会话或中断操作。 ODBC 的空闲连接弹性和应用重试解决了不同的问题。 关于重试关键词和受控断开测试,请参见 空闲连接复原能力。

不要因为客户端失去连接而重播写入。 服务器可能在响应丢失前就已经提交了。 使用针对应用程序的重试策略和检测重复工作的方法。 在请求或作业完成时(包括错误路径),释放语句和连接句柄。 关于生命周期和池化行为,请参见 连接服务器。