mssql-django 문제 해결

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

mssql-django 2.0은 기본 pyodbc 드라이버 경로와 선택적 mssql-python 드라이버 경로를 지원합니다. 자세한 내용은 mssql-django의 데이터베이스 드라이버 선택을 참조하세요.

연결 문제

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

pyodbc 경로에서 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 드라이버가 설치되지 않음

  기본 pyodbc 경로를 사용할 때 Microsoft ODBC 드라이버 for SQL Server를 설치하세요. 다운로드 링크는 SQL Server 대한 ODBC 드라이버 다운로드를 참조하세요. mssql-python 경로는 외부에 설치된 ODBC 드라이버를 사용하지 않습니다.

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

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

  DATABASES = {
      "default": {
          "ENGINE": "mssql",
          "NAME": "<database>",
          "USER": "<user_id>",
          "PASSWORD": "<password>",
          "HOST": "<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 데이터 원본을 확인합니다.

MSSQL-python이 연결 옵션을 거부합니다

증상:

"python_driver": "mssql_python"을(를) 설정하는 별칭은 pyodbc 연결 문자열 키워드를 OPTIONS["extra_params"](으)로 옮긴 후 연결 설정 과정에서 다음 오류 중 하나가 발생하며 실패합니다:

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Unknown keyword 'longasmax' is not recognized

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Reserved keyword 'driver' is controlled by the driver and cannot be specified by the user

메시지 내 키워드 이름은 소문자로 되어 있어서, 당신이 쓴 LongAsMax 키워드는 로 표시됩니다 longasmax. ConnectionStringParseError DB-API 예외 계층 구조에 포함되지 않기 때문에 Django가 이를 오류로 django.db.utils 재포장하지 않습니다.

가능한 원인 및 솔루션:

• extra_params의 pyodbc 전용 키워드

  mssql-python 경로는 허용 목록을 기준으로 extra_params를 검증합니다. DRIVER 및 APP은 운전자용으로 예약되어 있으며 Reserved keyword 양식을 생성합니다. DSN, MARS_Connection, Description 및 Connect Timeout, LongAsMax, ColumnEncryption, UseFMTONLY, Regional, Network Library, WSID, AnsiNPW, QuotedId, Current Language, Unknown keyword와 같은 pyodbc 전용 키워드는 허용 목록에 없으며 SERVERNAME 양식을 생성합니다. 키워드를 제거하거나, ODBC 옵션이 필요한 별칭에 대해 기본 pyodbc 경로를 사용하세요.

• mssql-python을 제어할 드라이버 옵션이 예상됩니다

  mssql-python 경로는 unicode_results, driver, host_is_server, dsn를 무시합니다. HOST 및 PORT은 SERVER=<server>,<port>이 되고, 빈 HOST은 localhost가 됩니다.

MSSQL-Python 의존성은 너무 오래되었습니다

증상:

"python_driver": "mssql_python"를 설정하는 별칭은 연결 설정 중 다음 오류 중 하나가 발생하며 실패합니다:

django.core.exceptions.ImproperlyConfigured: mssql-python 1.15.0 or newer is required; you have 1.14.0

django.core.exceptions.ImproperlyConfigured: The 'python_driver' connection option requests mssql-python, but the module could not be imported: No module named 'mssql_python'. Install it with 'pip install "mssql-python>=1.15.0"'.

두 번째 양식은 모듈이 mssql_python 전혀 임포트가 불가능하다는 뜻입니다.

해결책: . 설치하세요 mssql-python>=1.15.0. mssql-django 2.0은 mssql-python>=1.15.0를 선언하므로, 일반적인 pip install mssql-django는 지원되는 플랫폼에서 호환되는 버전으로 확인됩니다.

드라이버 17 대체 기능은 mssql-python에 적용되지 않습니다

증상:

"python_driver": "mssql_python"를 설정하는 별칭은 Microsoft ODBC Driver 17 for SQL Server가 설치되어 있어도 여전히 작동하지 않습니다.

이 사건에는 특별한 오류가 없습니다. mssql-python 경로에서는 driver 옵션을 아무런 경고 없이 무시하므로, 적용되는 기본 오류와 함께 연결이 실패합니다. 운전자 이름을 extra_params 대신 이동시키면 오류가 발생합니다 Reserved keyword 'driver' . mssql-python이 연결 옵션을 거부한다는 점을 참고하세요.

해결책: 외장 설치된 ODBC 드라이버 17을 사용해야 할 경우 기본 pyodbc 경로를 사용하세요. mssql-python 경로는 Driver 17로 되돌아가지 않고, 이 옵션을 무시합니다 driver . 그 경로는 별도로 설치된 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 '<user_id>'. (18456) (SQLDriverConnect); [28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456)")

mssql-python 경로에서:

django.db.utils.OperationalError: Driver Error: Invalid authorization specification; DDBC Error: [Microsoft][SQL Server]Login failed for user '<user_id>'.

가능한 원인 및 솔루션:

• 잘못된 자격 증명

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

• 그 데이터베이스 NAME 는 존재하지 않습니다

  SQL Server에서는 mssql-python 경로가 같은 메시지와 함께 잘못된 비밀번호를 발생 OperationalError 시키므로, 메시지만으로는 어느 비밀번호를 건드렸는지 알 수 없습니다. 자격 증명을 변경하기 전에 데이터베이스가 존재하는지 확인하세요. NAME이 master을 가리키도록 하여 로그인만 별도로 테스트해 보세요. 그렇게 해서 연결되면 자격 증명은 올바르고 문제는 데이터베이스에 있습니다. pyodbc 경로는 이 경우를 별도로 로 보고합니다 Cannot open database "<database>" requested by the login. The login failed. (4060).

  Azure SQL Database는 이 경우를 다르게 보고합니다. mssql-python 경로에서 Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. 오류가 발생합니다. 메시지에 서버 이름이 표시되지만, 서버 이름 자체는 정상입니다. 대신 NAME을 확인해 보세요.

• 사용자가 존재하지 않음

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

• SQL Server 인증 사용 안 함

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

연결 시간 초과

증상:

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

가능한 원인 및 솔루션:

• 네트워크 대기 시간

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

• 자동 일시 중지가 사용하도록 설정된 Azure SQL Database 서버리스

  자동 일시정지된 데이터베이스는 첫 연결 시도 시 재개되며, 그 시도는 오류 40613으로 실패할 수 있지만 데이터베이스는 재개됩니다. 최소 60으로 설정 connection_timeout 하고 첫 번째 연결을 다시 시도하세요. 자세한 내용은 Azure SQL Database serverless와 Auto-Pause 및 auto-resume을 참조하세요.

• 서버 오버로드됨

  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 마이그레이션 작업 중에 발생합니다.

원시 SQL 및 GROUP BY 이슈

이러한 오류는 GROUP BY 절이 포함된 원시 쿼리 또는 주석이 추가된 쿼리가 백엔드의 플레이스홀더 재작성 단계를 거칠 때 발생합니다.

IndexError GROUP BY의 이스케이프된 %% 및 실제 매개변수에 대해

증상:

IndexError: Replacement index N out of range for positional args tuple

쿼리는 GROUP BY 절이 없어도 작동하고, 이스케이프 처리된 %% 리터럴이 없어도 작동하지만, 이 둘이 실제 %s 매개변수와 함께 있으면 실패합니다.

해결책: 최신 mssql-django 버전으로 업그레이드하세요. 백엔드는 자리 표시자 재작성 정규식을 %% 및 %s에만 적용하도록 제한하므로, 이스케이프된 %% 리터럴은 원문 그대로 보존되고 유령 자리 표시자가 삽입되지 않습니다.

원시 GROUP BY 쿼리의 NotImplementedError용 IntegerChoices

증상:

NotImplementedError: Not supported type <enum '...'> (StatusChoices.IN_PROGRESS)

동일한 enum 값은 ORM 쿼리와 GROUP BY가 없는 raw 쿼리에서는 작동하지만, GROUP BY 절이 포함된 raw 쿼리에 매개변수로 전달하면 실패합니다.

해결책: 최신 mssql-django 버전으로 업그레이드하세요. 백엔드는 isinstance 경로에서 매개변수 유형 검사를 위해 GROUP BY를 사용하므로 IntegerChoices(int의 하위 클래스)가 올바르게 바인딩됩니다. bool는 여전히 bit에 바인딩되며, 일반 int는 변경되지 않습니다.

정규 표현식 조회 문제

__regex 또는 __iregex에서 행이 반환되지 않음

증상: 쿼리가 오류 없이 실행되고 빈 결과 집합을 반환하지만, 행은 패턴과 일치합니다.

Product.objects.filter(name__regex=r"^Widget \d+$")  # no rows, though "Widget 42" exists

원인: dbo.REGEXP_LIKE 패턴 내 문자 그대로 여백을 무시합니다. 이 패턴은 마치 ^Widget\d+$인 것처럼 매칭되며, 공백이 포함된 어떤 값도 이를 만족할 수 없습니다. 아무것도 올라가지 않아서 빈 결과는 데이터 문제로 보입니다.

해결책: 공백을 이스케이프 또는 캐릭터 클래스로 쓰세요:

Product.objects.filter(name__regex=r"^Widget\s\d+$")
Product.objects.filter(name__regex=r"^Widget[ ]\d+$")

Cannot find ... dbo.REGEXP_LIKE

증상:

django.db.utils.ProgrammingError: ('42000', '[42000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous. (4121) (SQLExecDirectW)')

경로 mssql-python 에서:

django.db.utils.ProgrammingError: Driver Error: Syntax error or access violation; DDBC Error: [Microsoft][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous.

원인: CLR 어셈블리가 당신이 쿼리하는 데이터베이스에 설치되어 있지 않습니다. 서버별로 설치되는 게 아니라 데이터베이스별로 설치돼요.

해결책: 그 데이터베이스를 대조해 보세요 python manage.py install_regex_clr <database> . 데이터베이스를 버리고 다시 만든 후 다시 실행하세요. 정규식 조회 설정을 참고하세요.

날짜 및 시간 문제

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

증상:

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

해결책: 최신 mssql-django 버전으로 업그레이드하세요. 백엔드는 시간대를 인식 Now() 하는 SQL을 생성하고, datetimeoffset 오프셋을 보존하며, 와 tzdata를 통해 zoneinfo 시간대 데이터를 읽습니다.

AttributeError .explain() 호출할 때

증상:

AttributeError: ... explain_format ...

해결책: 최신 mssql-django 버전으로 업그레이드하세요. 백엔드 핸들은 지원되는 모든 Django 버전의 메타데이터를 설명합니다.

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 pyodbc 경로에서 발생합니다.

유니코드 인코딩 오류

증상:

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

해결책: pyodbc 사전에서 OPTIONS 인코딩을 구성하세요. mssql-python 경로는 unicode_results를 무시합니다.

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

FreeTDS 문제

FreeTDS는 pyodbc 전용 설정이 필요하며, 이는 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 및 컨테이너 문제

컨테이너 이미지는 기본 pyodbc 경로를 사용할 때 명시적인 ODBC 드라이버 설치와 빌드 의존성이 필요합니다. mssql-python 경로에는 별도의 ODBC 드라이버 설치가 없지만, Django가 pyodbc를 로드할 때 백엔드가 pyodbc를 가져오기 때문에 unixODBC 런타임이 여전히 필요합니다.

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

증상:

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

가능한 원인 및 솔루션:

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

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

• 누락된 unixodbc-dev 패키지

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

• apt-get autoremove드라이버 설치 후 제거됨 libgssapi-krb5-2

  msodbcsql18는 libgssapi-krb5-2를 의존성으로 선언하지 않고 런타임에 로드합니다. 라이브러리는 보통 curl의 의존성으로 함께 설치되므로, curl로 --auto-remove를 퍼지하거나 나중에 apt-get autoremove를 실행하면 해당 라이브러리가 제거됩니다. 이미지는 문제없이 빌드되지만, 그 후 모든 연결이 실패합니다. 명시적으로 libgssapi-krb5-2을 설치하고, 드라이버 설치 후에는 자동 제거하지 마세요.

버전 18을 설치했을 때 드라이버 17이 누락되었다고 보고했습니다

증상:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 17 for SQL Server' : file not found (0) (SQLDriverConnect)")

오류는 버전 17을 명명하지만, odbcinst -q -d 버전 18이 등록 dpkg -l msodbcsql18 되어 있고 설치되어 있다고 나옵니다.

원인: 버전 18은 등록되었지만 로드에 실패하여 mssql-django가 설치되지 않은 버전 17로 다시 떨어집니다. Fallback은 실패한 드라이버가 아니라 두 번째로 시도한 드라이버를 보고합니다.

해결책: 설치하고 재조립하세요 libgssapi-krb5-2 . 도서관이 어떻게 사라지는지는 앞서 언급한 자동 삭제 노트를 참고하세요.

컨테이너에 pyodbc 모듈을 로딩하는 오류

증상:

django.core.exceptions.ImproperlyConfigured: Error loading pyodbc module: libodbc.so.2: cannot open shared object file: No such file or directory

원인: 이미지에 unixODBC 런타임이 없습니다. mssql-django는 Django가 백엔드를 로드할 때 pyodbc를 가져오므로, 이 오류는 mssql-python 경로에서도 연결이 시도되기 전에 발생합니다.

해결책: 설치 unixodbc (또는 unixodbc-dev).

MSSQL-Python 드라이버가 로드되지 않음

증상:

django.db.utils.OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver.

원인: mssql-python와 함께 제공되는 드라이버에는 Kerberos 런타임 라이브러리가 필요하지만, 슬림 베이스 이미지에는 이러한 라이브러리가 포함되어 있지 않습니다.

해결책: 설치 libkrb5-3 와 libgssapi-krb5-2.

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 libgssapi-krb5-2 \
    && apt-get purge -y 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 합니다.

관련 콘텐츠

• mssql-django 구성 참조
• mssql-django에 대한 연결 옵션
• mssql-django를 사용하여 논리 및 연결 복원력 다시 시도
• mssql-django의 제한 사항 및 지원되지 않는 기능
• 성능 대시보드
• Azure SQL Database에 대한 Query Performance Insight
• 쿼리 저장소를 사용하여 성능 모니터링
• 실제 실행 계획 분석
• Wiki 문제 해결
• 자주 묻는 질문(FAQ)