使用 Python 和 Pyodbc 連線到 Microsoft SQL Server

使用 pyodbc 透過 ODBC 將 Python 應用程式連線至 Microsoft SQL Server。安裝 Python 套件與相容的 SQL Server ODBC 驅動程式後，將伺服器、資料庫、驅動程式及驗證設定傳給 pyodbc.connect()。本指南使用直接 SQL；若希望以 Python 物件表示資料庫資料表，也可以選擇 ORM。

安裝 pyodbc 與 SQL Server ODBC 驅動程式

請在執行應用程式的同一個 Python 環境中安裝 pyodbc，例如執行 python -m pip install pyodbc。這會安裝 Python 介面，但不會安裝 Microsoft 的 ODBC 驅動程式。請另外在程式執行所在的電腦或容器安裝 SQL Server ODBC 驅動程式，並確認名稱與系統中安裝的驅動程式完全一致。常見名稱為 ODBC Driver 18 for SQL Server；請使用系統上實際可用的名稱。

連線前，請先備妥伺服器位址與資料庫名稱。伺服器可以是主機名稱、位址，或主機與執行個體名稱，例如 db.example.net\SQLEXPRESS；代管環境也可能需要連接埠。管理員可能需要授予該帳戶所選資料庫的存取權。SQL Server 的連線資訊與 Python 的工作目錄無關，但作業系統的 ODBC 管理員必須能使用該驅動程式。

使用驅動程式與受信任驗證連線

若 Windows 環境已設定整合式驗證，請使用包含 Trusted_Connection=yes 的驅動程式連線字串。請將驅動程式、伺服器與資料庫值替換為符合你安裝環境的設定。以下小程式會組合並顯示連線字串，方便確認各欄位如何串接；它不會連線至資料庫。

執行以下範例：

本節中的程式碼以及顯示的標籤或輸出仍為英文。

driver = "ODBC Driver 18 for SQL Server"
server = "db.example.net"
database = "Sales"
connection_string = (
    f"Driver={{{driver}}};"
    f"Server={server};"
    f"Database={database};"
    "Trusted_Connection=yes;"
)
print(connection_string)

Driver={ODBC Driver 18 for SQL Server};Server=db.example.net;Database=Sales;Trusted_Connection=yes;

若要在應用程式中開啟連線，請將該字串傳給 pyodbc.connect(connection_string)。整合式驗證會使用目前程序可用的身分，實際行為取決於作業系統、驅動程式與 SQL Server 設定；這與提供 SQL Server 使用者名稱和密碼不同。TLS 設定請遵循組織的憑證政策。不同版本的驅動程式可能採用不同的加密預設值，請勿只為了讓連線成功就停用憑證檢查。

透過 DSN 和認證資料連線

資料來源名稱 (DSN) 是在主機上建立的 ODBC 設定。它可以保存共用的伺服器與驅動程式設定，讓應用程式只需提供 DSN 名稱，並在需要時提供認證資料。連線字串格式如下：DSN=SalesReadOnly;UID=app_reader;PWD=<secret>;。DSN 必須存在於相同環境中，且 Python 程序必須能讀取；為互動式使用者設定的 DSN，服務帳戶或容器可能無法使用。

請透過祕密管理工具或依環境設定的組態提供認證資料，不要將其提交至原始碼管理。如果祕密包含特殊字元，請使用 ODBC 連線字串支援的引用規則，或另外設定認證資料；否則分號可能會被解讀為欄位分隔符。避免輸出完整連線字串，以免密碼出現在記錄中。使用 DSN 字串呼叫相同的 pyodbc.connect(...)，並依 DSN 與伺服器的設定選擇整合式驗證或 SQL 驗證。

執行查詢並關閉資源

連線後，建立游標、執行 SQL，然後擷取或逐筆走訪傳回的資料列。對於使用者或應用程式提供的值，請使用參數標記。在 pyodbc 中，? 是位置參數標記；分開傳入值可避免它們與 SQL 文字混在一起。參數適用於資料值，不適用於資料表或欄位名稱。如果識別字必須變動，請從固定的允許清單中選取，並依 SQL Server 規則引用。

常見的應用程式流程是先執行 connection = pyodbc.connect(connection_string)，再執行 cursor = connection.cursor() 和 cursor.execute("SELECT name FROM dbo.Customers WHERE customer_id = ?", customer_id)。你可以逐筆走訪 cursor 來處理資料列，或在結果集小到可放入記憶體時呼叫 fetchall()。若結果集很大，請逐步處理資料列。此查詢假設所選資料庫中存在指定的資料表與欄位；請依你的結構替換名稱。

connection = pyodbc.connect(connection_string) 成功後，請將游標操作放在 try 區塊中，並在 finally 子句關閉連線：try: ... finally: connection.close()。若要清理游標，請在該區塊內使用 with connection.cursor() as cursor:；離開游標的內容管理區塊時，游標便會關閉。像 with connection: 這樣的 pyodbc 連線內容管理區塊會管理交易範圍：正常離開時提交，例外未處理而逸出時回復，但不會關閉連線。你可以在 try 中結合交易與游標內容管理區塊，然後在 finally 呼叫 connection.close()。只要連線已成功開啟，這樣便會在查詢處理正常結束或發生例外後關閉連線。如果你會修改資料，請明確決定交易應在何處提交。此用法需要已設定好的 SQL Server、驅動程式與資料庫結構；本文並未實際執行這個用法。

診斷常見的連線錯誤

如果 pyodbc 回報找不到驅動程式，請確認 ODBC 驅動程式已安裝在程式的執行環境中，且 Driver={...} 的值與已註冊名稱完全一致，包括空格與版本。如果無法連上伺服器，請檢查 DNS 或主機名稱拼寫、連接埠與執行個體設定、防火牆存取，以及 SQL Server 是否接受網路連線。逾時通常表示連線問題或伺服器負載較高；調高逾時設定無法修正錯誤的目的地。

若登入失敗，請確認連線實際使用的身分。受信任驗證使用程序身分，而 UID 和 PWD 會要求使用 SQL 認證；混用兩種方式可能會送出錯誤的身分。接著檢查資料庫存取權與資料庫名稱。若發生憑證或加密錯誤，請與管理員確認伺服器憑證鏈及驅動程式的加密設定，不要降低驗證強度。最後，檢查連線字串是否缺少分號、驅動程式名稱的大括號是否成對、鍵名是否意外含有空白，或特殊字元是否未正確跳脫。診斷記錄應保留足夠資訊，但請遮蔽密碼及其他祕密。

如需驅動程式與連線字串的詳細資訊，請參閱 pyodbc SQL Server 連線指南 與 pyodbc 官方文件。若要查看讀取查詢結果的相關範例，請參閱如何在 Python 中使用 fetchall() 從資料庫擷取元素。