mssql-django 문제 해결

SQL Server, Azure SQL Database, Azure SQL Managed Instance 및 Microsoft Fabric의 SQL 데이터베이스용 mssql-django 백엔드의 일반적인 문제를 진단하고 해결합니다.

연결 문제

이 섹션에서는 가장 일반적인 연결 오류 및 해결 방법을 설명합니다.

ODBC 드라이버를 찾을 수 없음

증상:

django.core.exceptions.ImproperlyConfigured: 'ODBC Driver 18 for SQL Server' is not a recognized ODBC driver

또는:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

가능한 원인 및 솔루션:

  • ODBC 드라이버가 설치되지 않음

    Microsoft ODBC Driver for SQL Server 설치합니다. 다운로드 링크는 SQL Server 대한 ODBC 드라이버 다운로드를 참조하세요.

  • 설치된 여러 드라이버 버전

    에서 정확한 드라이버 이름 또는 경로를 지정합니다.settings.py

    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에서 전체 경로를 지정합니다.

    "OPTIONS": {
    "driver": "/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1",
},

  • 설치된 드라이버 확인

    • Linux/macOS에서는 odbcinst -q -d를 실행합니다.
    • Windows 관리 도구에서 ODBC 데이터 원본을 확인합니다.

연결이 거부되었습니다.

증상:

django.db.utils.OperationalError: ('08001', '[08001] ... TCP Provider: Error code 0x2749 ...')

가능한 원인 및 솔루션:

  • SQL Server TCP/IP가 사용하도록 설정되지 않음

    • SQL Server 구성 관리자를 엽니다.
    • SQL Server 네트워크 구성에서 TCP/IP를 사용하도록 설정합니다.
    • TCP/IP 속성에서 연결에 사용되는 IP 주소를 활성화합니다.
    • SQL Server 서비스를 다시 시작합니다.

  • 방화벽 차단 포트 1433

    • 방화벽 규칙이 포트 1433에서 인바운드 연결을 허용하는지 확인합니다.
    • Azure SQL 경우 Azure 포털 방화벽 설정에 클라이언트 IP를 추가합니다.

  • 잘못된 서버 이름 또는 포트

    구성의 HOST 값과 PORT 값을 확인합니다.

로그인 실패

증상:

django.db.utils.OperationalError: ('28000', "[28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<username>'.")

가능한 원인 및 솔루션:

  • 잘못된 자격 증명

    사용자 이름 및 암호를 확인합니다.

  • 사용자가 존재하지 않음

    로그인이 대상 데이터베이스의 사용자에 매핑되어 있는지 확인합니다.

  • SQL Server 인증 사용 안 함

    혼합 모드 인증을 사용하거나 Windows 또는 Microsoft Entra 인증을 사용합니다.

연결 시간 초과

증상:

django.db.utils.OperationalError: ('HYT00', '[HYT00] [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired')

가능한 원인 및 솔루션:

  • 네트워크 대기 시간

    옵션에서 connection_timeout을 늘리십시오.

  • 서버 오버로드됨

    connection_retries 및 connection_retry_backoff_time을 늘리십시오.

    "OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_timeout": 30,
    "connection_retries": 5,
    "connection_retry_backoff_time": 10,
},

마이그레이션 문제

이러한 오류는 SQL Server 대한 Django 마이그레이션 작업 중에 발생합니다.

날짜 및 시간 문제

Now() 값은 다음과 같은 경우 이동됩니다. USE_TZ=True

증상:

Django Now(), auto_now, 또는 auto_now_add로 작성된 타임스탬프는 SQL Server 호스트 시간대가 UTC가 아닐 경우 이동됩니다.

해결 방법: 1.7.2 이상으로 업그레이드 mssql-django 합니다. 버전 1.7.2는 시간대 인식 Now() SQL 생성 및 datetimeoffset 오프셋 처리 문제를 해결합니다.

AttributeError .explain() 호출할 때

증상:

AttributeError: ... explain_format ...

해결 방법: 1.7.2 이상으로 업그레이드 mssql-django 합니다. 버전 1.7.2는 Django 4.0 이상에서의 explain 메타데이터에 대한 컴파일러 호환성 문제를 수정합니다.

AutoField를 변경할 수 없음

증상:

django.db.utils.ProgrammingError: Cannot alter column to or from an IDENTITY column

