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 lokalnego rozwoju, kontenerów i 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 | Nazwa serwera usługi głównej dla uwierzytelniania Kerberos. |
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 w dostawcach znajdziesz w sekcji Funkcje obsługiwane natywnym dostawcą.
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
msodbcsql18z ; zwykle yes zmssql-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 |
Zadeklaruj typ obciążenia aplikacji. 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. |
Nazwa aplikacji
Ustaw nazwę aplikacji, aby móc odróżnić swoje obciążenia podczas monitorowania po stronie serwera.
| Keyword | Alias | Domyślnie | Opis |
|---|---|---|---|
APP |
Application Name |
MSSQL-Python |
Nazwę, którą serwer raportuje dla Twojego połączenia. |
Kierowca zwiększa MSSQL-Python| początek Twojej wartości. Na przykład raporty APP=orders-apiMSSQL-Python|orders-api do serwera.
Możesz także podać app="orders-api" do connect(). Podobnie jak w przypadku innych słów kluczowych połączenia, argument słowa kluczowego nadpisuje wartość w parametry połączenia.
Nazwa pojawia się w i APP_NAME()sys.dm_exec_sessions.program_name. W dedykowanych pulach SQL Azure Synapse zamiast tego zapytajsys.dm_pdw_exec_sessions.app_name. Więcej informacji znajdziesz w sys.dm_pdw_exec_sessions.
Połączenia synchroniczne, eksperymentalna natywna ścieżka asynchroniczna oraz kopiowanie masowe wysyłają tę samą nazwę. Różne nazwy tworzą oddzielne pule połączeń, więc używaj jednej nazwy dla każdego obciążenia.
Twoja wartość nie może być pusta i musi być poprawna w Unicode. Pełna nazwa, w tym MSSQL-Python|, może obejmować do 128 jednostek kodu UTF-16, co daje 115 dla Twojej wartości. Niektóre znaki, takie jak emoji, używają dwóch jednostek kodowych. Nieprawidłowa wartość podnosi ValueError. Przekazanie wartości, która nie jest ciągiem znaków do argumentu app , podnosi TypeError.
Zastrzeżone słowa kluczowe
| Keyword | Opis |
|---|---|
Driver |
Zarezerwowane do użytku wewnętrznego. Sterownik automatycznie zarządza tą wartością. |
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 |
Uwierzytelnianie zintegrowane z Windows z 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 ustawieniem, które ogranicza każde polecenie, a nie próbę uwierzytelniania. 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, APP |
Supported. Sterownik dodaje własną nazwę na początku Twojej wartości. Aby uzyskać więcej informacji, zobacz Nazwa aplikacji. |
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. |
Sterownik ustawia Driver się sam, więc zgłasza błąd zarezerwowanego słowa kluczowego dla zamiast Driver nieznanego błędu słowa kluczowego.