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

mssql-python ładuje jeden 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

Ten artykuł omawia dostawcę mssql-odbc udostępnionego w mssql-python-rs wersji 0.5.0 oraz różnice od msodbcsql18.

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 ustawia MultiSubnetFailover=yes dla kwalifikujących się połączeń TCP. Ustaw MultiSubnetFailover=no dla prób sekwencyjnych. Aby zmienić domyślne wdrożenie, ustaw MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT na true lub false (bez rozróżniania wielkości liter) przed pierwszym użyciem sterownika. Inne wartości powodują błąd, chyba że zostaną zastąpione ustawieniem dla tego połączenia.

Słowo kluczowe typu connection-string nadpisuje domyślne ustawienie środowiska. Atrybut pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) nadpisuje oba ustawienia.

Domyślnie wyklucza transporty niebędące TCP, mirroring baz danych oraz nazwane instancje wymagające wykrywania przez przeglądarkę SQL Server. Te również odrzucają jawne MultiSubnetFailover=yes.

W systemie Windows domyślna opcja jest również wyłączona dla lokalnych adresów bez prefiksu, takich jak localhost. Jawne określenie prefiksu lub portu TCP, takie jak tcp:localhost lub localhost,1433, zapobiega temu wykluczeniu lokalnego celu. Jawne MultiSubnetFailover=yes również ją nadpisuje. Zobacz Wysoka dostępność i przełączanie awaryjne.

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).
Odporność sieci Obsługiwane połączenia TCP domyślnie używają równoległych prób adresów. Tryb równoległy nie nadaje priorytetu adresom według IpAddressPreference i odrzuca więcej niż 64 rozpoznanych adresów. Informacje o próbach sekwencyjnych i kolejności rodzin adresów można znaleźć w domyślnym przełączaniu awaryjnym wielopodsieci. Oddzielny algorytm Transparent Network IP Resolution (TNIR) nie jest implementowany. Buforowanie systemu nazw domen (DNS) wspomagane przez serwer umożliwia przełączenie na adres z pamięci podręcznej w przypadku awarii DNS po pomyślnym logowaniu, gdy serwer zezwala na buforowanie. Ulepszone trasowanie jest używane po wynegocjowaniu z serwerem.
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. Na macOS Encrypt=Strict połączenia TCP mogą negocjować TLS 1.3 z kompatybilnym serwerem.
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 i binarne są przesyłane do serwera na zwykłej ścieżce wiązania. Jawne powiązania SQL_SS_XML i SQL_SS_UDT przez setinputsizes() również są przesyłane strumieniowo, gdy Python wybiera dane przy wykonaniu: zadeklarowany rozmiar musi przekraczać 4000 dla str lub 8000 dla bytes lub bytearray. Powiązanie typu zdefiniowanego przez użytkownika (UDT) wymaga, aby serwer opisał typ parametru. Niektóre niestandardowe i mieszane powiązania nadal buforują. Aby uzyskać więcej informacji, zobacz Znane problemy.
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(), iteracyjne pobieranie, fetchval(), konwersja typowana oraz strumieniowanie dużych tekstów/binarnych.
Pobieranie strzałek arrow_batch(), arrow()i arrow_reader(). Wymaga pyarrow.
Wiele zestawów wyników nextset(), w tym wyniki generowane 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=...).
Limit czasu operacji połączeniowych conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) Dotyczy żądań sieciowych należących do połączenia, w tym zatwierdzania transakcji, wycofania transakcji oraz zmian katalogu i izolacji. Reset puli przesuwa reset serwera do następującego żądania ustawienia izolacji; zarówno to żądanie, jak i wszelkie wcześniejsze wycofanie wykorzystują ten limit czasu. 0 pozostawia te żądania nieograniczone. Ten limit czasu jest oddzielny od limitów logowania i zapytania i nie jest ostatecznym limitem czasu uzyskania połączenia z puli. Sprzątanie po anulowaniu może wydłużyć czas trwania wywołania.
Czyszczenie kursora Zamknięcie kursora anuluje oczekującą pracę na serwerze, gdy jest to potrzebne, zamiast odczytywać wszystkie pozostałe wyniki. Czyszczenie przygotowanego wyrażenia respektuje limit czasu zapytania. Sprzątanie po anulowaniu ma dodatkowy budżet oczekiwania równy limitowi czasu połączenia lub 120 sekund, gdy ten limit czasu wynosi 0.
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.
Wielowątkowość Równoczesne połączenia i zapytania z osobnym połączeniem i kursorem dla każdego wątku roboczego. Nie udostępniaj kursorów między wątkami.
API metadanych tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), getTypeInfo(), rowVerColumns(), procedures() oraz getinfo(). SQL_USER_NAME raportuje użytkownika bazy danych, a nie parametr UID ciągu połączenia. Wartości zdolności i limity dotyczące rozmiaru pakietu mogą różnić się od msodbcsql18: SQL_NEED_LONG_DATA_LEN raportuje "N", ponieważ długie wejście nie wymaga zadeklarowanej całkowitej długości. Wykorzystaj zwrócone obsługiwane funkcje i limity.
Kodowanie i konwertery Domyślne kodowanie szerokoznakowe, konwertery wyjściowe, parametry nie-Unicode uwzględniające sortowanie oraz wyniki wąskoznakowe w kodowaniu klienta platformy. Niestandardowe dekodowanie znaków jednobajtowych musi odpowiadać temu kodowaniu; niezgodność może spowodować wyświetlanie nieprawidłowego tekstu lub bytes. Użyj conn.setdecoding(mssql_python.SQL_CHAR) do przywrócenia domyślnego dekodowania szerokoznakowego. W przypadku podstawiania parametrów niezgodnych z Unicode, 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.