해결 방법: SQL Server는 필드를 AutoField에서 또는 AutoField로 변경하는 것을 지원하지 않습니다. 원하는 필드 형식으로 새 모델을 만들고 데이터를 수동으로 마이그레이션한 다음 이전 테이블을 삭제합니다. 해결 방법은 mssql-django를 사용한 데이터베이스 마이그레이션을 참조하세요.

외래 키 제약 조건으로 이름 바꾸기 실패

증상:

django.db.utils.ProgrammingError: ... could not drop constraint ...

해결 방법: SQL Server 열 이름을 바꾸기 전에 외래 키 제약 조건을 삭제해야 합니다. 마이그레이션에 SeparateDatabaseAndState를 사용합니다. 예를 들어 mssql-django를 사용한 데이터베이스 마이그레이션을 참조하세요.

인코딩 문제

인코딩 오류는 일반적으로 SQL Server 문자 데이터를 잘못 해석할 때 pyodbc 발생합니다.

유니코드 인코딩 오류

증상:

UnicodeDecodeError: 'utf-8' codec can't decode byte ...

해결 방법: OPTIONS 사전에서 pyodbc 인코딩을 구성합니다.

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "unicode_results": True,
},

FreeTDS 문제

FreeTDS에는 Microsoft ODBC 드라이버와 다른 특정 구성이 필요합니다.

host_is_server 오류

증상:

를 지정하지 않고 FreeTDS를 사용할 때 연결이 실패합니다 host_is_server.

해결 방법: FreeTDS를 사용하는 경우 host_is_server을(를) True(으)로 설정합니다.

"OPTIONS": {
    "driver": "FreeTDS",
    "host_is_server": True,
},

FreeTDS 구성에 대한 자세한 내용은 mssql-django에 대한 연결 옵션을 참조하세요.

데이터베이스 문제 테스트

인증 방법에 따라 데이터베이스 생성 및 소멸 테스트가 실패할 수 있습니다.

관리 ID를 사용하여 테스트 데이터베이스를 만들 수 없습니다.

증상:

django.db.utils.DatabaseError: ('42000', '[42000] ... EXECUTE permission denied on object ...')

또는:

django.db.utils.OperationalError: ('28000', ... login failed ...)

테스트 실행기는 ActiveDirectoryMsi (관리형 ID) 인증을 사용할 때 테스트 데이터베이스를 생성하거나 삭제하지 못합니다. 이 제한 사항은 다음과 같은 이유로 존재합니다.

  • 관리 ID 자격 증명은 호스트 환경(예: Azure VM 및 App Service)에서 가져옵니다.

  • 테스트 실행기는 테어다운 중에 test 데이터베이스 자격 증명을 사용해 연결을 시도합니다.

  • 관리 ID는 데이터베이스 수준 역할을 부여할 수 있지만, 테스트 데이터베이스 만들기 및 삭제에는 일반적으로 테스트 실행기에서 없는 서버 수준 권한이 필요합니다.

영향을 받는 인증 방법:

  • ActiveDirectoryMsi (Azure 관리 ID)
  • ActiveDirectoryServicePrincipal (서버 범위에서만 구성된 경우)

지원되는 인증 방법 (테스트 데이터베이스 만들기 작동):

  • ActiveDirectoryPassword
  • ActiveDirectoryIntegrated
  • SQL 인증(사용자 이름/암호)

테스트 환경용 인증의 트레이드오프

Method 비밀없는 자동 테스트 DB 생성/삭제 지원 일반적인 용도
ActiveDirectoryMsi Yes 일반적으로 아니요(서버 수준 권한이 부여되지 않는 한) Azure 호스팅 프로덕션 워크로드
ActiveDirectoryServicePrincipal 아니요(클라이언트 암호/인증서) 부여된 서버 수준 권한에 따라 다름 명시적 ID 관리가 있는 CI/CD
ActiveDirectoryPassword 아니오 예(충분한 SQL 권한 포함) 개발자 및 제어된 CI 환경
SQL 인증 아니오 예(충분한 SQL 권한 포함) 로컬 또는 격리된 테스트 환경

해결 방법:

  • 개발용: --keepdb 플래그를 사용하여 테스트 데이터베이스 정리를 건너뜁니다.

    python manage.py test --keepdb

  • CI/CD 파이프라인의 경우: 전용 테스트 데이터베이스를 미리 만들고 관리 ID CREATE TABLE 및 ALTER 권한을 부여합니다.

    -- Connect as a server admin, then:
