Stringi połączeń dla mssql-python

Sterownik mssql-python obsługuje następujące słowa kluczowe parametry połączenia podczas łączenia z SQL Server, Azure SQL Database, Azure SQL Managed Instance oraz bazą danych SQL w Microsoft Fabric.

Składnia parametrów połączenia

Łańcuchy połączeń używają par klucz-wartość oddzielone średnikiem:

keyword1=value1;keyword2=value2;...

Wartości zawijania zawierające znaki specjalne (średniki, znaki równości lub nawiasy kręcone) w nawiasach kręconych:

PWD={my;complex=password}

Aby uwzględnić dosłowną zamknięcie w wartości, użyj dwóch zamkających nawiasów (}}):

PWD={password}}with}}brace}

Podstawowe przykłady połączeń

Poniższe przykłady pokazują, jak łączyć się za pomocą różnych metod uwierzytelniania. W aplikacjach produkcyjnych używaj uwierzytelniania Microsoft Entra, kiedy tylko to możliwe. Eliminuje hasła z kodu i łańcuchów połączeń.

Ten przykład wykorzystuje ActiveDirectoryDefault, które próbuje wiele źródeł poświadczeń (Azure CLI, zmienne środowiskowe, zarządzana tożsamość) w kolejności. Nie przechowywane jest żadne hasło w kodzie:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server z uwierzytelnianiem SQL

Używaj uwierzytelniania SQL tylko do lokalnego rozwoju na instancji SQL Server, którą kontrolujesz. Poświadczenia są osadzone w parametry połączenia, więc należy je przechowywać w zmiennych środowiskowych lub pliku.env, a nie w kodzie źródłowym:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL z uwierzytelnianiem Microsoft Entra

Ciąg parametry połączenia dla Azure SQL Database jest taki sam jak w SQL Server. ActiveDirectoryDefaultdziała w środowiskach lokalnych programistów, kontenerach i hostowanych w Azure bez zmian w kodzie:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Używaj argumentów słów kluczowych

Możesz przekazywać parametry połączenia jako argumenty słów kluczowych zamiast lub dodatkowo do parametry połączenia. Argumenty słów kluczowych unikają pułapek związanych z montażem parametry połączenia. Hasła ze specjalnymi znakami, takimi jak @, ;, {, lub } nie wymagają zawijania nawiasów, gdy są przekazywane jako argumenty słów kluczowych:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Porównaj z assembly parametry połączenia, gdzie hasło zawierające @ musi być owinięte:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Sterownik po normalizacji łączy argumenty słów kluczowych do parametry połączenia. Jeśli argument słowa kluczowego odpowiada parametrowi już znajdującemu się w parametry połączenia, argument słowa kluczowego przejmuje pierwszeństwo i nadpisuje wartość parametry połączenia:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

Poniższy przykład łączy parametry połączenia z argumentami słów kluczowych:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Słowa kluczowe parametrów połączenia

Serwer i baza danych

Określ docelową instancję SQL Server oraz bazę danych dla połączenia.

Keyword Pseudonimy Domyślnie Opis
Server addr, address Żaden Nazwa hosta, adres IP lub nazwa instancji SQL Server. Dla nazwanych instancji używamy server\instance. For Azure SQL, użyj server.database.windows.net. Aby określić port, użyj server,port.
Database Żaden Żaden Nazwa bazy danych, do której należy się połączyć.

Authentication

Podaj dane uwierzytelniające do uwierzytelniania SQL lub wybierz tryb uwierzytelniania Microsoft Entra. Opcje bez hasła znajdziesz w Microsoft Entra Authentication Modes.

Keyword Pseudonimy Domyślnie Opis
UID uid Żaden Nazwa użytkownika do uwierzytelniania SQL.
PWD pwd Żaden Hasło do uwierzytelniania SQL.
Trusted_Connection trusted_connection no Użyj zintegrowanej uwierzytelniania Windows. Ustaw na yes, aby włączyć.
Authentication authentication Żaden Tryb uwierzytelniania Microsoft Entra. Zobacz uwierzytelnianie Microsoft Entra.

Szyfrowanie i zabezpieczenia

