이 문서에서는 Django DATABASES 구성에서 OPTIONS 사전 설정을 설명합니다. 이러한 설정은 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 vs 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로 설정합니다. 이렇게 하면 백엔드가 freetds.conf에서 데이터 서버 이름을 조회하는 대신 HOST 및 PORT을 직접 사용하도록 지시합니다:
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 인증 키워드에도 사용됩니다.
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,
},
},
}
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)
연결당 데이터베이스의 격리 수준에 대한 자세한 내용은 차단 없이 데이터 읽기를 참조하세요.