mssql-odbc 드라이버 사용 (미리보기)

mssql-python 두 가지 네이티브 ODBC 제공자 중 하나를 로드합니다:

Provider 그것이 무엇인지 상태
msodbcsql18 Microsoft ODBC 드라이버 18 for SQL Server, 확립된 C++ 드라이버 기본값, 변경 없음
mssql-odbc Rust로 작성된 새로운 ODBC 드라이버 미리보기, 선택 참여

이 문서에서는 mssql-python, 현재 msodbcsql18에서 사용 중인 버전과 mssql-odbc와의 차이점을 다룹니다.

Note

mssql-odbc 현재 활발히 개발 및 검증 중입니다. 아직 Microsoft ODBC Driver 18을 완전히 대체하는 것은 아닙니다. msodbcsql18를 당분간 프로덕션 기본값으로 유지하세요 개발팀은 이 글에서 명확히 언급된 의도적 제외를 제외하고, 향후 릴리스에서 미리보기 공백을 해소할 계획입니다.

Availability

드라이버는 mssql-python-rs 패키지 안에 CPython 3.10 이후 버전용 사전 제작된 휠로 포함되어 제공됩니다:

Platform Architectures
Windows CPython 3.11+의 x64; ARM64
macOS universal2 (x86_64 + arm64), macOS 15 이상 버전
Linux(glibc) x86_64, aarch64 — manylinux_2_28 그리고 manylinux_2_34
리눅스 (musl) x86_64, aarch64 — musllinux_1_2

드라이버 활성화

mssql-python 패키지는 mssql-python-rs에 의존하므로 일반 설치에는 Rust 드라이버가 함께 포함됩니다:

pip install mssql-python

--no-deps로 설치하거나 프라이빗 인덱스에서 설치하는 경우, mssql-python-rs도 명시적으로 설치하세요.

첫 연결 전에 제공자를 선택하거나, 환경 변수로:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

배쉬 또는 Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

또는 Python에서:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

애플리케이션의 기존 연결 문자열을 사용해 연결하세요. 인증서 검증은 활성화 상태로 유지하세요 (Encrypt=yes;TrustServerCertificate=no). 인증 및 인증서 설정에 대해서는 연결 문자열 과 암호화 및 인증서를 참조하세요.

connection = mssql_python.connect(connection_string)

드라이버는 공급자를 선택할 때 다음과 같은 규칙을 적용합니다:

  • MSSQL_PYTHON_NATIVE_PROVIDER 환경 변수는 native_provider보다 우선합니다. 상충하는 속성 할당은 RuntimeWarning를 방출한다.
  • 선택은 연결 문자열 검증 이후, 그리고 네이티브 연결이 구축되기 직전에 고정됩니다. 이후 연결 장애가 발생해도 선택 상태가 해제되지 않습니다. 이전의 연결 문자열 파싱 오류나 제공자 패키지 누락은 선택을 해결하지 않습니다. 선택이 확정된 후에는 native_provider를 다른 제공업체로 변경하면 RuntimeWarning이 발생하며 효과가 없어요. 제공업체를 전환하려면 프로세스를 다시 시작하세요.
  • 인식되지 않은 제공자 이름은 ValueError 예외를 발생시키고, 드라이버는 기본 제공자로 되돌아가지 않습니다. native_provider에 할당된 알 수 없는 이름은 즉시 오류가 발생합니다. 연결 시도 시 환경 변수 내 알 수 없는 이름으로 인해 오류가 발생합니다.
  • 속성 선택이 고정되기 전에 지우려면 None을(를) native_provider(으)로 설정하세요. 환경 변수가 여전히 우선권을 가집니다.

선택된 제공자, 선택 출처, 그리고 선택이 고정되었는지 확인하기 위해 mssql_python.get_native_provider_info()를 호출하세요. 연결 전에 이는 선택 사항만 나타내며, 네이티브 드라이버가 성공적으로 로드되었다는 증거는 아닙니다.

