Konfiguruj ustawienia modułu mssql-python

Sterownik mssql-python zapewnia klasę Settings kontrolującą zachowanie całego modułu. Te ustawienia wpływają na wszystkie połączenia i operacje kursora. Konfiguruj je raz przy starcie aplikacji, zanim utworzysz jakiekolwiek połączenia.

Ustawienia dostępu

Pobierz aktualny Settings obiekt i sprawdź lub zmodyfikuj jego właściwości:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

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

Dostępne ustawienia

Poniższe ustawienia kontrolują, jak sterownik zwraca dane i formatuje wyniki.

małe litery

Ustawienie lowercase określa, czy nazwy kolumn w cursor.description są wyświetlane małymi literami. Włącz to ustawienie, jeśli aplikacja odwołuje się do kolumn po nazwie i chcesz uniknąć niezgodności w wielkości liter. Frameworki internetowe, takie jak Flask i FastAPI, często konwertują wiersze na słowniki, co sprawia, że spójne określenia są ważne:

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

Separator dziesiętny

Sterownik zapewnia funkcje na poziomie modułu do sterowania separatorem dziesiętnym dla konwersji numerycznych. Zmień to ustawienie tylko wtedy, gdy instancja SQL Server używa lokalizacji z przecinkiem jako separatorem dziesiętnym, na przykład francuskie lub niemieckie lokalizacje. Większość aplikacji nie musi zmieniać tego ustawienia:

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

Więcej informacji o obsłudze dziesiętnej można znaleźć w artykule Odwzorowania typów danych.

native_uuid

Ustawienie native_uuid określa, czy kolumny UNIQUEIDENTIFIER są zwracane jako obiekty Python uuid.UUID, czy jako zgodne z pyodbc ciągi znaków pisane wielkimi literami. To ustawienie jest przydatne dla zespołów migrujących z pyodbc, które korzystają z wartości UUID w postaci ciągów znaków:

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

Możesz też ustawić native_uuid dla każdego połączenia:

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

Wybierz natywnego dostawcę ODBC

Sterownik ładuje jednego natywnego dostawcę ODBC na proces. Dostępni są dwaj dostawcy:

Oba pakiety instalują się z pip install mssql-python, więc nie musisz instalować niczego innego, żeby wypróbować dostawcę mssql-odbc. Kod aplikacji się nie zmienia.

Wybierz dostawcę za pomocą zmiennej środowiskowej MSSQL_PYTHON_NATIVE_PROVIDER. W systemie Linux lub macOS:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

W programie Windows PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Albo ustaw native_provider atrybut modułu przed otwarciem pierwszego połączenia:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

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

Funkcja get_native_provider_info() zwraca wybranego dostawcę oraz miejsce, skąd pochodzi wybór:

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

Sterownik stosuje te zasady, gdy ustala dostawcę:

• Zmienna środowiskowa ma pierwszeństwo przed atrybutem native_provider . Jeśli ustawisz atrybut na innego dostawcę niż zmienna środowiskowa, sterownik emituje RuntimeWarning i używa zmiennej środowiskowej.

• Wybór jest ustalony, gdy sterownik ładuje dostawcę, co następuje po parsowaniu parametry połączenia i przed kontaktem sterownika z serwerem. Wybór pozostaje stały nawet jeśli połączenie nie powiedzie się, na przykład dlatego, że serwer jest nieosiągalny. Błąd wywołany zanim dostawca zostanie załadowany, taki jak błąd parsowania parametrów połączenia lub brak pakietu dostawcy, nie koryguje wyboru. Po ustaleniu selekcji zmiana w native_provider emituje RuntimeWarning i nie ma wpływu na resztę procesu.

• Nierozpoznana nazwa dostawcy powoduje ValueError. Ustawienie atrybutu na nieznaną nazwę natychmiast zgłasza wyjątek. Nieznana nazwa w zmiennej środowiskowej powoduje błąd przy otwieraniu pierwszego połączenia. Sterownik nie przełącza się na domyślnego dostawcę.

• Ustaw native_provider na None, aby wyczyścić wybór przed pierwszym połączeniem.

Stałe na poziomie modułu

Sterownik ujawnia stałe zgodności DB-API 2.0 tylko do odczytu, które opisują jego możliwości. Użyj tych stałych do pisania kodu dostosowującego się do różnych sterowników 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

Stała apilevel określa poziom zgodności z DB-API:

Bezpieczeństwo gwintu

threadsafety Stała określa poziom bezpieczeństwa wątków:

Sterownik mssql-python używa threadsafety = 1, co oznacza:

• Możesz importować i używać modułu między wątkami.
• Każde połączenie musi należeć tylko do jednego wątku naraz.
• Stwórz osobne połączenie na każdy wątek lub użyj puli połączeń (domyślnie włączonej). Więcej informacji można znaleźć w artykule Pula połączeń.

Paramstyle

Stała paramstyle określa format symbolu zastępczego parametru:

Sterownik mssql-python używa paramstyle = 'pyformat'. Zawsze używaj nazwanych parametrów, aby zapobiec wstrzyknięciu SQL. Nigdy nie twórz zapytań z użyciem danych wejściowych użytkownika za pomocą formatowania ciągów ani f-stringów:

# 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}
)

Informacje o wersji

Sprawdź, która wersja sterownika jest zainstalowana:

import mssql_python

# Driver version
print(mssql_python.__version__)  # For example, '1.16.0'

Konfiguruj ustawienia przy starcie

Ustawij konfigurację modułu po uruchomieniu aplikacji, zanim utworzysz jakiekolwiek połączenia. Wczesne ustawianie wartości zapobiega niespójnemu zachowaniu między połączeniami:

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)

Aspekty bezpieczeństwa gwintu

Ustawienia modułu są globalne i wpływają na wszystkie połączenia we wszystkich wątkach. Jeśli zmienisz ustawienie po tym, jak połączenia są już otwarte, istniejące połączenia mogą nie odzwierciedlać tej zmiany konsekwentnie. Ustaw wszystkie wartości konfiguracyjne przed utworzeniem pierwszego połączenia:

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

Konfiguracja specyficzna dla połączenia

Możesz zmienić niektóre ustawienia dla poszczególnych połączeń bez zmiany ustawień globalnych. Używaj zastąpień dla poszczególnych połączeń, gdy różne części aplikacji wymagają odmiennego działania. Na przykład moduł raportujący może potrzebować UUID ciągów tekstowych, podczas gdy reszta aplikacji korzysta z uuid.UUID obiektów:

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

# Use the autocommit property
conn.autocommit = True

Treści powiązane

• Stringi połączeń dla mssql-python
• Zarządzanie połączeniami za pomocą mssql-python
• Mapowania typów danych dla mssql-python