USE [test_database_name];

-- Grant permissions for managed identity (replace with your identity name)
CREATE USER [your-app-identity] FROM EXTERNAL PROVIDER;
GRANT CREATE TABLE TO [your-app-identity];
GRANT ALTER ON SCHEMA::dbo TO [your-app-identity];

  • 대안: 테스트 환경에 SQL 인증을 사용하거나 CI/CD 테스트 실행기용으로 ActiveDirectoryPassword 전환합니다.

롤백 프로시저

마이그레이션이 중간에 실패하면 이 롤백 시퀀스를 사용하여 알려진 양호한 상태로 돌아갑니다.

  1. 추가 스키마 드리프트를 방지하기 위해 애플리케이션 쓰기를 중지합니다.

  2. 마이그레이션 상태 검사:

    python manage.py showmigrations
python manage.py sqlmigrate <app_label> <migration_number>

  3. 마지막으로 정상으로 확인된 마이그레이션으로 롤백:

    python manage.py migrate <app_label> <previous_migration>

  4. 스키마 및 마이그레이션 기록이 다른 경우 실제 데이터베이스 스키마를 확인한 후에만 상태를 신중하게 --fake 복구합니다.

  5. 먼저 스테이징 환경에서 마이그레이션을 다시 실행한 다음 프로덕션을 다시 시도합니다.

Important

삭제, 이름 바꾸기 및 열 형식 변경과 같은 파괴적인 마이그레이션의 경우 배포 전에 테스트된 백업을 수행합니다. 마이그레이션으로 롤백할 수 없는 경우 백업에서 복원하고 유효성을 다시 검사한 마이그레이션을 다시 적용합니다.

Docker 및 컨테이너 문제

컨테이너 이미지에는 명시적 ODBC 드라이버 설치 및 빌드 종속성이 필요합니다.

컨테이너에서 ODBC 드라이버를 찾을 수 없음

증상:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

가능한 원인 및 솔루션:

  • 컨테이너 이미지에 ODBC 드라이버가 설치되지 않음

    슬림 또는 알파인 기본 이미지에는 ODBC 드라이버가 포함되지 않습니다. Microsoft APT 리포지토리를 추가하고 Dockerfile에 msodbcsql18를 설치합니다. 전체 Dockerfile 예제는 App Service에 배포 를 참조하세요.

  • 누락된 unixodbc-dev 패키지

    pyodbc 휠은 libodbc.so에 링크됩니다. Python 패키지를 설치하기 전에 설치 unixodbc-dev (Debian/Ubuntu) 또는 unixODBC-devel (RHEL/Fedora).

pyodbc가 슬림한 이미지에서 빌드하지 못함

증상:

error: command 'gcc' failed: No such file or directory

또는:

fatal error: sql.h: No such file or directory

해결 방법: pip install 전에 빌드 종속성을 설치합니다.

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    unixodbc-dev

또는 다단계 빌드를 사용하여 최종 이미지를 작게 유지합니다.