Wszystkie połączenia są używane Encrypt=yes domyślnie. W większości zastosowań domyślna metoda jest wystarczająca. Używaj strict tylko wtedy, gdy instancja SQL Server obsługuje TDS 8.0 i potrzebujesz TLS 1.3. Używaj TrustServerCertificate=yes tylko w środowiskach programistycznych z certyfikatami podpisanymi samodzielnie.

Keyword Pseudonimy Domyślnie Opis
Encrypt encrypt yes Włącz szyfrowanie TLS. Wartości: yes, , nostrict. Użyj strict do TDS 8.0 z obowiązkowym TLS 1.3.
TrustServerCertificate trust_server_certificate, trustservercertificate no Zaufaj samodzielnie podpisanym certyfikatom serwera bez weryfikacji. Ustawione na yes tylko do rozwoju.
HostnameInCertificate hostnameincertificate Żaden Oczekiwana nazwa hosta w certyfikacie TLS serwera.
ServerCertificate servercertificate Żaden Ścieżka do pliku PEM zawierającego zaufany organ certyfikacyjny.
ServerSPN serverspn Żaden Server Service Principal Name for Kerberos authentication.

Wysoka dostępność i przełączanie awaryjne

Te słowa kluczowe dotyczą wdrożeń grup dostępności Always On. Ustaw ApplicationIntent=ReadOnly tak, aby obciążenia wymagające dużej liczby odczytów (raporty, analityka) były kierowane do replik wtórnych, zmniejszając obciążenie na podstawowym procesorze. Ustaw MultiSubnetFailover=yes moment, gdy Twoja grupa dostępności obejmuje wiele podsieci.

Keyword Pseudonimy Domyślnie Opis
MultiSubnetFailover multisubnetfailover no Włącz awaryjne przełączanie wielopodsieci dla grup dostępności Always On.
ApplicationIntent applicationintent ReadWrite Declare application workload type. Zastosowanie ReadOnly do routingu tylko do odczytu do replik wtórnych.
ConnectRetryCount connectretrycount 1 Liczba prób automatycznego ponownego połączenia dla odporności na bezczynne połączenie. Jest to funkcja na poziomie sterownika dla zerwanych połączeń bezczynnościowych, a nie substytut logiki powtórek na poziomie aplikacji.
ConnectRetryInterval connectretryinterval 10 Sekundy między próbami ponownego połączenia odporności na połączenie bezczynne.

Wydajność i sieć

Domyślne ustawienia działają w większości zastosowań. Zwiększenie PacketSize (do 32767) dla masowych transferów danych. Konfiguruj, KeepAlive czy połączenia przechodzą przez zapory sieciowe lub load balancery, które przerywają bezczynne sesje TCP.

Keyword Pseudonimy Domyślnie Opis
PacketSize packet size, packetsize 4096 Rozmiar pakietu sieciowego w bajtach (512–32767).
KeepAlive keepalive Żaden TCP utrzymuje interwał w ciągu sekund.
KeepAliveInterval keepaliveinterval Żaden Interwał powtarzania TCP w kilka sekund.
IpAddressPreference ipaddresspreference Żaden Preferencja rodziny adresów IP: IPv4First, IPv6First, UsePlatformDefault.

Zastrzeżone słowa kluczowe

Keyword Opis
Driver Zarezerwowane do użytku wewnętrznego. Sterownik automatycznie zarządza tą wartością.
APP Zarezerwowane. Zawsze ustawione przez "MSSQL-Python" kierowcę.

Tryby uwierzytelniania Microsoft Entra

Słowo Authentication kluczowe obsługuje następujące wartości. Wybierz tryb odpowiadający twojemu rozmieszczeniu:

Wartość Opis Kiedy stosować
ActiveDirectoryDefault Zastosowania DefaultAzureCredential z Azure Identity SDK. Próbuje różnych metod uwierzytelniania kolejno. Lokalny rozwój w ramach Azure CLI, Azure PowerShell i Azure Developer CLI. W produkcji użyj konkretnego trybu (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal), aby uniknąć powolnego przejścia poświadczeniowego.
ActiveDirectoryInteractive Interaktywne logowanie w przeglądarce. Na Windows deleguje sterownik ODBC natywnie. Lokalne tworzenie i narzędzia, w których użytkownik jest obecny do uwierzytelniania w przeglądarce.
ActiveDirectoryDeviceCode Przepływ kodu urządzenia dla środowisk headless. Wyświetla kod do wpisania w .https://microsoft.com/devicelogin Sesje SSH, kontenery Dockera lub inne środowiska bez przeglądarki.
ActiveDirectoryPassword Deprecated. Uwierzytelnianie nazw użytkownika i haseł za pomocą Microsoft Entra ID. Wymaga UID i PWD. Korzysta z przepływu ROPC, który jest niekompatybilny z MFA. Nie polecam. Użyj polecenia ActiveDirectoryMSI lub ActiveDirectoryServicePrincipal zamiast tego.
ActiveDirectoryMSI Zarządzana tożsamość usługi dla aplikacji hostowanych w Azure. Azure VMs, App Service lub Azure Functions, gdzie konfigurowana jest zarządzana tożsamość. Nie są potrzebne żadne poświadczenia.
ActiveDirectoryServicePrincipal Uwierzytelnianie zasady usługi. Wymaga UID (identyfikator klienta) oraz PWD (tajemnica klienta). Potoki CI/CD i usługi w tle, które wykorzystują zarejestrowaną tożsamość aplikacji.
ActiveDirectoryIntegrated Windows Integrated authentication with Microsoft Entra ID (Kerberos). Komputery Windows połączone z domeną w środowiskach przedsiębiorstw z skonfigurowanym Kerberosem.

Aby uzyskać konfigurację środowiska reprodukcyjnego Dockera, devcontainera i środowiska CI, zobacz Container i lokalny development. Ten artykuł centralizuje wybór w czasie uruchomieniowym Python i pokazuje, jak używać obrazów przypiętych w Digest w środowiskach współdzielonych.

Przykład: DefaultAzureCredential

ActiveDirectoryDefaultmapuje na łańcuch Azure IdentityDefaultAzureCredential. Najpierw testuje token Azure CLI podczas lokalnego rozwoju, a następnie zarządzaną tożsamością po wdrożeniu do Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Przykład: Przepływ kodu urządzenia

Używaj przepływu kodu urządzenia podczas działania w środowiskach bez przeglądarki, takich jak sesje SSH czy kontenery Docker. Sterownik wyświetla adres URL oraz kod do wpisania na osobnym urządzeniu:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Przykład: Główny podmiot

Autoryzacja za pomocą głównej usługi wykorzystuje zarejestrowaną tożsamość aplikacji z identyfikatorem klienta i sekretem. Stosuj to podejście dla potoków CI/CD oraz usług w tle, które działają bez interakcji użytkownika:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Aby zarejestrować aplikację i przyznać jej dostęp do bazy danych, zobacz Microsoft Entra service principals with Azure SQL. Pełną konfigurację w , mssql-pythonzobacz uwierzytelnianie podmiotu usługi.

Przekroczenie limitu czasu połączenia

Ustaw limit czasu połączenia za pomocą parametru timeout . Użyj timeoutu, aby zapobiec zawieszeniu aplikacji na czas nieskończony, gdy serwer jest nieosiągalny:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Możesz też zmienić limit czasu na istniejącym połączeniu:

conn.timeout = 60

Tryb automatycznego zatwierdzania

Domyślnie jest , autocommitFalseco wymaga wywołań jawnych commit() . Włącz automatyczne zatwierdzanie dla instrukcji DDL lub zapytań tylko do odczytu, które nie wymagają kontroli transakcji:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Atrybuty połączenia

Ustaw atrybuty połączenia ODBC przed nawiązaniem połączenia, używając attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Programowe budowanie parametry połączenia

Aby zapobiec wstrzykiwaniu parametry połączenia, nie używaj konkatenacji stringów ani f-stringów z wejściem użytkownika. Zamiast tego używaj argumentów słów kluczowych lub zmiennych środowiskowych. Aby uzyskać więcej wzorców konstrukcyjnych, w tym plików konfiguracyjnych JSON/YAML, Azure Key Vault oraz klasy builder, zobacz Build connection strings programatically.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Walidacja ciągu połączeń

Sterownik weryfikuje łańcuchy połączeń i podnosi dane ConnectionStringParseError dla nieznanych lub błędnie napisanych słów kluczowych:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Treści powiązane

  • Last updated on