Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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.
| 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 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 rozwiązuje się na więcej niż jeden adres IP, to ustawienie umożliwia próby połączenia równoległego, a sterownik używa pierwszego, który się powiódł. Pominięcie słowa kluczowego nie wyłącza go u dostawcy Rust. Zachowanie Transparent Network IP Resolution (TNIR) dostawcy Microsoft jest oddzielne od tego ustawienia. Różnice między dostawcami znajdziesz w artykule hosty wieloadresowe.
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.
| Keyword | Pseudonimy | Domyślnie | Opis |
|---|---|---|---|
MultiSubnetFailover |
multisubnetfailover |
no z msodbcsql18; zwykle yes z mssql-odbc |
Połącz się ze wszystkimi rozwiązanymi adresami jednocześnie i użyj pierwszego, które się uda. W przypadku domyślnych i wyłączonych funkcji dostawcy Rust zobacz domyślne przełączanie awaryjne w wielu podsieciach. |
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 uwierzytelniania za pomocą parametru timeout . Użyj timeoutu, aby zapobiec zawieszeniu aplikacji na czas nieskończony, gdy serwer jest nieosiągalny:
# 30-second authentication timeout
conn = mssql_python.connect(connection_string, timeout=30)
Connection.timeout jest osobnym ustawieniam, które ogranicza każde zdanie, a nie próbę uwierzytelnienia. Więcej informacji można znaleźć w artykule Timeout połączenia.
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'
Słowa kluczowe z innych sterowników
Walidacja uruchamia się zanim sterownik nawiąże połączenie, więc słowo kluczowe, które akceptują inne sterowniki SQL Server, natychmiast się tu zawodzi. Ciągi połączeń przeniesione z ADO.NET, ODBC lub pyodbc zazwyczaj wymagają następujących podstawień:
| Słowo kluczowe w innych sterownikach | Odpowiednik mssql-python |
|---|---|
Data Source |
Server, lub jego addr i address aliasy |
Initial Catalog |
Database |
User ID |
UID |
Password |
PWD |
Connection Timeout, Connect Timeout, Timeout, Login Timeout |
Parametr timeout .connect() Więcej informacji można znaleźć w artykule Timeout połączenia. |
Application Name |
None. Sterownik ustawia tę wartość i raportuje Application Name jako nieznane słowo kluczowe. |
APP |
None. Sterownik ustawia tę wartość i raportuje APP jako zarezerwowane słowo kluczowe. Więcej informacji można znaleźć w artykule Zarezerwowane słowa kluczowe. |
Pooling, Max Pool Size |
None. Konfiguruj pulowanie w kodzie. Więcej informacji można znaleźć w artykule Pula połączeń. |
Workstation ID, WSID |
None. Usuń słowo kluczowe z parametry połączenia. |
MultipleActiveResultSets, MARS_Connection |
None. Usuń to słowo kluczowe. Aby uruchamiać zapytania równocześnie, używaj oddzielnych połączeń. Więcej informacji można znaleźć w sekcji Wiele kursorów. |
Dla APP i Driver, sterownik zgłasza zarezerwowany błąd słowa kluczowego zamiast nieznanego błędu, ponieważ kontroluje obie wartości.