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

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

Provider Description 상태
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc 러스트 기반 ODBC 드라이버 미리보기, 옵트인

mssql-python-rs 패키지에는 mssql-odbc 제공자가 포함됩니다.

Note

msodbcsql18를 프로덕션 워크로드에 사용하세요. 미리보기 mssql-odbc 제공업체에 등록하기 전에 알려진 문제점을 검토하세요.

Availability

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

Platform Architectures
Windows x64; CPython 3.11 및 이후 버전에서의 ARM64
macOS Universal 2 (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-odbc도 설치되며, 여기에는 mssql-python-rs 드라이버가 포함됩니다:

python -m pip install mssql-python

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

첫 연결을 열기 전에 공급자를 선택하세요. 다음 방법 중 하나를 사용합니다.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

MSSQL_CONNECTION_STRING 환경 변수를 애플리케이션의 연결 문자열로 설정하세요. 인증서 검증은 활성화 상태로 유지하세요 (Encrypt=yes;TrustServerCertificate=no). 자세한 내용은 연결 문자열과 암호화 및 인증서를 참조하세요.

선택한 제공업체로 이 예시를 실행해 보세요:

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])

예시는 1를 출력합니다.

제공자 선정은 다음과 같은 규칙을 따릅니다:

  • MSSQL_PYTHON_NATIVE_PROVIDER가 native_provider보다 우선합니다. 속성을 충돌하는 공급자로 설정하면 RuntimeWarning가 발생합니다.
  • 드라이버가 로드되기 전에 None를 native_provider로 설정하여 Python 설정을 지우세요. 이것만으로도 환경 변수가 사라지지 않습니다.
  • 인식되지 않은 제공자 이름이 ValueError 예외를 발생시킵니다. 잘못된 이름native_provider을 할당하면 즉시 오류가 발생하며, 잘못된 환경 변수는 연결 시 오류가 발생합니다. 드라이버는 기본 공급자로 되돌아가지 않습니다.
  • 드라이버가 네이티브 연결 시도를 시작하면 제공자가 고정되며, 그 시도가 실패하더라도 말입니다. Python을 재시작해서 공급자를 바꾸세요. native_provider을 다른 제공업체로 변경하면 RuntimeWarning이 발생하며 효과가 없습니다.

연결 문자열 검증 오류와 누락된 제공자 패키지는 이 지점에 도달하기 전에 발생합니다. 이 오류를 수정하고 재시작 없이 다른 제공업체를 선택할 수 있습니다.

mssql_python.get_native_provider_info() 호출하여 제공업체 이름, 선택 방식, 그리고 해당 선택이 고정되었는지 확인하세요.

msodbcsql18(으)로 돌아가려면 애플리케이션에서 native_provider 및 모든 MSSQL_PYTHON_NATIVE_PROVIDER 할당을 제거한 다음 Python을 다시 시작하세요.

다중 서브넷 장애 조치 기본값

러스트 제공자는 해당 전송 제어 프로토콜(TCP) 연결에 대해 기본적으로 MultiSubnetFailover를 활성화합니다. MultiSubnetFailover=no를 명시적으로 설정하여 순차적 연결 시도를 요청하세요. 배포 전체 기본값을 변경하려면 네이티브 드라이버가 처음 사용되기 전에 MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT를 true 또는 false로 설정하세요. connection-string 키워드는 이 기본값을 덮어씁니다.

숫자 SQL_COPT_SS_MULTISUBNET_FAILOVER 속성(1248)은 연결 전에 설정하면 키워드를 덮어씁니다.

드라이버는 비-TCP 전송, 데이터베이스 미러링, SQL Server 브라우저 탐색이 필요한 이름 있는 인스턴스, 명시적인 프로토콜과 주소가 없는 로컬 Windows 연결에는 이 기본값을 활성화하지 않습니다. 비-TCP 전송, 데이터베이스 미러링 또는 SQL Server Browser 검색에 대해 MultiSubnetFailover를 명시적으로 활성화하면 연결 오류가 발생합니다. 자세한 내용은 고가용성(High Availability)과 장애 조치(failover)를 참조하세요.

지원되는 기능

다음 기능들은 알려진 문제가 있지만 지원됩니다.

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

Microsoft Entra ID 통합 인증은 Windows에서 로그인된 Windows 계정을 사용합니다. Linux와 macOS에서는 Kerberos 티켓을 사용해 테넌트의 Active Directory Federation Services(AD FS) 엔드포인트에 인증하는 데 사용합니다. 전제 조건은 Windows 통합 인증을 참조하세요.

arrow_reader()을 닫으면 SQLCancel을 보내 진행 중인 페치를 중단합니다. close 호출은 취소 정리가 끝나기를 기다립니다. 자세한 내용은 Apache Arrow 통합을 참조하세요.

데이터 형식

드라이버는 xml, json, 벡터 값을 Python str 객체로 반환하며, 벡터는 JavaScript 객체 표기법(JSON) 배열로 표현됩니다. geometry, geography, hierarchyid와 같은 공통 언어 런타임(CLR) 형식을 Python bytes 객체로 반환합니다. 자세한 내용은 데이터 타입 매핑 및 알려진 문제를 참조하세요.

알려진 문제

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

