Użyj sterownika mssql-odbc (Podgląd)

mssql-python wczytuje jednego z dwóch natywnych dostawców ODBC:

Provider Description Status
msodbcsql18 Sterownik Microsoft ODBC 18 dla programu SQL Server Domyślny
mssql-odbc Sterownik ODBC oparty na Rust Podgląd, zgoda

Pakiet mssql-python-rs0.4.0 zawiera także provider mssql-odbc.

Note

Użyj msodbcsql18 do zadań produkcyjnych. Zanim zdecydujesz się na dostawcę wersji zapoznawczej mssql-odbc, zapoznaj się z jego znanymi problemami.

Availability

Driver jest dostarczany wewnątrz pakietu mssql-python-rs jako gotowe pakiety wheel dla wersji CPython 3.10 i późniejszych:

Platform Architektury
Windows x64; ARM64 na wersjach CPython 3.11 i późniejszych
macOS universal2 (x86_64 i arm64), macOS 15 i późniejsze wersje
Linux (glibc) x86_64 i aarch64 (manylinux_2_28 oraz manylinux_2_34)
Linux (musl) x86_64 i aarch64 (musllinux_1_2)

Włącz sterownik

Instalacja mssql-python również instaluje mssql-python-rs, które zawiera sterownik mssql-odbc:

python -m pip install mssql-python

Jeśli instalujesz za pomocą --no-deps lub z prywatnego indeksu, jawnie zainstaluj również mssql-python-rs.

Wybierz dostawcę przed otwarciem pierwszego połączenia. Użyj jednej z następujących metod.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Ustaw zmienną środowiskową MSSQL_CONNECTION_STRING na parametry połączenia aplikacji. Zachowaj włączoną walidację certyfikatów (Encrypt=yes;TrustServerCertificate=no). Więcej informacji można znaleźć w parametrach połączenia oraz Szyfrowanie i certyfikaty.

Użyj tego przykładu z wybranym przez siebie dostawcą:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

Przykład wyświetla 1.

Wybór dostawcy odbywa się zgodnie z następującymi zasadami:

  • MSSQL_PYTHON_NATIVE_PROVIDER ma pierwszeństwo przed native_provider. Ustawienie atrybutu na powodującego konflikt dostawcę generuje RuntimeWarning.
  • Przed załadowaniem sterownika ustaw opcję native_provider na None, aby wyczyścić ustawienie Python. To nie czyści zmiennej środowiskowej.
  • Nierozpoznana nazwa dostawcy powoduje ValueError. Przypisanie nieprawidłowej nazwy do native_provider natychmiast zgłasza wyjątek; nieprawidłowa zmienna środowiskowa zgłasza wyjątek przy nawiązywaniu połączenia. Sterownik nie przełącza się na domyślnego dostawcę.
  • Dostawca jest ustalany, gdy sterownik rozpoczyna natywną próbę połączenia, nawet jeśli ta próba się nie powiedzie. Uruchom ponownie Python, aby przełączyć dostawcę. Zmiana na innego dostawcę native_provider emituje RuntimeWarning i nie ma żadnego efektu.

Błędy walidacji ciągu połączeń oraz brakujące pakiety dostawców występują przed tym punktem. Możesz poprawić te błędy i wybrać innego dostawcę bez restartu.

Zadzwoń, mssql_python.get_native_provider_info() aby sprawdzić nazwę dostawcy, sposób wyboru i czy wybór jest stały.

Aby wrócić do msodbcsql18, usuń MSSQL_PYTHON_NATIVE_PROVIDER i usuń dowolne native_provider przypisania z aplikacji, a następnie zrestartuj Python.

Domyślne przełączanie awaryjne w wielu podsieciach

Dostawca Rust domyślnie włącza MultiSubnetFailover dla odpowiednich połączeń protokołu Transmission Control Protocol (TCP). Ustaw MultiSubnetFailover=no jawnie, aby zażądać kolejnych prób połączenia. Aby zmienić domyślne ustawienie dla całego wdrożenia, ustaw MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT na true lub false przed pierwszym użyciem natywnego sterownika. Słowo kluczowe typu connection-string nadpisuje tę wartość domyślną.