돌아가려면 변수를 msodbcsql18로 설정하거나, 설정을 해제하고 코드에서 native_provider 할당을 제거하거나 "msodbcsql18"로 설정하세요. 그 다음 프로세스를 다시 시작하세요.

현재 효과가 있는 것

mssql-odbc 드라이버는 mssql-python가 호출하는 모든 ODBC 함수를 구현하므로 대부분의 애플리케이션은 코드 변경 없이도 공급자를 전환할 수 있습니다. 나머지 차이점은 알려진 문제에서 확인하세요.

영역 Notes
연결 수명 주기 연결, close(), with 블록, 로그인 타임아웃, 진단, 그리고 현재 데이터베이스 변경. 연결 문자열 설정에는 IpAddressPreference, / , ConnectRetryInterval, ConnectRetryCount, ApplicationIntent, 그리고 KeepAlivePacketSizeMultiSubnetFailover(유휴 연결 복원력)이 포함됩니다.
Authentication SQL 인증(UID / PWD); Windows 인증(Trusted_Connection=Yes Windows에서는 SSPI를 사용하고 Linux 및 macOS에서는 Kerberos를 사용); 그리고 Microsoft Entra 인터랙티브, 디바이스 코드, 서비스 주체, 관리 ID, 기본 자격 증명 및 액세스 토큰. Entra 통합 및 비밀번호 인증은 지원되지 않습니다; 알려진 문제를 참조하세요.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate 및 ServerCertificate.
쿼리 실행 직접 실행과 준비된 실행, 준비된 계획 재사용, qmark 매개변수, 그리고 수행되는 pyformat 변환 mssql-python
ODBC 이스케이프 구문 함수, 날짜/시간, 외부 조인, GUID, LIKE ... {escape ...}, 인터벌, {encrypt ...} 그리고 이스케이프 폼.
저장된 프로시저 T-SQL이나 위치 기반 {call ...} 구문을 execute()을 통해 호출하고, 결과 집합을 읽고, nextset()로 다음 결과 집합으로 이동합니다.
입력 매개 변수 스칼라 파라미터, SQL NULL, setinputsizes(), 그리고 혼합된 일반 및 스트림 파라미터가 있습니다.
큰 매개변수 큰 텍스트와 이진 매개변수는 일반 바인딩 경로를 통해 서버로 전송됩니다; XML 및 UDT 매개변수의 제한 사항은 아래에 나열되어 있습니다.
executemany() ODBC 매개변수 배열로 배치됩니다. 스트림 값이 포함된 행은 행별로 실행됩니다.
행 가져오기 fetchone(), fetchmany(), fetchall(), 반복, fetchval(), 타이핑 변환, 그리고 대용량 텍스트/바이너리 스트리밍이 포함됩니다.
화살표 가져오기 arrow_batch(), arrow()및 arrow_reader(). pyarrow가 필요합니다.
다중 결과 집합 nextset(), 매개변수 배열에 의해 생성된 결과를 포함
Transactions 자동커밋, 커밋, 롤백, with connect(...) 블록이 종료될 때 발생하는 자동 커밋(또는 오류가 처리되지 않은 채 남은 경우 롤백), 그리고 읽기 미커밋, 리드커밋, 반복 가능한 읽기, 직렬화 가능, 스냅샷 격리 레벨.
쿼리 시간 제한 Connection.timeout를 (초 단위로) 해당 연결의 커서가 실행하는 문장의 시간 제한으로 설정합니다. 시간이 만료되면 OperationalError가 발생합니다. 0 즉, 타임아웃이 없다는 뜻입니다. 이 설정은 connect(timeout=...)로 전달되는 로그인 타임아웃과는 별개입니다.
연결 풀링 체크아웃 시 연결 재설정과 Microsoft Entra 아이덴티티별 별도 풀을 포함한 내장 mssql-python 풀
메타데이터 API tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures() 및 getTypeInfo().
인코딩 및 변환기 기본 와이드 문자 인코딩 및 출력 변환기. 맞춤형 좁은 문자 디코딩과 비유니코드 매개변수 변환에는 알려진 문제(Known issues)에 명시된 제한 사항이 있습니다.

