Konfigurieren der Moduleinstellungen für mssql-python

Der mssql-python-Treiber bietet eine Settings Klasse, die das modulweite Verhalten steuert. Diese Einstellungen beeinflussen alle Verbindungen und Cursoroperationen. Konfigurieren Sie sie einmal beim Anwendungsstart, bevor Sie irgendwelche Verbindungen herstellen.

Zugriffseinstellungen

Rufen Sie das aktuelle Settings Objekt ab und inspizieren oder ändern Sie seine Eigenschaften:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

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

Verfügbare Einstellungen

Die folgenden Einstellungen steuern, wie der Treiber Daten und Formatergebnisse zurückgibt.

Kleinbuchstaben

Die Einstellung lowercase steuert, ob Spaltennamen in Kleinbuchstaben cursor.description erscheinen. Aktivieren Sie diese Einstellung, wenn Ihre Anwendung Spalten nach Namen aufruft und Sie Unstimmigkeiten bei der Groß-/Kleinschreibung vermeiden möchten. Webframeworks wie Flask und FastAPI wandeln Zeilen oft in Wörterbücher um, was eine konsistente Groß-/Kleinschreibung wichtig macht:

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

Dezimaltrennzeichen

Der Treiber bietet modulbasierte Funktionen zur Steuerung des Dezimalseparators für numerische Umrechnungen. Ändern Sie diese Einstellung nur, wenn Ihre SQL Server-Instanz einen Ort mit einem Komma als Dezimaltrenner verwendet, wie zum Beispiel französische oder deutsche Orte. Die meisten Anwendungen müssen diese Einstellung nicht ändern:

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 weitere Informationen zur Dezimalbehandlung siehe Datentypabbildungen.

native_uuid

Die Einstellung native_uuid steuert, ob UNIQUEIDENTIFIER Spalten als Python-Objekte uuid.UUID oder als pyodbc-kompatible Großbuchstaben-Zeichenketten zurückgegeben werden. Diese Einstellung ist nützlich für Teams, die von pyodbc migrieren und auf String-UUID-Werte angewiesen sind:

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 kannst auch pro Verbindung festlegen native_uuid :

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

Wählen Sie den nativen ODBC-Anbieter aus

Der Treiber lädt pro Prozess einen nativen ODBC-Provider. Es stehen zwei Anbieter zur Verfügung:

Beide Pakete werden mit pip install mssql-python installiert, sodass du nichts anderes installieren musst, um den mssql-odbc Anbieter auszuprobieren. Dein Anwendungscode ändert sich nicht.

Wählen Sie den Anbieter mit der Umgebungsvariable MSSQL_PYTHON_NATIVE_PROVIDER aus. Unter Linux oder macOS:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

Unter Windows PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Oder setze das native_provider Attribut des Moduls, bevor du die erste Verbindung öffnest:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

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

Die get_native_provider_info() Funktion gibt den ausgewählten Anbieter zurück und woher die Auswahl stammt:

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

Der Treiber wendet diese Regeln an, wenn er den Anbieter ermittelt:

• Die Umgebungsvariable hat Vorrang vor dem Attribut native_provider . Wenn Sie das Attribut auf einen anderen Anbieter als die Umgebungsvariable setzen, gibt der Treiber RuntimeWarning aus und verwendet die Umgebungsvariable.

• Die Auswahl ist festgelegt, wenn der Treiber den Anbieter lädt, was passiert, nachdem der Verbindungszeichenfolge geparst wurde und bevor der Treiber den Server kontaktiert. Die Auswahl bleibt auch dann stabil, wenn die Verbindung dann fehlschlägt, zum Beispiel weil der Server nicht erreichbar ist. Ein Fehler, der vor dem Laden des Providers angezeigt wird, wie ein Parsing-Fehler der Verbindungszeichenfolge oder ein fehlendes Provider-Paket, ändert die Auswahl nicht. Nachdem die Auswahl festgelegt wurde, sendet eine Änderung an native_providerRuntimeWarning aus und hat für den Rest des Prozesses keine Wirkung mehr.

• Ein nicht anerkannter Anbietername löst ValueError aus. Das Setzen des Attributs auf einen unbekannten Namen löst sofort eine Ausnahme aus. Ein unbekannter Name in der Umgebungsvariable löst einen Fehler aus, wenn du die erste Verbindung öffnest. Der Treiber greift nicht auf den Standardanbieter zurück.

• Setze native_provider auf None, um eine Auswahl vor der ersten Verbindung zu löschen.

Modulniveau-Konstanten

Der Treiber stellt lesgeschützte DB-API 2.0-Compliance-Konstanten zur Verfügung, die seine Fähigkeiten beschreiben. Verwenden Sie diese Konstanten, um Code zu schreiben, der sich an verschiedene DB-API Treiber anpasst:

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

Die Konstante apilevel meldet das DB-API Compliance-Niveau:

Gewindesicherung

Die Konstante threadsafety meldet das Sicherheitsniveau des Fadens:

Der mssql-python-Treiber verwendet threadsafety = 1, was bedeutet:

• Du kannst das Modul importieren und über Threads hinweg verwenden.
• Jede Verbindung darf jeweils nur zu einem Thread gehören.
• Erstelle pro Thread eine separate Verbindung oder nutze einen Connection Pool (standardmäßig aktiviert). Weitere Informationen finden Sie unter Connection pooling.

Paramstyle

Die Konstante paramstyle gibt das Parameter-Platzhalterformat an:

Der mssql-python-Treiber verwendet paramstyle = 'pyformat'. Verwenden Sie immer benannte Parameter, um SQL-Injection zu verhindern. Erstellen Sie niemals Abfragen mit Benutzereingaben durch String-Formatierung oder f-Strings:

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

Versionsinformationen

Überprüfen Sie, welche Version des Treibers installiert ist:

import mssql_python

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

Einstellungen beim Start konfigurieren

Setze die Modulkonfiguration einmal beim Start der Anwendung, bevor du Verbindungen herstellt. Das frühe Festlegen von Werten verhindert inkonsistentes Verhalten zwischen Verbindungen:

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)

Überlegungen zur Thread-Sicherheit

Die Moduleinstellungen sind global und beeinflussen alle Verbindungen über alle Threads hinweg. Wenn du eine Einstellung änderst, nachdem die Verbindungen bereits geöffnet sind, spiegeln bestehende Verbindungen die Änderung möglicherweise nicht konsistent wider. Setze alle Konfigurationswerte, bevor du deine erste Verbindung erstellst:

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

Verbindungsspezifische Konfiguration

Du kannst einige Einstellungen pro Verbindung überschreiben, ohne die globale Standardeinstellung zu ändern. Verwenden Sie verbindungsspezifische Überschreibungen, wenn verschiedene Teile Ihrer Anwendung ein unterschiedliches Verhalten benötigen. Zum Beispiel könnte ein Berichtsmodul String-UUIDs benötigen, während der Rest der Anwendung Objekte verwendet uuid.UUID :

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

# Use the autocommit property
conn.autocommit = True

Verwandte Inhalte

• Verbindungsstrings für mssql-python
• Verwalte Verbindungen mit mssql-python
• Datentypabbildungen für mssql-python