Настройка модулей 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, часто преобразуют строки в словари, что делает важным согласованный корпус:

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 строки в верхнем регистре. Эта настройка полезна для команд, переходящих с pyodbc и которые зависят от значений строк UUID:

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.

Константы на уровне модуля

Драйвер показывает константы соответствия только для чтения 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:

Ценность	Значение
`'2.0'`	Полное соответствие DB-API 2.0.

Защита резьбы

Константа threadsafety сообщает об уровне потокобезопасности:

Ценность	Значение
`0`	Потоки не могут делить модуль.
`1`	Потоки могут совместно использовать модуль, но не соединения.
`2`	Потоки могут делить модуль и соединения.
`3`	Потоки могут делить модуль, соединения и курсоры.

Драйвер mssql-python использует threadsafety = 1, что означает:

Вы можете импортировать и использовать модуль между потоками.
Каждое соединение должно принадлежать только одному потоку одновременно.
Создайте отдельное соединение для каждого потока или используйте пул соединений (по умолчанию включён). Для получения дополнительной информации см. раздел Пулирование соединений.

парамстайл

paramstyle константа указывает формат заполнителя параметра:

Style	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__)  # 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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-22