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

Wartość	Opis
`False`	Domyślne. Nazwy kolumn zachowują oryginalną obudowę.
`True`	Nazwy kolumn w `cursor.description` są zamieniane na małe litery.

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

Wartość	Opis
`True`	Domyślne. `UNIQUEIDENTIFIER` kolumny zwracają `uuid.UUID` obiekty.
`False`	`UNIQUEIDENTIFIER` kolumny zwracają łańcuchy pisane wielkimi literami (zgodne z pyodbc).

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)

Note

To ustawienie native_uuid zostało wprowadzone w wersji 1.5.0 biblioteki mssql-python.

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:

Wartość	Meaning
`'2.0'`	Pełna zgodność z DB-API 2.0.

Bezpieczeństwo gwintu

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

Wartość	Meaning
`0`	Wątki nie mogą udostępniać modułu.
`1`	Wątki mogą współdzielić moduł, ale nie połączenia.
`2`	Wątki mogą współdzielić moduł i połączenia.
`3`	Wątki mogą współdzielić moduł, połączenia i kursory.

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:

Style	Format	Przykład
`'qmark'`	Znaki zapytania	`WHERE id = ?`
`'numeric'`	Pozycja liczbowa	`WHERE id = :1`
`'named'`	Nazwany	`WHERE id = :id`
`'format'`	ANSI C printf	`WHERE id = %s`
`'pyformat'`	Format języka Python	`WHERE id = %(id)s`

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__)  # e.g., '1.5.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()

Important

Skonfiguruj ustawienia przed utworzeniem połączeń. Zmiana ustawień po utworzeniu połączeń może prowadzić do niespójnego zachowania.

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

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-22