Atrybut liczbowy SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) również nadpisuje słowo kluczowe, jeśli zostanie ustawiony przed nawiązaniem połączenia.

Sterownik nie włącza tego ustawienia domyślnego dla transportów niebędących TCP, mirroringu baz danych, nazwanych instancji wymagających wykrywania przez przeglądarkę SQL Server ani lokalnych połączeń Windows, które pomijają jawny protokół i adres. Jawne włączenie MultiSubnetFailover dla transportu innego niż TCP, kopii lustrzanej bazy danych lub wykrywania przez przeglądarkę SQL Server powoduje błąd połączenia. Więcej informacji można znaleźć w artykule High availability and failover.

Obsługiwane funkcje

Obsługiwane są następujące funkcje, z zastrzeżeniem znanych problemów.

Area Notes
Cykl życia połączenia Connect, close(), with blocks, limit czasu logowania, diagnostyka i zmiana aktualnej bazy danych. Ustawienia łańcucha połączeń obejmują ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, oraz ConnectRetryCount / ConnectRetryInterval (odporność bezczynnego połączenia). Natywny sterownik negocjuje także buforowanie systemu nazw domen (DNS) wspomagane przez serwer oraz ulepszone routowanie, gdy serwer to obsługuje.
Authentication uwierzytelnianie SQL (UID / PWD); uwierzytelnianie systemu Windows (Trusted_Connection=Yes, z użyciem Security Support Provider Interface (SSPI) na Windows lub Kerberos na Linuksie i macOS); oraz uwierzytelnianie Microsoft Entra ID: interaktywne, zintegrowane, kod urządzenia, nazwa główna usługi, tożsamość zarządzana, domyślne dane uwierzytelniające oraz token dostępu. Uwierzytelnianie hasłem Microsoft Entra ID nie jest obsługiwane. Aby uzyskać więcej informacji, zobacz Znane problemy.
Bezpieczeństwo warstwy transportowej (TLS) Encrypt, TrustServerCertificate, HostnameInCertificate i ServerCertificate.
Wykonywanie zapytania Bezpośrednia i przygotowana realizacja, ponowne użycie przygotowanego planu, parametry qmark oraz konwersja wykonywana przez pyformatmssql-python.
Składnia sekwencji ucieczki ODBC Funkcja, data/czas, zewnętrzne połączenie, globalnie unikalny identyfikator (GUID), LIKE ... {escape ...}, interwał oraz formy ucieczki {encrypt ...}.
Procedury przechowywane Wywołuj je za pomocą Transact-SQL (T-SQL) lub składni pozycyjnej {call ...} za pośrednictwem execute(), czytaj zbiory wyników i przechodź dalej za pomocą nextset().
Parametry wejściowe Parametry skalarne, SQL NULL, setinputsizes(), oraz mieszane parametry regularne/streamowane.
Duże parametry Duże parametry tekstowe, binarne, rozszerzalny język znaczników (XML) oraz typy zdefiniowane przez użytkownika (UDT) wspierają strumieniowanie danych w czasie wykonywania.
executemany() Przetwarzane partiami z macierzami parametrów ODBC. Wiersze zawierające wartości strumieniowe wracają do wykonywania wiersz po wierszu.
Pobieranie wierszy fetchone(), fetchmany(), fetchall(), iteracja, fetchval(), konwersja typu oraz duże strumieniowanie tekstowe/binarne.
Pobieranie strzałek arrow_batch(), arrow() oraz arrow_reader(). Wymaga pyarrow.
Wiele zestawów wyników nextset(), w tym wyniki uzyskane przez tablice parametrów.
Transakcje Automatyczne zatwierdzanie, zatwierdzanie, wycofanie oraz poziomy izolacji read-uncommitted, read-committed, repeatable read, serializable i izolacja migawkowa. Po wyłączeniu automatycznego zatwierdzania menedżer kontekstu połączenia zatwierdza po pomyślnym zakończeniu i wycofuje zmiany w przypadku wyjątku.
Przekroczenie limitu czasu zapytania Ustaw Connection.timeout w sekundach przed utworzeniem kursora. Gdy instrukcja przekroczy ten limit czasu, sterownik zgłasza OperationalError. 0 oznacza brak limitu czasu. Ustaw limit czasu logowania osobno za pomocą connect(timeout=...).
Buforowanie połączeń Wbudowana pula mssql-python obejmuje resetowanie połączenia przed ponownym użyciem. Dla izolacji puli specyficznej dla uwierzytelniania, zobacz Izolacja tożsamości.
API metadanych tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), i getTypeInfo().
Kodowanie i konwertery Domyślne kodowanie znaków szerokich, konwertery wyjściowe oraz parametry nieobsługujące Unicode zależne od sortowania, w tym kolejności sortowania UTF-8 i starsze kolejności sortowania SQL sort-ID. Niestandardowe dekodowanie znaków jednobajtowych musi odpowiadać kodowaniu klienta. Aby uzyskać więcej informacji, zobacz Znane problemy.

