이 문서에서는 Django OPTIONS 구성에서 DATABASES 사전 설정을 설명합니다. 이러한 설정은 ODBC 드라이버를 통해 SQL Server 연결하는 방법을 mssql-django 제어합니다.
ODBC 드라이버 선택
mssql-django 1.7을 기준으로 백 엔드는 기본적으로 SQL Server ODBC Driver 18로 설정됩니다. ODBC Driver 18이 설치되지 않은 경우 백 엔드는 자동으로 ODBC Driver 17로 돌아갑니다.
메모
ODBC 드라이버 18은 Encrypt=yes 기본적으로 사용하도록 설정하고 서버 인증서의 유효성을 검사합니다. 드라이버 17에서 작동하는 연결은 SSL/TLS 신뢰 오류로 실패할 수 있습니다. 오류를 해결하려면 다음을 수행합니다.
- 온-프레미스 SQL Server 경우 클라이언트가 이미 신뢰하는 인증 기관에서 서버 인증서를 설치하거나 기존 서버 인증서를 각 클라이언트 신뢰 저장소로 가져옵니다. 자세한 내용은 연결 암호화를 위한 SQL Server 데이터베이스 엔진 구성을 참조하세요.
- IP 주소나 인증서의 주체 이름 또는 주체 대체 이름(SAN)과 일치하지 않는 별칭을 사용해 연결하는 경우
HostNameInCertificate=<name-from-certificate>를extra_params에 추가하세요.
드라이버를 명시적으로 지정할 수 있습니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 17 for SQL Server",
},
},
}
Linux에서 드라이버 라이브러리의 전체 경로를 지정할 수도 있습니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
},
},
}
DSN 대 HOST
HOST 이름 또는 이름이 지정된 DSN(데이터 원본 이름)을 사용하여 연결할 수 있습니다.
HOST로 연결
대부분의 구성은 이 HOST 설정을 직접 사용합니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
},
}
DSN으로 연결
ODBC 데이터 원본에 구성된 명명된 DSN을 사용합니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"OPTIONS": {
"dsn": "MyDataSourceName",
},
},
}
FreeTDS 지원
FreeTDS를 ODBC 드라이버로 사용하려면 host_is_server를 True로 설정합니다. 이렇게 하면 백엔드가 HOST에서 데이터 서버 이름을 조회하는 대신 PORT 및 freetds.conf을 직접 사용하도록 지시합니다:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "FreeTDS",
"host_is_server": True,
},
},
}
FreeTDS를 사용한 DSN이 없는 연결에 대한 자세한 내용은 FreeTDS 사용자 가이드를 참조하세요.
추가 ODBC 매개 변수
추가 ODBC 연결 문자열 매개 변수를 전달하는 데 사용합니다extra_params. 값은 연결 문자열에 추가되는 세미콜론으로 구분된 문자열입니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
"extra_params": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
},
},
}
이 설정은 Microsoft Entra 인증 키워드에도 사용됩니다.
Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric의 SQL 데이터베이스, 가용성 그룹 리스너, 또는 장애 조치 클러스터 인스턴스에 연결할 때, MultiSubnetFailover=Yesextra_params. 드라이버는 모든 해결된 엔드포인트에 병렬로 연결을 시도하고, 첫 번째 응답형 엔드포인트와 인증을 완료합니다. 단일 IP 대상에서는 안전합니다: DNS가 한 주소로 해석되면 드라이버가 단일 연결 시도를 하면서 측정 가능한 오버헤드 없이 진행되므로, Microsoft SQL 패밀리 엔드포인트를 대상으로 하는 모든 Django 배포에서 이 설정을 켜둔 상태로 유지할 수 있습니다.
Caution
자체 서명된 인증서를 사용하여 로컬 개발에만 사용합니다 TrustServerCertificate=yes . 프로덕션 환경에서는 사용하지 마세요. 인증서 체인 유효성 검사를 비활성화하여 중간자 공격 위험을 증가시킵니다. 서버에 신뢰할 수 있는 인증서를 설치하고 TrustServerCertificate=no로 연결합니다.
연결 시간 제한 및 다시 시도
시간 제한 및 다시 시도 설정을 사용하여 연결 복원력을 구성합니다.
| Option | 기본값 | Description |
|---|---|---|
connection_timeout |
0 (사용 안 함) |
연결을 기다리는 최대 시간(초)입니다. |
connection_retries |
5 |
연결 실패 시 다시 시도 횟수입니다. |
connection_retry_backoff_time |
5 |
다시 시도 사이에 대기하는 시간(초)입니다. |
query_timeout |
0 (사용 안 함) |
쿼리가 완료되기를 기다리는 최대 시간(초)입니다. |
예제:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
"connection_timeout": 30,
"connection_retries": 3,
"connection_retry_backoff_time": 10,
"query_timeout": 120,
},
},
}
connection_timeout=0 MSSQL-Django 기본값입니다. pyodbc는 양수 값을 제공할 때만 호출 SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) 하기 때문에 드라이버 의존 기본값이 적용됩니다(Microsoft ODBC 드라이버 for SQL Server는 15초 소요). 명시적인 값을 설정해 반응하지 않는 연결 시도가 예측 가능하게 실패하도록 하세요.
만약 대상이 자동 일시정지가 활성화된 Azure SQL Database serverless라면, 최소한 60.을 사용하세요. 자동 일시정지된 데이터베이스는 첫 연결 시 재개되며, 재개는 30초에서 60초 이상 걸릴 수 있습니다. 타임아웃이 짧아지면 첫 연결 시도가 재개 완료 전에 타임아웃됩니다.
connection_retries 결국 복구되지만, 첫 번째 요청은 성공하기 전에 여러 번의 타임아웃 간격을 지불합니다.
Collation
텍스트 필드 조회에 대한 사용자 지정 데이터 정렬을 설정합니다.
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
"collation": "Chinese_PRC_CI_AS",
},
},
}
여러 데이터베이스 연결
Django는 여러 데이터베이스에 동시에 연결할 수 있도록 지원합니다. 이는 읽기 복제본, 데이터베이스 간 쿼리 또는 격리 수준으로 워크로드를 분리하는 데 유용합니다.
여러 데이터베이스 구성
설정에서 각 연결을 정의합니다.DATABASES
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "app_db",
"HOST": "<your-primary-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
},
"readonly": {
"ENGINE": "mssql",
"NAME": "app_db",
"HOST": "<your-readonly-replica>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
"extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
},
},
"analytics": {
"ENGINE": "mssql",
"NAME": "analytics_db",
"HOST": "<your-analytics-server>",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
"isolation_level": "READ UNCOMMITTED",
},
},
}
Caution
READ UNCOMMITTED는 더티 리드를 허용합니다. 절대 정확도가 필요하지 않은 보고 또는 분석 쿼리에만 이 격리 수준을 사용합니다. 자세한 내용은 트랜잭션 관리를 참조하세요.
데이터베이스 라우터를 사용하여 쿼리 라우팅
읽기 및 쓰기 작업을 적절한 연결로 직접 지정하는 데이터베이스 라우터를 만듭니다.
class ReadReplicaRouter:
"""Route read queries to the readonly replica, writes to the primary."""
def db_for_read(self, model, **hints):
return "readonly"
def db_for_write(self, model, **hints):
return "default"
def allow_relation(self, obj1, obj2, **hints):
return True
def allow_migrate(self, db, app_label, model_name=None, **hints):
return db == "default"
settings.py에서 라우터를 등록합니다:
DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]
라우터 클래스를 파일(예: myproject/routers.py.)에 저장합니다.
특정 데이터베이스를 직접 쿼리
메서드를 using() 사용하여 특정 데이터베이스 별칭을 쿼리합니다.
# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")
# Write to default
Product.objects.create(name="Widget", price=9.99)
연결당 데이터베이스의 격리 수준에 대한 자세한 내용은 차단 없이 데이터 읽기를 참조하세요.