Używanie sterownika mssql-odbc (Wersja zapoznawcza)

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

Provider Co to jest Status
msodbcsql18 Microsoft ODBC Driver 18 dla SQL Server, ugruntowany sterownik C++ Domyślne; bez zmian
mssql-odbc Nowy sterownik ODBC napisany w Rust Zapowiedź, zgoda

Ten artykuł omawia mssql-odbcwersję 0.3.0, obecnie używaną przez mssql-python, oraz to, czym różni się od msodbcsql18.

Note

mssql-odbc jest aktywnie rozwijany i walidowany. Nie jest to jeszcze całkowite zastąpienie Microsoft ODBC Driver 18. Na razie zostaw msodbcsql18 jako domyślne ustawienie dla środowiska produkcyjnego. Zespół deweloperski planuje usunąć braki w wersji zapoznawczej w nadchodzących wydaniach, z wyjątkiem celowych wykluczeń wyraźnie wskazanych w tym artykule.

Availability

Sterownik jest dostępny wewnątrz pakietu mssql-python-rs jako gotowe wheels dla CPython 3.10 i późniejszych:

Platform Architektury
Windows x64; ARM64 na CPython 3.11+
macOS universal2 (x86_64 + arm64), macOS 15 lub nowszy
Linux (glibc) x86_64, aarch64 — manylinux_2_28 oraz manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Włączanie sterownika

Pakiet mssql-python zależy od mssql-python-rs, więc normalna instalacja przynosi ze sobą sterownik Rust:

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 pierwszym połączeniem, albo za pomocą zmiennej środowiskowej:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash czy Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

lub z Pythona:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Połącz się, używając istniejącego parametry połączenia swojej aplikacji. Zachowaj włączoną walidację certyfikatów (Encrypt=yes;TrustServerCertificate=no). Aby uzyskać informacje o uwierzytelnianiu i konfiguracji certyfikatów, zobacz Ciągi połączenia oraz Szyfrowanie i certyfikaty.

connection = mssql_python.connect(connection_string)

Kierowca stosuje następujące zasady przy wyborze dostawcy:

  • Zmienna środowiskowa MSSQL_PYTHON_NATIVE_PROVIDER ma pierwszeństwo przed native_provider. Przypisanie atrybutów konfliktowych powoduje RuntimeWarning.
  • Wybór staje się ustalony po walidacji ciągu połączeń i tuż przed utworzeniem połączenia natywnego. Kolejna awaria połączenia nie usuwa zaznaczenia. Wcześniejszy błąd parsowania stringów połączeń lub brak pakietu dostawcy nie zmienia wyboru. Po ustaleniu selekcji zmiana native_provider na innego dostawcę emituje RuntimeWarning i nie ma żadnego efektu. Rozpocznij proces od nowa, aby zmienić dostawcę.
  • Nierozpoznana nazwa dostawcy podnosi ValueError; sterownik nie przełącza się na domyślnego dostawcę. Nieznane imię przypisane do native_provider natychmiast zgłasza wyjątek. Nieznana nazwa w zmiennej środowiskowej powoduje błąd, gdy próbujesz się połączyć.
  • Ustaw native_provider na None, aby usunąć wybór atrybutów, zanim zostanie on ustalony. Zmienna środowiskowa nadal ma pierwszeństwo.

Kliknij mssql_python.get_native_provider_info(), aby sprawdzić wybranego dostawcę, źródło wyboru oraz czy selekcja jest stała. Przed połączeniem ten komunikat raportuje wybór, a nie dowód, że natywny sterownik został pomyślnie załadowany.

Aby cofnąć się, ustaw zmienną na msodbcsql18, lub usuń jej ustawienie i usuń dowolne native_provider przypisania z kodu (albo ustaw ją na "msodbcsql18"). Następnie rozpocznij proces od nowa.

Co działa dziś

