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ń.

SQL Server z uwierzytelnianiem Microsoft Entra (zalecane)

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.

Authentication

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

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.

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

Te słowa kluczowe obejmują grupy dostępności Always On, cele Azure SQL oraz odporność na połączenie bezczynne. 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 celem jest Azure SQL Database, Azure SQL Managed Instance, baza danych SQL w Microsoft Fabric, nasłuchiwacz grup dostępności lub instancja klastra awaryjnego. Gdy nazwa serwera jest rozpoznawana jako więcej niż jeden adres IP, sterownik łączy się jednocześnie ze wszystkimi tymi adresami i używa tego, który odpowie jako pierwszy. Bez niego sterownik próbuje adresy pojedynczo. Adres, który nie odpowiada, zatrzymuje się, dopóki nie wygaśnie limit połączenia TCP systemu operacyjnego, co może wyczerpać czas logowania, zanim sterownik dotrze do adresu, który odbierze. Gdy nazwa DNS jest rozwiązywana do jednego adresu, sterownik podejmuje tylko jedną próbę połączenia, więc to ustawienie można bezpiecznie pozostawić włączone.

MultiSubnetFailover=yes ma następujące ograniczenia. Nie możesz używać go przez inny protokół niż TCP, połączenie z instancją SQL Server skonfigurowaną z więcej niż 64 adresami IP zawodzi, a nie da się jej używać z mirroringiem bazy danych. Dublowanie baz danych zostało wycofane we wszystkich obsługiwanych wersjach programu SQL Server. Zamiast tego użyj grup dostępności Always On.

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.

Zastrzeżone słowa kluczowe

Tryby uwierzytelniania Microsoft Entra

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

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

Jeśli celem jest serwerless Azure SQL Database z włączonym automatycznym pauzowaniem, użyj co najmniej 60. Automatycznie wstrzymana baza danych wznawia się przy pierwszej próbie połączenia, a krótszy czas wygasa przed zakończeniem wznowienia. Próba może również zakończyć się błędem 40613 podczas wznowienia działania bazy danych, więc aplikacja musi spróbować ponownie. Więcej informacji znajdziesz w sekcji Automatyczne wstrzymywanie i automatyczne wznawianie.

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)

Obiekty poświadczeń

Zamiast nazywać tryb uwierzytelniania w parametry połączenia, możesz przekazać sterownikowi obiekt poświadczenia z parametremtoken_provider. Ten parametr akceptuje dowolny obiekt z metodą get_token(scope) , w tym wszystkie dane poświadczenia w azure-identity pakiecie:

import mssql_python
from azure.identity import DefaultAzureCredential

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Encrypt=yes",
    token_provider=DefaultAzureCredential(),
)

Nie łącz token_provider z Authentication tym samym słowem kluczowym w tym samym powiązaniu. Kierowca podnosi się InterfaceError , gdy obaj są obecni. Aby uzyskać więcej informacji, zobacz Microsoft Entra authentication (Uwierzytelnianie w usłudze Microsoft Entra).

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

• Buduj łańcuchy połączeń programatycznie
• Install mssql-python
• Microsoft Entra authentication with mssql-python
• Pulowanie połączeń z mssql-python
• Zarządzanie połączeniami za pomocą mssql-python