Issue Details Workaround
Microsoft Entra ID 비밀번호 인증 Authentication=ActiveDirectoryPassword는 지원되지 않습니다. 이 방법은 다단계 인증(MFA)을 충족하지 못합니다. SQL 인증(UID / PWD)은 영향을 받지 않습니다. 서비스 프린시펄, 관리 신원, 액세스 토큰 등 다른 Microsoft Entra ID 방법을 사용하세요.
attrs_before설정 Microsoft Entra ID 인증 모드와 애플리케이션 의도는 숫자 연결 속성으로 설정할 수 없습니다. ApplicationIntent 및 Authentication 연결 문자열 키워드를 사용하세요.
연결 연산 타임아웃 SQL_ATTR_CONNECTION_TIMEOUT는 취소 정리를 제어합니다. 풀 연결 리셋 시 타임아웃을 강제하지 않습니다. 리셋 중에 서버가 응답을 멈추면 연결 요청이 차단된 상태로 유지될 수 있습니다. pooled-reset 타임아웃을 사용할 수 없습니다. 로그인에는 Connection.timeout을, 명세서에는 connect(timeout=...)을 설정하세요.
다중 주소 호스트 msodbcsql18 기본적으로 투명 네트워크 IP 해석(TNIR)을 활성화합니다; mssql-odbc 하지만 이를 지원하지 않습니다. mssql-python는 두 공급자 모두에서 TransparentNetworkIPResolution 연결 문자열 키워드를 거부합니다. MultiSubnetFailover=yes는 가용성 그룹 리스너 및 기타 다중 주소 호스트에 사용됩니다. 기본값에 대해서는 멀티서브넷 장애 전환 기본값을 참조하세요.
데이터 분류 민감도 분류 메타데이터는 제공되지 않으며, SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400)도 지원되지 않습니다. 쿼리 sys.sensitivity_classifications.
fork() 연결 후 리눅스에서는 부모 프로세스가 연결된 후 포크된 프로세스가 드라이버를 사용할 때 새 연결이 있어도 중단될 수 있습니다. 풀링을 활성화하면 부모 서버도 멈출 수 있습니다. (#566) spawn start 메서드를 사용하고 각 워커 내부에서 연결하세요.
리눅스에서의 네이티브 트레이싱 네이티브 트레이싱이 활성화되면 Python은 프로세스 종료 시 드라이버 정리 중에 중단할 수 있습니다. 리눅스에서는 MSSQL_TDS_TRACE을 설정하지 않은 상태로 두세요.
읽지 않은 결과물 커서를 닫거나 다른 문장을 실행하면 취소하는 대신 남은 결과를 읽고 버리므로 느릴 수 있습니다. 준비된 구문 정리는 구문의 쿼리 타임아웃을 사용하지만, 0 타임아웃은 해당 정리 작업이 무제한으로 남습니다. 필요한 행만 가져오세요. 예를 들어 TOP을 사용하고, 커서를 생성하기 전에 Connection.timeout을 설정하세요.
맞춤형 싱글바이트 문자 디코딩 네이티브 드라이버는 좁은 텍스트에 대해 Windows에서는 Windows ANSI 코드 페이지를 사용하고 Linux와 macOS에서는 프로세스 로캘의 코드 페이지를 사용합니다. 명시적인 Python 디코딩이 해당 코드 페이지와 일치하지 않으면 잘못된 텍스트 또는 bytes를 생성할 수 있습니다. 기본 와이드 문자 디코딩을 사용하세요: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() 일부 능력 값과 패킷 크기 기반 한계는 msodbcsql18와 다릅니다. SQL_USER_NAME 연결 문자열 UID가 아닌 데이터베이스 주체를 보고합니다. 보고된 기능이나 제한이 애플리케이션에 중요할 때는 특정 서버 메타데이터를 조회하세요.
메모리 부족 오류 일부 드라이버 할당 실패는 MemoryError를 발생시키는 대신 Python 프로세스를 종료합니다. (#484) 보내고 가져오는 값의 크기를 제한하세요.
큰 값 읽기 성능 varchar(max) 및 nvarchar(max) 데이터의 청크 읽기는 msodbcsql18를 사용하는 경우보다 느릴 수 있습니다. (#473) 업무량을 비교 평가하세요.

문제 신고

버그가 발생하면 msodbcsql18로 재현하고 두 제공업체 모두에서 발생하는지 기록하세요. 전환 방법은 드라이버 활성화를 참조하세요.

mssql_python.get_native_provider_info()의 출력, 운영체제, Python 및 드라이버 버전, 그리고 실패한 T-SQL 배치 및 오류 메시지를 보고서에 포함하세요:

Windows에서는 Python을 시작하기 전에 PowerShell에서 이 변수들을 설정해 네이티브 드라이버 진단을 수집하세요. mssql-odbc을 선택한 상태에서 문제를 재현합니다:

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

MSSQL_TDS_TRACE 트레이싱을 활성화하고, MSSQL_TDS_TRACE_LEVEL 로그 레벨을 선택하며, MSSQL_TDS_TRACE_DIR 표준 오류 출력 대신 네이티브 ODBC 드라이버의 프로세스별 추적 파일용 디렉터리를 선택합니다. Rust 동반 패키지는 현재 디렉터리 아래의 mssql_python_logs에 로그 파일도 생성합니다.

트레이스는 T-SQL 텍스트와 매개변수 값을 포함할 수 있습니다. 발췌문을 공유하기 전에 민감한 데이터를 삭제하세요. 진단 후에는 이 변수들을 제거하고 Python을 재시작하여 추적을 비활성화하세요.

관련 콘텐츠

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