Sterownik mssql-odbc implementuje każdą funkcję ODBC wywoływaną przez mssql-python, dzięki czemu większość aplikacji może zmieniać dostawców bez zmian w kodzie. Sprawdź Znane problemy, aby sprawdzić pozostałe różnice.

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).
Authentication uwierzytelnianie SQL (UID / PWD); uwierzytelnianie systemu Windows (Trusted_Connection=Yes, przy użyciu SSPI w systemie Windows lub Kerberos w systemie Linux i macOS); oraz interakcyjne uwierzytelnianie Microsoft Entra, kod urządzenia, jednostka usługi, tożsamość zarządzana, domyślne poświadczenia i token dostępu. Uwierzytelnianie zintegrowane Entra i uwierzytelnianie hasłem nie są obsługiwane; zobacz Znane problemy.
magazyn lokalny wątku 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, outer-join, GUID, LIKE ... {escape ...}, interwał oraz {encrypt ...} formy escape.
Procedury przechowywane Wołaj je za pomocą składni T-SQL lub pozycyjnej {call ...} przez execute(), odczytuj zbiory wyników i przesuwaj się za pomocą nextset().
Parametry wejściowe Parametry skalarne, SQL NULL, setinputsizes(), oraz mieszane parametry regularne/streamowane.
Duże parametry Duży tekst i parametry binarne przesyłane są do serwera na zwykłej ścieżce wiązania; Ograniczenia parametrów XML i UDT są wymienione poniżej.
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 Autocommit, commit, rollback, automatyczny commit (lub rollback, jeśli wystąpił błąd), który następuje po zakończeniu bloku with connect(...), oraz poziomy izolacji read-uncommitted, read-committed, repeatable-read, serializable i snapshot isolation.
Przekroczenie limitu czasu zapytania Ustaw Connection.timeout (w sekundach), aby ograniczyć instrukcje wykonywane przez kursory tego połączenia; wygaśnięcie zgłasza wyjątek OperationalError. 0 oznacza brak limitu czasu. To ustawienie jest oddzielne od limitu czasu logowania przekazywanego jako connect(timeout=...).
Buforowanie połączeń Wbudowana pulamssql-python, w tym reset połączenia podczas pobierania z puli oraz oddzielne pule dla tożsamości Microsoft Entra.
API metadanych tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), i getTypeInfo().
Kodowanie i konwertery Domyślne kodowanie szerokoznakowe i konwertery wyjściowe. Niestandardowe dekodowanie znaków wąskich oraz konwersja parametrów nie-Unicode mają ograniczenia wymienione w sekcji Znane problemy.

Typy danych

Możesz odczytać wszystkie typy danych SQL Server, a sterownik obsługuje każdy typ parametrów, który wiąże mssql-python. Sterownik zwraca wartości xml, vector oraz str jako vector (geometry jako tablica JSON) oraz typy CLR takie jak geography, hierarchyid oraz bytes jako json. Aby poznać inne mapowania w Python, zobacz mapowania typów danych. Ograniczenia dotyczące poszczególnych typów: zobacz Znane problemy.

Znane problemy

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