데이터 형식

모든 SQL Server 데이터 타입을 읽을 수 있고, 드라이버는 mssql-python이(가) 바인딩하는 모든 파라미터 타입을 지원합니다. 드라이버는 vector, str, vector 값을 hierarchyid(geography는 JSON 배열로)로 반환하고, geometry, xml, bytes와 같은 CLR 형식은 json로 반환합니다. 다른 Python 매핑에 대해서는 데이터 타입 매핑을 참조하세요. 타입별 제한 사항은 알려진 문제를 참조하세요.

알려진 문제

작업 부하를 msodbcsql18에서 전환하기 전에 이러한 차이점을 확인하세요.

Issue Details Workaround
Microsoft Entra 통합 인증 Authentication=ActiveDirectoryIntegrated는 지원되지 않습니다. Windows 인증(Trusted_Connection=Yes)은 영향을 받지 않습니다. 다른 Microsoft Entra 방법을 사용하거나 msodbcsql18를 유지하세요.
Microsoft Entra 암호 인증 Authentication=ActiveDirectoryPassword는 지원되지 않으며, 이 방법이 MFA를 충족하지 못하므로 지원할 계획도 없습니다. SQL 인증(UID / PWD)은 영향을 받지 않습니다. 서비스 주체, 관리 신원, 접근 토큰 등 다른 Microsoft Entra 메서드를 사용하세요.
attrs_before설정 인증, 애플리케이션 의도 및 다중 서브넷 장애 조치(failover)는 숫자 속성으로 설정할 수 없습니다. 쿼리 타임아웃 이외의 문 속성은 거부됩니다. 해당하는 연결 문자열 키워드를 사용하세요.
연결 연산 타임아웃 set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) 값을 받아들이고 저장하지만, 0.3.0에서는 타임아웃을 강제하지 않습니다. 로그인에는 Connection.timeout를 사용하고 명세서에는 connect(timeout=...)를 사용하십시오. 둘 다 일반적인 연결 작업 마감일은 아닙니다.
다중 주소 호스트 msodbcsql18 기본적으로 투명 네트워크 IP 해석(TNIR)을 활성화합니다; mssql-odbc 하지만 이를 지원하지 않습니다. mssql-python는 두 공급자 모두에서 TransparentNetworkIPResolution 연결 문자열 키워드를 거부합니다. MultiSubnetFailover=Yes이 없으면 주소가 한 번에 하나씩 시도되므로, 도달할 수 없는 주소는 연결을 지연시킬 수 있습니다. 서버 지원 DNS 캐싱과 향상된 라우팅은 협상되지 않습니다. 가용성 그룹 리스너 및 기타 다중 주소 호스트에 대해 MultiSubnetFailover=Yes를 설정하세요.
일시적 DNS 실패 DNS 조회가 실패하면 드라이버는 마지막으로 성공한 주소로 폴백하지 않습니다. (#457) 연결을 다시 시도합니다.
데이터 분류 민감도 분류 메타데이터는 제공되지 않으며, SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400)도 지원되지 않습니다. 쿼리 sys.sensitivity_classifications.
다중 스레딩 멀티스레드 사용은 검증되지 않았습니다. msodbcsql18를 멀티스레드 작업 부하에 유지하세요.
fork() 연결 후 리눅스에서는 부모 프로세스가 연결된 후 포크된 프로세스가 드라이버를 사용할 때 새 연결이 있어도 중단될 수 있습니다. 풀링을 활성화하면 부모 서버도 멈출 수 있습니다. (#566) spawn start 메서드를 사용하고 각 워커 내부에서 연결하세요.
실행 중인 문 취소하기 실행 중인 쿼리나 페치는 중단될 수 없습니다. 예를 들어, arrow_reader()를 닫아도 다른 스레드에서 진행 중인 읽기 작업을 멈추지 않습니다. Connection.timeout를 사용하여 장기 실행 문을 제한하세요.
읽지 않은 결과물 커서를 닫거나 다른 문장을 실행하면 취소하는 대신 남은 결과를 읽고 버리므로 느릴 수 있습니다. 준비된 문장을 사용한 커서를 닫으면 Connection.timeout를 무시하고 서버가 응답을 중지하면 멈출 수 있습니다. (#546) 필요한 행만 가져오세요, 예를 TOP들어 .
대형 xml 및 UDT 파라미터 SQL_SS_XML 또는 SQL_SS_UDT부터 setinputsizes()까지로 바인딩된 값은 스트리밍되지 않고 메모리에 버퍼링됩니다. xml 값을 일반 문자열로 바인드하세요.
빈 image 값 빈 비NULL SQL Server image 값은 b"" 대신 None로 반환됩니다. 읽거나 CAST(image_column AS varbinary(max)), 빈 상태/NULL 구분이 중요할 때는 msodbcsql18를 사용하세요.
비유니코드 문자열 매개변수 setinputsizes() varchar char부터 / 까지 바인딩된 문자열은 코드 페이지 437, 코드 페이지 850 및 UTF-8 데이터 정렬에서 잘못 인코딩될 수 있습니다. 기본 문자열 바인딩을 사용하세요.
Windows에서의 레거시 코드 페이지 디코딩 setdecoding(SQL_CHAR, encoding="cp1252") 또는 다른 레거시 코드 페이지를 사용하면 텍스트가 잘못 디코딩되거나 char로 반환될 수 있습니다. 이는 드라이버가 / varcharbytes 데이터를 UTF-8로 반환하기 때문입니다. 기본값을 사용하세요: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME 데이터베이스 사용자가 아닌 connection-string UID을 반환합니다. UID가 운전자에게 도달하지 않으면 비어 있습니다. 일부 능력 값과 패킷 크기 기반 한계는 msodbcsql18와 다릅니다. 데이터베이스 사용자에 SELECT USER_NAME()를 사용하십시오.
메모리 부족 오류 일부 드라이버 할당 실패는 MemoryError를 발생시키는 대신 Python 프로세스를 종료합니다. (#484) 보내고 가져오는 값의 크기를 제한하세요.
큰 값 읽기 성능 한 벤치마크에서는 청크 데이터의 varchar(max) / nvarchar(max) 읽기가 msodbcsql18를 사용할 때보다 약간 느렸습니다. (#473) 업무량을 비교 평가하세요.

이 목록은 완전한 것이 아닙니다.

문제 보고

버그를 발견하면 msodbcsql18을 선택한 후 프로세스를 재시작하고 해당 동작이 여전히 발생하는지 확인하세요. 또한 Python 측에서 상충되는 공급자 할당도 제거하세요. 이 비교는 문제를 특정하는 데 도움이 됩니다; 그것만으로는 원인을 증명하지 못합니다. mssql_python.get_native_provider_info()의 출력, 플랫폼, 그리고 실패한 SQL 또는 오류 메시지를 포함하세요:

Rust-드라이버 진단의 경우, Python을 시작하기 전에 이 변수들을 설정하고 mssql-odbc이 선택된 상태에서 문제를 재현하세요. 예를 들어 PowerShell에서 다음을 수행합니다.

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

MSSQL_TDS_TRACE 추적을 활성화하고, MSSQL_TDS_TRACE_LEVEL 로그 필터를 선택하며, MSSQL_TDS_TRACE_DIR stderr 대신 프로세스별 파일을 작성합니다. 이 설정을 변경한 후 Python을 재시작하세요. 트레이스는 SQL 텍스트와 매개변수 값을 포함할 수 있습니다. 관련 발췌문을 공유하기 전에 민감한 데이터를 검토하고 가리거나 삭제하고, 진단 후에는 추적 기능을 비활성화하세요.

관련 콘텐츠

  • 에 마지막으로 업데이트됨