配置 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)

注释

该 native_uuid 设置是在 mssql-python 1.5.0 版本中引入的。

选择本机 ODBC 提供程序

驱动程序每个进程加载一个本地 ODBC 提供者。 有两个提供者可供选择：

Provider	描述	预计发货时间
msodbcsql18	违约。 Microsoft ODBC Driver 18 for SQL Server.	mssql-python-odbc
mssql-odbc	选择加入。 一个基于Rust的ODBC提供程序。	mssql-python-rs

这两个软件包都可通过 pip install mssql-python 安装，因此你无需安装其他任何内容即可试用该 mssql-odbc 提供程序。 你的应用程序代码不会变。

使用 MSSQL_PYTHON_NATIVE_PROVIDER 环境变量选择提供程序。 在 Linux 或 macOS 上：

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

在 Windows PowerShell 上：

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

或者在打开第一个连接前设置 native_provider 模块属性：

import mssql_python

mssql_python.native_provider = "mssql-odbc"

conn = mssql_python.connect(connection_string)
print(mssql_python.get_native_provider_info())

该 get_native_provider_info() 函数返回所选提供程序以及该选择来自何处：

{'id': 'mssql-odbc', 'package': 'mssql_py_core', 'version': None, 'driver_path': '...', 'source': 'property', 'frozen': True}

驱动程序在解析提供程序时会应用以下规则：

• 环境变量优先于 native_provider 属性。 如果你将属性设置为与环境变量不同的提供者，驱动程序会发出 RuntimeWarning，并使用环境变量。

• 当驱动程序加载提供者时，选择是固定的，这发生在解析连接字符串之后、驱动程序联系服务器之前。 即使连接失败，例如服务器无法访问，选择依然保持不变。 在提供程序加载前出现的错误，如连接字符串解析错误或缺少提供程序包，并不会固定该选择。 选择确定后，更改 RuntimeWarning 会发出 native_provider，且对整个过程的其余部分无影响。

• 未识别的服务提供者名称会引发 ValueError。 将属性设置为未知名称会立即引发错误。 当你打开第一个连接时，环境变量中的一个未知名称会引发错误。 驱动程序不会回退到默认提供商。

• 将 native_provider 设置为 None，以便在首次连接之前清除选择。

模级常量

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

价值	Meaning
'2.0'	完全 DB-API 2.0 合规。

线程安全

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

价值	Meaning
0	线程无法共享模块。
1	线程可以共享模块，但不能共享连接。
2	线程可以共享模块和连接。
3	线程可以共享模块、连接和光标。

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

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

paramstyle

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

样式	Format	示例
'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__)  # For example, '1.16.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

相关内容

• mssql-python 的连接字符串
• 用 mssql-python 管理连接
• mssql-python 的数据类型映射