連接伺服器

下載 PHP 驅動程式

使用本指南開啟連線,驗證 PHP 收到的值,並在工作完成後釋放連線。 這些程式針對本機或遠端的 SQL Server 測試資料庫使用 SQL Server 驗證。 對於無密碼的 Azure 和 Fabric 連線,請使用 連線到 Azure SQL 和 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。 Web 伺服器可以使用與終端機不同的 php.ini、執行時和帳號。
  3. 取得伺服器地址、資料庫名稱及具有連線權限的身分。 資料庫登入帳號不會自動授權每個資料表。
  4. 設定網路存取權限和受信任的伺服器憑證。 這些程式會明確要求加密與憑證驗證。 請依憑證上的主機名稱連接,而不要以憑證未涵蓋的 IP 位址取代該主機名稱。

在 PHP 行程的環境中,使用你的 shell、開發工具或主機設定來設定這些變數。 不要提交密碼檔或輸出環境變數。

變數 Value
SQL_SERVER 伺服器主機名稱,可選擇以 tcp: 為前綴,後接 ,<port>。
SQL_DATABASE 一個現有的資料庫,您的登入帳號可以存取。
SQL_USER 一個 SQL Server 登入帳戶。
SQL_PASSWORD 該登入帳號的密碼,透過受保護設定提供。

讀取伺服器和資料庫設定時,是從受信任的應用程式設定中取得,而非網頁請求參數。 PDO 範例中將這些設定放在 DSN 中。 保持其連線關鍵字在應用程式控制之下。

將實際的資料庫名稱、使用者名稱和密碼存入環境變數,無需自行加入或重複大括號。 這兩個 PHP 擴充甚至需要 ODBC 風格的轉義,即使是 SQLSRV 陣列選項和 PDO 建構參數:將每個右大括號寫成兩個,值則以大括號包覆。 每個程式在將這些值傳給驅動程式前,先執行一次此操作。 外大括號保留值開頭和結尾的字面大括號,並防止資料庫名稱內的分號分隔 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_* 函式的 handle。 使用任何一個把手前都要先檢查是否有 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()、例外狀況追蹤、連線字串或權杖。

選擇驗證模式

Mode 用途 看!
SQL Server 認證 當 Microsoft Entra ID 不可用時,使用本地 SQL Server、容器與 Azure SQL 使用 SQL Server 認證連接
整合驗證(連線設定中沒有使用者名稱或密碼) Windows 身分識別,或為 Kerberos 設定的 Linux/macOS 用戶端 使用 Windows 驗證連線
Microsoft Entra ID(Authentication 或 AccessToken 關鍵字) 已設定為使用 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 statement 選項,以秒為單位。 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 中的 Warehouse 停用它。
閒置恢復 ConnectRetryCount 以及 ConnectRetryInterval 連接選項。 同樣的 DSN 關鍵字。 ODBC。 它們不會重試任意應用程式作業。

完整關鍵字清單、允許值與預設值,請參見 連線選項。 不要在 PDO DSN 中放置 CharacterSet、QueryTimeout 或 PDO:: 常數名稱。

管理連線存留期

當請求或工作需要資料庫工作時,請開啟連線。 在整個請求或工作過程中重複使用它,完成後再釋放它。 不要每列都連線與中斷連線。 在長時間運行的 worker 中,先釋放 statement 並完成每一筆交易,然後再接受下一個工作。

當你關閉 SQLSRV 的連線時,SQLSRV 會關閉相關的陳述式。 明確提前釋放 statement 會釋放資源,但連線不會中斷。 對於 PDO,指派 $pdo = null 只會移除該變數的參考。 某個 PDOStatement 或其他變數仍可保留連結。 也要釋放那些參照。 closeCursor() 釋放待處理結果,以便該陳述式可重複使用;它不是連線關閉方法。

這兩個 API 都是從自動提交模式開始:成功的語句會提交,除非你開始交易作業,否則不需要另外的應用程式提交。 對於必須一起成功或失敗的寫入群組,則使用 sqlsrv_begin_transaction() 或 $pdo->beginTransaction(),然後明確提交或回滾。 關閉有未完成交易的連線嘗試回滾,而非提交。 不要只依賴關機清理來執行你的事務策略。 完整範例請參見 執行交易。

釋放 PHP 連線句柄不一定會關閉其實體網路連線。 ODBC 的池化可以將其保留以便重複使用。 池化並不是永久保留 PHP 資源的理由,PDO_SQLSRV 也不支援 PDO::ATTR_PERSISTENT => true。 關於平台特定的池化配置,請參見 連線集區。

將指南套用到你的 SQL 目標上

handle、fetch 和清理模式會套用在支援的 SQL 目標上的這兩個擴充功能。 連線端點、認證、網路存取及 SQL 能力各異。

標的 改編
SQL Server 這些程式使用 SQL 登入帳號。 在設定 PHP 程序身份時,整合認證是另一種選擇。
Azure SQL Database 使用邏輯伺服器主機名稱和指定的資料庫。 建議在這些程式中使用 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 已載入該行程,並確認可在 PDO::getAvailableDrivers() 中看到 sqlsrv。
找不到 ODBC 驅動程式 安裝 Microsoft ODBC 驅動程式並檢查其註冊與架構。 安裝 PHP 擴充功能並不會安裝 ODBC。
連線逾時或找不到伺服器 檢查伺服器名稱、埠口、名稱解析、路由、防火牆規則,以及 SQL Server 是否在 TCP 上監聽。
憑證鏈或主機名稱驗證失敗 安裝正確的信任鏈,並使用憑證的主機名稱。 不要把 TrustServerCertificate=true 它當作生產上的修正。
登入失敗或資料庫無法開啟 檢查認證模式、資料庫名稱、登入/使用者映射以及權限。 省略憑證時,會要求使用整合式驗證;它不會選擇 SQL 驗證。
在終端機中可成功執行,但網頁請求失敗 比較 PHP 執行時、載入擴充功能、程序身份、環境變數及網路存取。 不要公開提供包含設定細節的 phpinfo() 頁面。
後續操作在已關閉的控制代碼上失敗 在所有陳述式作業中保持連線。 關閉連線後再建立新連線;舊的 handle 不會自動重新開啟。

其他相關文章