配置 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', ...)

小数分隔符

驱动程序提供模块级函数，用于控制数值转换中的小数点分隔符。 仅当您的 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

你还可以为每个连接单独设置 native_uuid：

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

模级常量

该驱动程序提供只读的、符合 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'

APILEVEL

apilevel常数报告了 DB-API 合规水平：

线程安全

threadsafety常数报告线程安全级别：

mssql-python驱动使用 threadsafety = 1，这意味着：

• 你可以跨线程导入并使用模块。
• 每个连接一次只能属于一个线程。
• 为每个线程创建一个独立连接，或者使用连接池（默认启用）。 有关更多信息，请参阅 连接池。

paramstyle

paramstyle常数报告参数占位符格式：

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()

连接特定配置

你可以在不更改全局默认的情况下，覆盖每个连接的某些设置。 当应用程序的不同部分需要不同行为时，请使用针对各个连接的覆盖设置。 例如，报告模块可能需要字符串UUID，而应用程序的其他部分使用 uuid.UUID 对象：

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

# Use the autocommit property
conn.autocommit = True

相关内容

• 连接字符串
• 连接管理
• 数据类型映射