Konfigurera mssql-python-modulinställningar

mssql-python-drivrutinen tillhandahåller en Settings klass som styr beteendet i hela modulen. Dessa inställningar påverkar alla anslutningar och marköroperationer. Konfigurera dem en gång vid applikationsstart, innan du skapar några anslutningar.

Åtkomstinställningar

Hämta det aktuella Settings objektet och inspektera eller ändra dess egenskaper:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

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

Tillgängliga inställningar

Följande inställningar styr hur drivrutinen returnerar data och formaterar resultat.

Gemener

Inställningen lowercase styr om kolumnnamnen i cursor.description anges med gemener. Aktivera den här inställningen när din applikation kommer åt kolumner efter namn och du vill undvika fel på grund av skillnader i användning av stora och små bokstäver. Webbramverk som Flask och FastAPI konverterar ofta rader till ordlistor, vilket gör enhetlig skiftlägesanvändning viktig:

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

Decimalavgränsare

Drivrutinen tillhandahåller modulnivåfunktioner för att styra decimalseparatorn för numeriska omvandlingar. Ändra denna inställning endast om din SQL Server-instans använder en plats med komma som decimalseparator, såsom franska eller tyska platser. De flesta applikationer behöver inte ändra denna inställning:

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

För mer information om decimalhantering, se Datatypmappningar.

native_uuid

Inställningen native_uuid styr om UNIQUEIDENTIFIER-kolumner returneras som Python-objekt uuid.UUID eller som pyodbc-kompatibla strängar i versaler. Denna inställning är användbar för team som migrerar från pyodbc och som är beroende av sträng-UUID-värden:

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

Du kan också ställa native_uuid in per anslutning:

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

Välj den inbyggda ODBC-leverantören

Drivrutinen laddar en inbyggd ODBC-leverantör per process. Två leverantörer finns tillgängliga:

Båda paketen installeras med pip install mssql-python, så du behöver inte installera något annat för att prova mssql-odbc-leverantören. Din applikationskod ändras inte.

Välj leverantören för miljövariabeln MSSQL_PYTHON_NATIVE_PROVIDER. I Linux eller macOS:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

På Windows PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Eller ställ in modulattributet native_provider innan du öppnar den första anslutningen:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

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

Funktionen get_native_provider_info() returnerar den valda leverantören och var valet kom ifrån:

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

Drivrutinen tillämpar dessa regler när den matchar leverantören:

• Miljövariabeln har företräde framför attributet native_provider . Om du sätter attributet till en annan leverantör än miljövariabeln, genererar drivrutinen RuntimeWarning och använder miljövariabeln.

• Urvalet är fastställt när drivrutinen laddar providern, vilket sker efter att reťazec pripojenia har analyserats och innan drivrutinen kontaktar servern. Urvalet ligger kvar även om anslutningen då misslyckas, till exempel för att servern är oåtkomlig. Ett fel som uppstår innan leverantören laddas, såsom ett anslutningssträngsparsningsfel eller ett saknat leverantörspaket, åtgärdar inte valet. När markeringen har fastställts avger en ändring av RuntimeWarningnative_provider och påverkar inte resten av processen.

• Ett okänt leverantörsnamn genererar ValueError. Att sätta attributet till ett okänt namn ger omedelbart ett fel. Ett okänt namn i miljövariabeln orsakar ett fel när du öppnar den första anslutningen. Drivrutinen återgår inte till standardleverantören.

• Ställ native_provider på None för att rensa ett val före den första anslutningen.

Modulnivåkonstanter

Drivrutinen exponerar skrivskyddad DB-API 2.0-efterlevnadskonstanter som beskriver dess kapaciteter. Använd dessa konstanter för att skriva kod som anpassar sig till olika DB-API drivrutiner:

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

Konstanten apilevel rapporterar DB-API efterlevnadsnivå:

trådsäkerhet

Konstanten threadsafety rapporterar trådsäkerhetsnivån:

mssql-python-drivrutinen använder threadsafety = 1, vilket betyder:

• Du kan importera och använda modulen över trådar.
• Varje anslutning får tillhöra endast en tråd åt gången.
• Skapa en separat anslutning per tråd, eller använd en anslutningspool (aktiverad som standard). För mer information, se Connection pooling.

paramstyle

Konstanten paramstyle rapporterar parameterplatshållarformatet:

mssql-python-drivrutinen använder paramstyle = 'pyformat'. Använd alltid namngivna parametrar för att förhindra SQL-injektion. Bygg aldrig frågor med användarinput genom strängformatering eller f-strängar:

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

Versionsinformation

Kontrollera vilken version av drivrutinen som är installerad:

import mssql_python

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

Konfigurera inställningar vid uppstart

Ställ in modulkonfigurationen en gång vid applikationsstart, innan du skapar några anslutningar. Att sätta värden tidigt förhindrar inkonsekvent beteende mellan anslutningar:

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)

Trådsäkerhetsaspekter

Modulinställningarna är globala och påverkar alla anslutningar över alla trådar. Om du ändrar en inställning efter att anslutningarna redan är öppna, kanske befintliga anslutningar inte speglar förändringen konsekvent. Ställ in alla konfigurationsvärden innan du skapar din första anslutning:

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

Anslutningsspecifik konfiguration

Du kan åsidosätta vissa inställningar per anslutning utan att ändra den globala standarden. Använd per-anslutning-överskrivningar när olika delar av din applikation behöver olika beteende. Till exempel kan en rapporteringsmodul behöva sträng-UUID medan resten av applikationen använder uuid.UUID objekt:

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

# Use the autocommit property
conn.autocommit = True

Relaterat innehåll

• Anslutningssträngar för mssql-python
• Hantera anslutningar med mssql-python
• Datatypmappningar för mssql-python