配置 mssql-python 模組設定

mssql-python 驅動程式提供 Settings 一個類別，用以控制模組範圍的行為。 這些設定會影響所有連線和游標操作。 在應用程式啟動時，於建立任何連線之前，只需將它們設定一次。

存取設定

檢索目前 Settings 物件並檢查或修改其屬性：

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

可用的設定

以下設定控制驅動程式如何回傳資料及格式化結果。

小寫

該設定控制 lowercase 欄位 cursor.description 名稱是否顯示為小寫。 當您的應用程式依名稱存取資料行，且您想避免大小寫不一致時，請啟用此設定。 像 Flask 和 FastAPI 這類 Web 框架經常會將資料列轉換成字典，因此大小寫的一致性就顯得很重要：

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)

價值	描述
False	違約。 欄位名稱會保留原始大小寫。
True	欄位 cursor.description 名稱會被轉換成小寫。

小數分隔符號

驅動程式提供模組層級功能，用以控制十進位分隔符以進行數字轉換。 只有當您的 SQL Server 實例使用以逗號作為小數分隔符號的地區設定時（例如法文或德文地區設定），才需要變更此設定。 大多數應用程式不需要更改這個設定：

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

欲了解更多關於十進位處理的資訊，請參見 資料型態映射。

native_uuid

native_uuid 設定控制是否將 UNIQUEIDENTIFIER 欄位以 Python uuid.UUID 物件的形式回傳，或是以與 pyodbc 相容的大寫字串回傳。 此設定對於依賴字串 UUID 值的團隊從 pyodbc 遷移非常有用：

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False

價值	描述
True	違約。 UNIQUEIDENTIFIER 欄位會回傳 uuid.UUID 物件。
False	UNIQUEIDENTIFIER 欄位回傳大寫字串（PYODBC 相容）。

你也可以針對每個連線設定 native_uuid：

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

Note

此 native_uuid 設定於 mssql-python 1.5.0 版本中引入。

模組層級常數

驅動程式會提供唯讀的 DB-API 2.0 相容性常數，用來描述其功能。 利用這些常數撰寫能適應不同 DB-API 驅動程式的程式碼：

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

API 級別

apilevel常數報告 DB-API 合規等級：

價值	Meaning
'2.0'	完全符合 DB-API 2.0 規範。

執行緒安全

threadsafety 常數表示執行緒安全層級：

價值	Meaning
0	執行緒無法共用模組。
1	執行緒可以共用模組，但連線不行。
2	執行緒可以共用模組和連接。
3	執行緒可以共用模組、連接和游標。

mssql-python 驅動程式使用 threadsafety = 1，意即：

• 你可以跨執行緒匯入並使用這個模組。
• 每個連線一次只能屬於一個執行緒。
• 為每個執行緒建立獨立連線，或使用預設啟用的連線池。 欲了解更多資訊，請參閱連線集區。

參數風格

paramstyle常數回報參數佔位格式：

Style	Format	Example
'qmark'	問號	WHERE id = ?
'numeric'	數字位置	WHERE id = :1
'named'	已命名	WHERE id = :id
'format'	ANSI C printf 函式	WHERE id = %s
'pyformat'	Python 格式	WHERE id = %(id)s

mssql-python 驅動程式使用 paramstyle = 'pyformat'. 務必使用命名參數以防止 SQL 注入。 切勿用字串格式或 f 字串來建立使用者輸入的查詢：

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

版本資訊

檢查安裝的驅動程式版本：

import mssql_python

# Driver version
print(mssql_python.__version__)  # e.g., '1.5.0'

啟動時設定

在應用程式啟動時，先設定一次模組配置，然後再建立任何連線。 及早設定數值可防止連線間行為不一致：

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

執行緒安全考量

模組設定是全域的，影響所有執行緒的連線。 如果你在連接已經開啟後才更改設定，現有連接可能無法一致反映這些變化。 在建立第一個連線前，先設定所有設定值：

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Important

建立連線前先設定好。 建立連結後更改設定可能會導致行為不一致。

特定連線的設定

你可以在不改變全域預設的情況下，覆蓋每個連線的某些設定。 當應用程式的不同部分需要不同行為時，請使用針對個別連線的覆寫設定。 例如，報告模組可能需要字串 UUID，而應用程式其他部分則使用 uuid.UUID 物件：

# Per-connection native_uuid override
conn = mssql_python.connect(connection_string, native_uuid=False)

# Use the autocommit property
conn.autocommit = True

相關內容

• 連接字串
• 連線管理
• 數據類型對應