Jeśli pobieranie jest uruchomione po zamknięciu , arrow_reader()close() anuluje pobieranie i wraca po jego zatrzymaniu. Zamknięcie czytnika dla wcześniejszego zapytania nie wpływa na późniejsze zapytanie na tym samym kursorze. 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 ograniczenia przed przełączeniem obciążenia z msodbcsql18. Poniższa tabela wskazuje zamierzone wykluczenia.

Issue Details Workaround
Uwierzytelnianie hasłem Microsoft Entra ID (celowe wykluczenie) Authentication=ActiveDirectoryPassword nie jest obsługiwane, a wsparcie nie jest planowane, ponieważ ta metoda nie może sprostać wymaganiom 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.
ustawienia attrs_before Selektor uwierzytelniania numerycznego (SQL_COPT_SS_AUTHENTICATION) oraz atrybut zamiaru aplikacji pozostają nieobsługiwane. Atrybuty wielopodsieciowego przełączania awaryjnego oraz zintegrowanego zabezpieczenia są implementowane. Dopasowanie identyfikatora metadanych (SQL_ATTR_METADATA_ID) również nie jest obsługiwane. Użyj słów kluczowych Authentication i ApplicationIntent connection-string, jeśli to stosowne.
fork() po nawiązaniu połączenia 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.
Wykorzystanie pamięci z niestandardowymi wiązaniami dużych parametrów Wartości data-at-execution powiązane jako typy o stałej szerokości SQL_CHAR, SQL_WCHAR lub SQL_BINARY są buforowane na potrzeby konwersji. Mieszanie parametrów buforowanych i strumieniowych może również buforować wcześniejsze duże wartości, czekając na późniejszą wartość buforowaną. Preferuj domyślne powiązania o zmiennej długości. Unikaj dużych wymuszeń o stałej szerokości tam, gdzie ważne jest zużycie pamięci, przez setinputsizes().
Podstawianie znaków spoza Unicode Dla znaków spoza docelowej strony kodowej parametru nie-Unicode sterownik może zastąpić je znakiem ?, gdzie msodbcsql18 używa znaku najlepiej dopasowanego. Preferuj typy SQL Unicode oraz domyślne wiązania ciągów znaków w Pythonie, gdy tekst musi być zachowany.
Zmiany izolacji po surowym SQL Po raw SQL SET TRANSACTION ISOLATION LEVEL ustawienie atrybutu połączenia na poziom buforowany sterownika może zwrócić sukces bez przywracania tego poziomu na serwerze. (#798) Unikaj mieszania surowego SQL i zmian izolacji opartych na atrybutach. Użyj jawnego SET TRANSACTION ISOLATION LEVEL podczas przywracania poziomu.
Niepowodzenia z powodu braku 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. Wyniki zależą od platformy i obciążenia. (#473) Przeprowadź test porównawczy swojego obciążenia.

Ta lista nie jest wyczerpująca.

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 przy zaznaczonym mssql-odbc. Na Linuksie pozostaw MSSQL_TDS_TRACE nieustawione z powodu błędu zakończenia procesu opisanego w sekcji Znane problemy.

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"

MSSQL_TDS_TRACE włącza śledzenie, MSSQL_TDS_TRACE_LEVEL wybiera filtr dziennika 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łędów. MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB ustawia próg rollover na plik (domyślnie 100 MiB; akceptuje 1-1024). To nie jest całkowity limit miejsca na dysku: pojedyncze pliki mogą przekroczyć próg, a stare pliki nie są usuwane. Pakiet towarzyszący Rust również tworzy pliki logów pod mssql_python_logs w aktualnym katalogu. Po zmianie tych ustawień zrestartuj Python.

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