Issue Details Workaround
Zintegrowane uwierzytelnianie firmy Microsoft Authentication=ActiveDirectoryIntegrated nie jest obsługiwany. Uwierzytelnianie systemu Windows (Trusted_Connection=Yes) pozostaje bez zmian. Użyj innej metody Microsoft Entra lub zostaw msodbcsql18.
Microsoft Entra password authentication (Uwierzytelnianie haseł firmy Microsoft w usłudze Entra) Authentication=ActiveDirectoryPassword nie jest obsługiwane, a wsparcie nie jest planowane, ponieważ ta metoda nie spełnia wymagań MFA. Uwierzytelnianie SQL (UID / PWD) nie jest zmienione. Użyj innej metody Microsoft Entra, takiej jak jednostka usługi, zarządzana tożsamość lub token dostępu.
attrs_before ustawienia Uwierzytelnianie, intencja aplikacji oraz przełączanie awaryjne wielu podsieci nie mogą być ustawiane jako atrybuty liczbowe. Atrybuty instrukcji inne niż timeout zapytania są odrzucane. Użyj równoważnych słów kluczowych ciągu połączenia.
Przekroczono limit czasu operacji połączenia set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) akceptuje i przechowuje wartość, ale nie wymusza timeoutu w wersji 0.3.0. Użyj connect(timeout=...) do logowania i Connection.timeout do wyciągów; żadne z nich nie jest ogólnym limitem czasu operacji połączenia.
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. Bez MultiSubnetFailover=Yes, adresy są próbowane pojedynczo, więc adres nieosiągalny może opóźnić połączenie. Wspomagane serwerowo buforowanie DNS i ulepszone trasowanie nie są negocjowane. Ustaw MultiSubnetFailover=Yes dla detektorów odbioru grupy dostępności i innych hostów wieloadresowych.
Tymczasowe awarie DNS Jeśli wyszukiwanie DNS się nie powiedzie, sterownik nie przełącza się z powrotem na ostatni poprawny adres. (#457) Ponów próbę nawiązania połączenia.
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.
Wielowątkowość Użycie wielowątkowe nie zostało zweryfikowane. Zachowaj msodbcsql18 dla obciążeń wielowątkowych.
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.
Anulowanie bieżącej instrukcji Nie można przerwać bieżącego zapytania ani pobierania. Na przykład zamknięcie arrow_reader() nie zatrzymuje odczytu będącego w toku w innym wątku. Użyj Connection.timeout, aby ograniczyć długotrwałe instrukcje.
Nieprzeczytane wyniki Zamknięcie kursora lub uruchomienie kolejnego polecenia odczytuje i odrzuca pozostałe wyniki zamiast ich anulować, co może być powolne. Zamknięcie kursora, który używał przygotowanej instrukcji, ignoruje Connection.timeout i może się zawiesić, jeśli serwer przestanie odpowiadać. (#546) Pobierz tylko te wiersze, których potrzebujesz, na przykład za pomocą TOP.
Parametry Large xml i UDT Wartości powiązane jako SQL_SS_XML lub SQL_SS_UDT przez setinputsizes() są buforowane w pamięci zamiast przesyłane strumieniowo. Powiąż xml wartości jako zwykłe ciągi znaków.
Wartości puste image Pusta, nie-NULL wartość SQL Server image jest zwracana jako None, a nie jako b"". Przeczytaj CAST(image_column AS varbinary(max))lub użyj msodbcsql18 , gdy rozróżnienie puste/NULL ma znaczenie.
Parametry łańcuchów niebędących w standardzie Unicode Ciągi oznaczone jako char / varchar do setinputsizes() mogą być nieprawidłowo kodowane dla stron kodowych 437, 850 oraz UTF-8. Użyj domyślnego wiązania ciągu.
Dekodowanie starszych stron kodowych na Windows W przypadku setdecoding(SQL_CHAR, encoding="cp1252") lub innej starszej strony kodowej tekst może zostać błędnie zdekodowany lub zwrócony jako bytes, ponieważ sterownik zwraca dane char / varchar jako UTF-8. Użyj ustawienia domyślnego: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME zwraca parametr połączenia UID, a nie użytkownika bazy danych. Jest pusty, gdy żaden UID nie trafia do sterownika. Niektóre wartości zdolności i limity oparte na rozmiarze pakietów różnią się od msodbcsql18. Użyj SELECT USER_NAME() dla użytkownika bazy danych.
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 W jednym z benchmarków odczyty danych varchar(max) / nvarchar(max) w fragmentach były nieco wolniejsze niż w przypadku msodbcsql18. (#473) Przeprowadź test porównawczy swojego obciążenia.

Ta lista nie jest wyczerpująca.

Zgłaszaj problemy

Jeśli napotkasz błąd, wybierz msodbcsql18, restartuj proces i sprawdź, czy zachowanie nadal występuje. Usuń też wszelkie przypisania dostawcy powodujące konflikt po stronie Pythona. Porównanie pomaga wyizolować problem; samo w sobie nie dowodzi jego przyczyny. Dołącz wynik mssql_python.get_native_provider_info(), informacje o swojej platformie oraz zapytanie SQL, które zakończyło się błędem, lub komunikat o błędzie:

Do diagnostyki sterownika Rust ustaw te zmienne przed uruchomieniem Python i odtwórz problem z mssql-odbc wybranym. Na przykład w programie PowerShell:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Włącza śledzenie, MSSQL_TDS_TRACE_LEVEL wybiera filtr logów i MSSQL_TDS_TRACE_DIR zapisuje pliki dla każdego procesu zamiast STDERR. Po zmianie tych ustawień zrestartuj Python. Ślady mogą zawierać tekst SQL i wartości parametrów. Przejrzyj i zanonimizuj wrażliwe dane przed udostępnieniem odpowiednich fragmentów oraz wyłącz śledzenie po diagnozie.

Treści powiązane

  • Ostatnia aktualizacja o