mssql-django 패키지는 SQL Server, Azure SQL Database, Azure SQL Managed Instance 및 Microsoft Fabric의 SQL 데이터베이스용으로 Microsoft가 공식 지원하는 Django 데이터베이스 백엔드입니다. 이 문서에서는 패키지 및 해당 종속성을 설치하는 방법을 설명합니다.
사전 요구 사항
- Python 3.10부터 3.14까지. Django 6.0 이후 버전은 최소한 Python 3.12가 필요합니다.
- pip 패키지 관리자(Python 3.4 이상 버전 포함)
-
Microsoft ODBC 드라이버 17 또는 18은 기본
pyodbc드라이버를 사용하는 데이터베이스 별칭을 위한 SQL Server용 드라이버입니다. SQL Server ODBC 드라이버 다운로드를 참조하세요.
Important
mssql-django 2.0은 모든 데이터베이스 별칭이 mssql-python를 사용하는 경우에도 pyodbc 1.15.0 이상이 필요합니다. 이 패키지는 호환 mssql-python 가능한 배포판이 있는 플랫폼에만 설치됩니다. 다른 플랫폼의 프로젝트는 버전 1.8.0을 유지합니다. 플랫폼 목록은 mssql-django 지원 및 수명 주기를 참조하세요.
PyPi에서 설치
pip을 사용해 패키지를 설치하세요. 이 명령어는 Django, , mssql-python, 를 설치하고tzdata, pyodbc자동으로 다음과 같은 기능을 수행합니다:
pip install mssql-django
기존 설치를 업그레이드하려면 다음을 수행합니다.
pip install --upgrade mssql-django
특정 버전을 설치하려면
pip install mssql-django==2.0.0
종속성 및 버전 호환성
2.0의 경우 mssql-django 패키지 메타데이터에는 다음과 같은 의존성 제약 조건이 포함됩니다:
| Component | 버전 지침 |
|---|---|
| Python | 3.10부터 3.14까지 |
| Django |
>=5.2 및 <6.2 |
pyodbc |
>=3.0 |
mssql-python |
>=1.15.0 |
tzdata |
종속성으로 설치됨 |
Tip
검증된 잠금 파일이 없는 한 pip에서 호환되는 버전을 결정하도록 하세요. 이전 pyodbc 버전을 고정하면 설치에 성공하더라도 런타임 문제가 발생할 수 있습니다.
데이터베이스 드라이버 선택
pyodbc 기본 드라이버이며 설정이 필요 없습니다. 대신 mssql-python에서 데이터베이스 별칭을 실행하려면 해당 별칭의 "python_driver": "mssql_python" 사전에 OPTIONS을 추가하세요. 별칭은 같은 프로젝트 내에서 서로 다른 드라이버를 사용할 수 있습니다. 동작 차이와 각 드라이버가 무시하는 옵션에 대해서는 mssql-django의 데이터베이스 드라이버 선택(Select the database driver)을 참조하세요.
설치 확인
설치 후 패키지가 올바르게 설치되었는지 확인합니다.
pip show mssql-django
예상 출력:
Name: mssql-django
Version: 2.0.0
Summary: Django backend for Microsoft SQL Server
기본 pyodbc 경로가 사용하는 ODBC 계층을 확인하세요:
import pyodbc
print(f"pyodbc version: {pyodbc.version}")
print(f"Available ODBC drivers: {pyodbc.drivers()}")
메모
mssql-django 백 엔드는 Django의 데이터베이스 라우팅 시스템에서 자동으로 구성됩니다. 애플리케이션 코드에서 직접 가져오지 마세요. 대신 ENGINE 구성에서 mssql를 DATABASES로 설정합니다.
가상 환경 사용
Python 가상 환경을 사용하여 프로젝트 종속성을 격리합니다.
python -m venv .venv
가상 환경을 활성화합니다.
.venv\Scripts\activate
그런 다음 가상 환경 안에 mssql-django를 설치합니다.
pip install mssql-django
플랫폼별 참고 사항
기본 pyodbc 드라이버를 사용하는 데이터베이스 별칭은 별도로 설치된 ODBC 드라이버가 필요하며, 설치 단계는 운영체제에 따라 다릅니다. 별칭이 있는 mssql-python 경우에는 이런 단계가 필요하지 않습니다. 대신, macOS의 OpenSSL과 Linux의 필수 라이브러리를 포함한 mssql-python 플랫폼 필수 조건을 설치하세요.
Windows
.msi에서 설치 관리자를 사용하여 Microsoft ODBC Driver 18 for SQL Server를 설치합니다.
리눅스
배포판의 패키지 관리자를 사용하여 ODBC 드라이버를 설치합니다. 플랫폼별 지침은 Microsoft ODBC driver for SQL Server(Linux) 설치를 참조하세요.
macOS
Homebrew를 사용하여 ODBC 드라이버를 설치합니다.
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18
종속성
패키지는 mssql-django 다음 종속성을 자동으로 설치합니다.
| Package | Purpose |
|---|---|
Django |
웹 프레임워크 |
pyodbc |
Python용 기본 ODBC 데이터베이스 드라이버 |
mssql-python |
무조건 설치된 옵트인 Python 데이터베이스 드라이버 |
tzdata |
표준 도서관 zoneinfo 모듈용 IANA 시간대 데이터베이스 |
백엔드는 표준 라이브러리 datetime 모듈을 사용해 시간대 정보가 포함된 zoneinfo 값을 변환합니다.
zoneinfo는 운영 체제의 IANA 시간대 데이터베이스가 있으면 이를 읽고, 그렇지 않으면 대신 tzdata 패키지를 사용하는데, 이 패키지는 Windows와 최소 컨테이너 이미지를 지원합니다.
pytz 더 이상 의존성이 아닙니다.