버전 2.0부터는 mssql-django 두 가지 Python 데이터베이스 드라이버 중 하나를 통해 연결됩니다:
- pyodbc와 함께 사용하는 별도로 설치된 SQL Server용 Microsoft ODBC 드라이버. 이 드라이버가 기본값입니다.
- mssql-python, Microsoft의 Python 드라이버로, 별도로 설치된 ODBC 드라이버가 필요하지 않습니다.
각 데이터베이스 별칭에 대해 드라이버를 선택합니다. 하나의 별칭을 사용할 mssql-python 수 있고, 나머지 프로젝트는 계속 사용할 pyodbc수 있습니다.
"mssql" 값은 두 경우 모두 ENGINE 유지됩니다.
mssql-python에 별칭을 선택하세요
해당 별칭의 OPTIONS 딕셔너리에서 python_driver 옵션을 설정하세요:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<database>",
"USER": "<user_id>",
"PASSWORD": "<password>",
"HOST": "<server>.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"python_driver": "mssql_python",
"extra_params": "Encrypt=yes",
},
},
}
백엔드는 "mssql-python", "python", "mssql_python"를 허용하며, 비교 시 대소문자를 구분하지 않습니다.
python_driver를 생략하거나, 비워 두거나, 기본 드라이버를 유지하려면 "pyodbc"로 설정하세요. 설정이 별칭 단위이기 때문에, 옵션을 제거하면 데이터베이스 하나씩 롤백할 수 있습니다.
mssql-python 모듈은 별칭이 이를 선택할 때만 임포트됩니다. 설치된 버전이 1.15.0보다 이전이면 백엔드는 필요한 버전이 포함된 ImproperlyConfigured를 발생시킵니다.
설치 요구 사항
pip install mssql-django 두 드라이버 모두 설치합니다. 경로에는 mssql-python 별도의 ODBC 드라이버 설치가 없습니다.
mssql-python 설치 또는 --no-deps를 미러링하지 않는 개인 인덱스에서는 패키지가 누락되어 임포트 시 별칭이 실패합니다.
macOS에서는 OpenSSL, Linux에는 필수 라이브러리를 포함해 mssql-python 플랫폼 필수 조건을 설치하세요.
필수 의존성 mssql-django 때문에 mssql-python 2.0은 호환 mssql-python 가능한 배포판이 있는 플랫폼에만 설치됩니다. 플랫폼 목록은 mssql-django 지원 및 수명 주기를 참조하세요.
동작 차이점
두 드라이버는 서로 다른 연결 문자열을 생성하고 서로 다른 연결 키워드를 노출합니다. 가명을 바꾸기 전에 이 섹션을 꼭 확인하세요.
연결 설정
| Setting | pyodbc | mssql-python |
|---|---|---|
HOST 및 PORT |
host_is_server, SERVERNAME 또는 SERVER 및 PORT로 방출되며, 이는 드라이버와 SERVER에 따라 달라집니다. |
항상 SERVER=<host>,<port>로 출력됩니다. 빈 HOST는 localhost가 됩니다. |
driver |
ODBC 드라이버를 선택합니다. 기본적으로 Microsoft ODBC Driver 18 for SQL Server를 사용하며, 자동으로 드라이버 17로 대체됩니다. | 무시됩니다. 드라이버 17의 백업 옵션은 없습니다. |
dsn |
지원됨 | 무시됩니다. |
host_is_server |
FreeTDS에서 지원됨. | 무시됩니다. |
unicode_results |
지원됨 | 무시됩니다. |
TOKEN |
지원됨 | 지원됨
PASSWORD, USER 또는 TOKEN 키워드 없이 Authentication 제공하세요. 애플리케이션이 토큰을 획득하고 갱신합니다. |
DATABASE_CONNECTION_POOLING |
적용됩니다. | 적용됩니다. |
타임아웃, 리트리, 격리 레벨, 콜레이션, return_rows_bulk_insert 그리고 두 경로 모두에서 동일하게 동작합니다.
추가 연결 매개변수
mssql-python 1.15는 허용 목록에 대해 검증하고 extra_params 그 외의 것은 거부합니다. 지원되는 키워드에는 Encrypt, TrustServerCertificate, ServerCertificate, ServerSPN, HostnameInCertificate, MultiSubnetFailover, KeepAlive, IpAddressPreference, ApplicationIntent, ConnectRetryCount, ConnectRetryInterval, KeepAliveInterval, PacketSize, 및 Authentication가 포함됩니다.
드라이버는 Network Library, WSID, QuotedId, Description뿐만 아니라 Connect Timeout, Current Language, ColumnEncryption, Regional, LongAsMax, AnsiNPW, UseFMTONLY, APP, DRIVER, MARS_Connection, SERVERNAME, DSN와 같은 pyodbc 전용 키워드도 거부합니다. 별칭을 바꾸기 전에 그 키워드를 제거하고, connection_timeout 대신 Connect Timeout 옵션을 사용하세요.
백엔드가 생성하는 키워드를 설정하면 extra_params 명시적 값이 승리합니다.
다중 활성 결과 세트 (MARS)
pyodbc 경로에서는 별칭이 Windows에서 Microsoft ODBC 드라이버를 사용할 때 백엔드가 MARS_Connection=yes를 추가합니다.
extra_params에 명시적으로 지정된 MARS_Connection 값이 대신 우선 적용되며, 일치는 대/소문자를 구분하지 않습니다.
mssql-python 경로에서는 MARS가 절대 활성화되지 않으며 MARS_Connection 키워드도 허용하지 않으므로, 해당 별칭에서는 MARS를 켤 수 없습니다.
MARS QuerySet.iterator() 가 없으면 행을 생성하기 전에 전체 결과를 메모리에 읽어 중첩 쿼리가 연결을 재사용할 수 있게 하며, chunk_size 이 점은 변경되지 않습니다. 대규모 쿼리셋의 메모리 비용을 고려하세요.
Microsoft Fabric Warehouse와 같이 MARS를 거부하는 엔드포인트에 대해서는 MARS 비활성화를 참조하세요.
인코딩 구성
두 드라이버 모두 setdecoding 및 setencoding를 허용하며, 각 항목은 선택한 드라이버의 연결 방법으로 전달됩니다. 모든 setdecoding 항목에는 두 경로에 모두 sqltype 키가 필요하며, 동일한 항목은 어느 드라이버에서든 작동합니다. 한 가지 차이점: mssql-python 는 -99 에 대해 SQL_WMETADATA받아들이고 pyodbc 거부합니다.
드라이버 중 하나를 선택하세요
새로 개발하는 경우 mssql-python를 사용하세요. 컨테이너 이미지와 앱 서비스 배포에서 ODBC 드라이버 설치 단계를 제거합니다.
배포가 명명된 DSN, FreeTDS, pyodbc 키워드를 통한 Always Encrypted, 직접 관리하는 ODBC 드라이버 버전 또는 MARS에 종속되는 경우 ColumnEncryption를 사용하세요. 각 경로에서 MARS가 요구하는 내용은 다중 활성 결과 세트를 참조하세요.
기존 프로젝트는 계속 유지 pyodbc할 수 있습니다. 기본 사양으로 남아 있으며 완전히 지원되고 있습니다. 이동할 때는 한 번에 한 가지 별칭을 바꾸고, 테스트 스위트를 그 별칭에 대해 실행한 후 나머지를 옮기세요.