mssql-python 설치 및 연결 문제 문제 해결

이 글을 사용해 드라이버의 mssql-python 설치, 연결, 컨테이너, 지속적 통합(CI) 문제를 진단하세요.

설치 문제

PIP 설치 실패 또는 소스에서 빌드

증상:

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

가능한 원인 및 해결 방법:

  • 사용 중인 플랫폼용 사전 빌드된 wheel이 없습니다

    • 지원되는 Python 버전(3.10 이후)과 플랫폼을 사용 중인지 확인하세요. 호환성 매트릭스는 지원 수명 주기 를 참조하세요.
    • 설치 전에 pip install --upgrade pip로 pip를 업그레이드하세요.
    • 반복 가능한 팀 환경에서는 반복 가능한 배포 에서 잠긴 워크플로우나 컨테이너 및 로컬 개발 의 컨테이너 패턴을 사용하여 로컬 머신 드리프트를 줄이세요.

  • 가상 환경이 활성화되지 않음

    • 먼저 가상 환경을 활성화하세요. 시스템 내 Python 설치는 권한 오류나 충돌을 일으킬 수 있습니다.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • 누락된 리눅스 시스템 라이브러리
    • 이 드라이버는 리눅스에서 여러 시스템 라이브러리를 필요로 합니다. 설치해야 할 패키지는 플랫폼별 의존성을 참조하세요.

충돌하는 드라이버 설치

증상:

설치 mssql-pythonpyodbc 후 같은 환경에서 가져오기 오류나 예상치 못한 동작이 발생합니다.

Solution:

mssql-python 그리고 pyodbc 공존할 수 있습니다. 충돌이 발생하면 깔끔한 가상 환경을 만드세요.

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

연결 문제

서버에 연결할 수 없습니다

증상:

OperationalError: [08001] (0) Client unable to establish connection

가능한 원인 및 해결 방법:

  • 서버에 접속할 수 없습니다

    • 서버 이름과 포트가 정확한지 확인하세요.
    • ping <server> 또는 telnet <server> 1433로 네트워크 연결성을 확인하세요.
    • 방화벽이 포트 1433에서 아웃바운드 연결을 허용하는지 확인하세요.

  • SQL Server가 실행되지 않음

    • SQL Server 서비스가 시작되었는지 확인하세요.
    • 이름 있는 인스턴스의 경우, SQL Server 브라우저 서비스가 실행 중인지 확인하세요.

  • Azure SQL firewall rules

    • Azure 포털에서 Azure SQL 방화벽 규칙에 클라이언트 IP 주소를 추가하세요.
    • Azure SQL Managed Instance의 경우, 허용된 네트워크에서 연결하는지 확인하세요.

기본 TCP 연결 테스트 :

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

로그인 실패

증상:

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

가능한 원인 및 해결 방법:

  • 인증 모드 불일치

    • Azure SQL Database, Azure SQL Managed Instance, Fabric 내 SQL 데이터베이스의 경우, Microsoft Entra 모드(예: Authentication=ActiveDirectoryDefault.)를 선호합니다.
    • SQL 인증을 의도적으로 사용한다면, 서버가 이를 허용하고 해당 엔드포인트에 맞는 올바른 로그인 형식을 사용하는지 확인하세요.

  • 잘못된 SQL 인증 자격 증명

    • 사용자 ID와 비밀번호를 확인하세요.
    • Azure SQL의 경우, 전체 사용자 ID를 포함하세요: <user_id>@<server>.

  • 사용자는 데이터베이스에 존재하지 않습니다

    • 사용자가 지정된 데이터베이스에 접근할 수 있는지 확인하세요.
    • 로그인이 데이터베이스 사용자에게 매핑되어 있는지 확인하세요.

  • 인증 설정되지 않음

    • Microsoft Entra 인증 사용(권장): Authentication=ActiveDirectoryDefault.
    • 로컬 SQL Server 인스턴스에서 SQL 인증을 받아야 할 문제를 해결할 때, SQL Server가 혼합 모드 인증을 사용하는지 확인하세요.

연결 시간 초과

증상:

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

가능한 원인 및 해결 방법:

  • 서버가 응답이 느려요

    • 연결 타임아웃을 늘리세요.
    conn = mssql_python.connect(connection_string, timeout=60)

  • 네트워크 대기 시간

    • 서버로 가는 네트워크 경로를 확인하세요.
    • 더 짧은 네트워크 경로나 가상 사설망(VPN)을 고려해 보세요.

  • 서버 부하가 큰 상황

    • 비혼잡 시간대에 연결하려고 노력하세요.
    • 데이터베이스 관리자에게 연락하세요.

SSL 인증서 오류

증상:

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

솔루션:

신뢰할 수 있는 인증서나 컨테이너 및 로컬 개발의 로컬 개발 패턴을 선호하세요. 직접 제어하는 서버를 대상으로 하는 로컬 개발에만 TrustServerCertificate=yes를 사용하세요.

자체 서명 인증서를 사용한 개발 및 테스트:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Caution

TrustServerCertificate=yes 지역 전용 대체 수단입니다. 공유 개발 컨테이너, CI 파이프라인, 운영 배포 등으로 가져가지 마세요. 자세한 내용은 암호화 및 인증서를 참조하세요.

운영 시 적절한 인증서를 설치하고 다음을 사용하세요:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "HostnameInCertificate=<server>.domain.com;"
)

컨테이너 및 CI 문제

리눅스에서 누락된 시스템 라이브러리

증상:

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

배포판에 필요한 시스템 패키지를 설치하세요:

Distribution 설치 명령
우분투(Ubuntu 또는 Debian) sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
레드 햇 또는 페도라 sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Dockerfile 예시는 컨테이너 및 로컬 개발을 참조하세요.

macOS 설치 후 SSL 오류

증상:

macOS에서 연결할 때, 특히 애플 실리콘에서 SSL 관련 오류가 발생합니다.

Solution:

Homebrew로 OpenSSL을 설치하고, 링커 플래그를 설정하세요:

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

관련 콘텐츠

  • Last updated on