Zintegrowane uwierzytelnianie Microsoft Entra ID wykorzystuje zalogowane konto Windows w systemie Windows. W systemach Linux i macOS używa biletu Kerberos do uwierzytelnienia w punkcie końcowym usług Active Directory Federation Services (AD FS) dzierżawy. Informacje o wymaganiach wstępnych znajdują się w artykule Windows Integrated authentication.

Zamknięcie arrow_reader() wysyła SQLCancel, aby przerwać trwające pobieranie. Wywołanie close czeka na zakończenie czyszczenia po anulowaniu. Więcej informacji można znaleźć w artykule o integracji z Apache Arrow.

Typy danych

Sterownik zwraca wartości xml, json i wektor jako obiekty Pythonstr, a wektor reprezentowany jest jako tablica JavaScript Object Notation (JSON). Zwraca typowe typy środowiska uruchomieniowego common language (CLR), takie jak geometry, geography i hierarchyid, jako obiekty Pythonbytes. Więcej informacji można znaleźć w sekcji Mapowania typów danych i Znane problemy.

Znane problemy

Sprawdź te różnice przed przeniesieniem obciążenia z msodbcsql18.

Issue Details Workaround
Microsoft Entra ID uwierzytelnianie hasłem Authentication=ActiveDirectoryPassword nie jest obsługiwany. Ta metoda nie spełnia wymagań uwierzytelniania wieloskładnikowego (MFA). Uwierzytelnianie SQL (UID / PWD) nie jest zmienione. Użyj innej metody Microsoft Entra ID, takiej jak jednostka usługi, zarządzana tożsamość lub token dostępu.
attrs_before ustawienia Tryb uwierzytelniania Microsoft Entra ID i intencja aplikacji nie mogą być ustawione jako numeryczne atrybuty połączenia. Użyj słów kluczowych parametrów połączenia Authentication i ApplicationIntent.
Przekroczono limit czasu operacji połączenia SQL_ATTR_CONNECTION_TIMEOUT steruje sprzątaniem po anulowaniu. Nie wymusza limitu czasu przy resetowaniu połączenia z puli. Prośba o połączenie może pozostać zablokowana, jeśli serwer przestanie odpowiadać podczas resetu. Nie ma dostępnego limitu czasu resetu puli. Ustaw connect(timeout=...) do logowania i Connection.timeout do wyciągów.
Hosty wieloadresowe msodbcsql18 domyślnie włącza Transparent Network IP Resolution (TNIR); mssql-odbc nie obsługuje go. mssql-python odrzuca TransparentNetworkIPResolution słowo kluczowe connection string u dowolnego z dostawców. Użyj MultiSubnetFailover=yes dla detektorów grup dostępności i innych hostów wieloadresowych. Informacje o ustawieniach domyślnych można znaleźć w Domyślne ustawienia trybu failover dla wielu podsieci.
Klasyfikacja danych Metadane klasyfikacji wrażliwości nie są dostępne, a SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) nie jest obsługiwane. Wyszukaj sys.sensitivity_classifications.
fork() po połączeniu W Linuksie proces rozwidlony po tym, jak proces nadrzędny nawiąże połączenie, może się zawiesić podczas korzystania ze sterownika, nawet przy nowym połączeniu. Przy włączonym poolingu rodzic też może się zawiesić. (#566) Użyj metody start spawn i nawiąż połączenie wewnątrz każdego workera.
Natywne śledzenie na Linuksie Przy włączonym natywnym śledzeniu Python może zakończyć działanie podczas czyszczenia sterowników podczas zamykania procesu. Pozostaw MSSQL_TDS_TRACE nieustawione na Linuksie.
Nieprzeczytane wyniki Zamknięcie kursora lub uruchomienie kolejnego polecenia odczytuje i odrzuca pozostałe wyniki zamiast ich anulować, co może być powolne. Czyszczenie prepared statement wykorzystuje limit czasu zapytania instrukcji, ale zerowy timeout pozostawia to czyszczenie nieograniczone. Pobierz tylko te wiersze, które są potrzebne, na przykład za pomocą TOP i ustaw Connection.timeout przed utworzeniem kursora.
Niestandardowe dekodowanie znaków wąskich Natywny sterownik korzysta ze strony kodowej Windows ANSI w systemie Windows oraz ze strony kodowej ustawień regionalnych procesu w systemach Linux i macOS do wąskiego tekstu. Jawne dekodowanie w Pythonie, które nie pasuje do tej strony kodowej, może spowodować błędny tekst lub bytes. Użyj domyślnego dekodowania znaków szerokich: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Niektóre wartości zdolności i limity oparte na rozmiarze pakietów różnią się od msodbcsql18. SQL_USER_NAME raportuje podmiot zabezpieczeń bazy danych, a nie parametry połączenia UID. Odpytaj konkretne metadane serwera, gdy zgłoszona funkcja lub ograniczenie ma znaczenie dla Twojej aplikacji.
Awarie związane z brakiem pamięci Niektóre niepowodzenia alokacji sterownika kończą proces Python zamiast zgłosić MemoryError. (#484) Ogranicz rozmiar wartości, które wysyłasz i pobierasz.
Wydajność odczytu dużych wartości Odczyty fragmentami danych varchar(max) i nvarchar(max) mogą być wolniejsze niż z msodbcsql18. (#473) Przeprowadź test porównawczy swojego obciążenia.

Zgłaszanie problemów

Jeśli napotkasz błąd, odtwórz go za pomocą msodbcsql18 i zanotuj, czy występuje u obu dostawców. Instrukcje zmiany znajdują się w sekcji Włącz sterownik.

Dołącz do raportu wynik polecenia mssql_python.get_native_provider_info(), informacje o swoim systemie operacyjnym, wersje języka Python i sterowników oraz nieudaną partię T-SQL i komunikat o błędzie:

W systemie Windows ustaw te zmienne w PowerShell przed uruchomieniem Pythona, aby zbierać diagnostykę natywnych sterowników. Odtwórz problem z wybranym mssql-odbc:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE umożliwia śledzenie, MSSQL_TDS_TRACE_LEVEL wybiera poziom logu i MSSQL_TDS_TRACE_DIR wybiera katalog dla plików śledzenia dla poszczególnych procesów z natywnego sterownika ODBC zamiast standardowego wyjścia błędu. Pakiet towarzyszący Rust również tworzy pliki logów pod mssql_python_logs w aktualnym katalogu.

Ślady mogą zawierać tekst T-SQL oraz wartości parametrów. Przed udostępnieniem fragmentów zaciemnij dane wrażliwe. Po diagnozie usuń te zmienne i zrestartuj Python, aby wyłączyć śledzenie.

Treści powiązane

  • Ostatnia aktualizacja o