# Build stage
FROM python:3.12-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ unixodbc-dev
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Runtime stage
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl gnupg2 unixodbc \
    && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
    && curl -fsSL https://packages.microsoft.com/config/debian/12/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 \
    && apt-get purge -y --auto-remove curl gnupg2 \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/*

컨테이너가 SQL Server 연결할 수 없습니다.

증상:

django.db.utils.OperationalError: ('08001', '... TCP Provider: Error code 0x2749 ...')

가능한 원인 및 솔루션:

  • Docker Compose 서비스 이름이 호스트로 사용되지 않음

    Docker Compose를 사용할 때는 DB_HOST을 서비스 이름(예: db)으로 설정하고, localhost 또는 127.0.0.1로 설정하지 마세요.

  • SQL Server 컨테이너가 준비되지 않음

    SQL Server 컨테이너를 시작하는 데 몇 초 정도 걸립니다. 상태 검사 또는 시작 지연을 추가합니다.

    services:
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    healthcheck:
      test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -No -Q "SELECT 1" || exit 1
      # $$ escapes the $ sign in Docker Compose YAML
      interval: 10s
      retries: 10
      start_period: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

  • 포트 매핑 충돌

    호스트에서 다른 SQL Server 인스턴스가 실행되는 경우 노출된 포트(예1434:1433: )를 변경하고 그에 따라 Django 구성을 업데이트합니다.

Azure SQL 일시적 오류 복구

백 엔드는 mssql-django 쿼리를 통해 Azure SQL Database 및 Azure SQL Managed Instance 연결을 자동으로 검색합니다SERVERPROPERTY('EngineEdition'). Azure SQL 대해 실행하는 경우 백 엔드는 일시적인 오류(예: 임시 리소스 제한 또는 간단한 네트워크 중단)에 대한 연결을 다시 시도합니다.

connection_retries 및 connection_retry_backoff_time 옵션을 사용하여 이 동작을 조정할 수 있습니다.

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_retries": 5,
    "connection_retry_backoff_time": 5,
},

이러한 설정은 초기 연결 설정에만 적용됩니다. 백 엔드는 실패한 쿼리를 다시 시도하지 않습니다. 연결이 설정된 후 일시적인 오류로 쿼리가 실패하면 예외가 애플리케이션 코드로 전파됩니다. 쿼리 수준 복원력을 위해 애플리케이션 수준 재시도 논리(예: django-retry-db 또는 사용자 지정 미들웨어)를 사용합니다.

느린 쿼리 및 계획 회귀

이러한 문제는 일반적으로 Django 수준 쿼리 검토와 함께 서버 쪽 분석이 필요합니다.

쿼리 속도가 느려지거나 시간 초과가 시작됩니다.

증상:

시간이 지남에 따라 동일한 쿼리 세트가 느려지거나 배포, 인덱스 변경 또는 통계 업데이트 후 시간이 초과되기 시작합니다.

가능한 원인 및 솔루션:

  • 기본 제공 성능 보고서 시작

    SQL Server 및 Azure SQL Managed Instance 경우 SQL Server Management Studio 성능 대시보드를 엽니다. Azure SQL Database 경우 Azure SQL Database 대한 Query Performance Insight를 엽니다. 이러한 도구는 비용이 많이 드는 쿼리, 대기 및 리소스 압력을 빠르게 표시하기 때문에 일반적으로 임시 DMV 쿼리보다 더 나은 첫 번째 단계입니다.

  • 회귀 계획

    쿼리 저장소 사용하여 느린 쿼리를 찾고 여러 계획이 있는지 확인합니다. 쿼리 저장소 사용하여 워크로드를 모니터링하기 위한 모범 사례에 설명된 회귀 쿼리 및 상위 리소스 사용 쿼리 보기부터 시작합니다.

  • 비효율적인 실행 계획

    해당 문에 대한 실제 실행 계획을 열어 테이블 또는 인덱스 스캔, 대규모 키 조회, 해시 스필 또는 부정확한 행 수 추정치가 있는지 확인하세요. 배경은 실행 계획 개요를 참조하세요.

  • 잘못된 병목 현상이 식별됨

    쿼리가 CPU 바인딩되지 않은 경우 쿼리 저장소 대기 통계를 사용하고 병목 상태를 식별하여 CPU, 메모리, 디스크 I/O, 차단 및 연결 압력을 구분합니다.

  • 잘못된 계층에 적용된 수정

    인덱스 추가 또는 조정, 통계 업데이트, 선택한 열 및 행 줄이기 또는 대량 쓰기 일괄 처리 등 가장 작은 효과적인 수정 사항을 적용합니다. 긴급 완화가 필요한 경우 DBA는 근본 원인을 수정하는 동안 쿼리 저장소 알려진 좋은 계획을 일시적으로 강제 적용할 수 있습니다.

대화형 쿼리에 dbshell 사용

Django의 dbshell 관리 명령은 데이터베이스에 연결된 대화형 SQL 셸을 엽니다.

python manage.py dbshell

백엔드는 Microsoft ODBC 드라이버를 구성할 때 sqlcmd를 사용하고, FreeTDS를 사용할 때는 isql를 사용합니다. 도구가 PATH에 있는지 확인합니다.

  • Windows: sqlcmd SQL Server 도구에 포함되거나 별도로 다운로드할 수 있습니다.
  • Linux 및 macOS: Microsoft 리포지토리에서 설치 mssql-tools18 합니다.

관련 콘텐츠

  • Last updated on