mssql-python 문제 해결

이 글을 이용해 운전자를 mssql-python 위한 문제 해결 안내를 찾아보세요. 당신의 문제와 일치하는 증상이나 오류 메시지부터 시작하세요.

설치 문제

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

지원되지 않는 Python 버전, 누락된 휠, 비활성 가상 환경, 누락된 리눅스 라이브러리에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.

충돌하는 드라이버 설치

와 를 함께 설치할 때 mssql-python 발생하는 가져오기 오류나 예상치 못한 동작에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.pyodbc

연결 문제

서버에 연결할 수 없습니다

SQLSTATE08001, 접근 불가능한 서버, 중단된 서비스, Azure SQL 방화벽 규칙에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.

로그인 실패

SQLSTATE 28000, 인증 모드 불일치, 유효하지 않은 자격 증명, 누락된 데이터베이스 사용자에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.

연결 시간 초과

SQLSTATE HYT00 또는 HYT01네트워크 지연, 느린 서버, 연결 타임아웃 설정에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.

SSL 인증서 오류

신뢰할 수 없는 인증서 오류 및 안전한 로컬 개발 옵션에 대해서는 설치 및 연결 문제 문제 해결을 참조하세요.

쿼리 실행 문제

테이블 또는 객체를 찾지 못함

SQLSTATE 42S02, 데이터베이스 컨텍스트, 스키마 자격 확인, 테이블 존재 확인에 대해서는 Troubleshoot query, data, and operation issues를 참조하세요.

구문 오류

SQLSTATE 42000, SQL 문법, 문자열 이스케이핑, 매개변수화된 쿼리에 대해서는 쿼리, 데이터, 연산 문제 문제 해결을 참조하세요.

매개변수 오류

SQLSTATE 07001, 자리 표시자 수, 지원되는 매개변수 스타일에 대해서는 '쿼리, 데이터 및 연산 문제 문제 해결'을 참조하세요.

데이터 타입 문제

날짜 변환 오류

SQLSTATE 22007 및 datetime 매개변수 변환에 대해서는 쿼리, 데이터 및 작업 문제 문제 해결을 참조하세요.

소수점 정밀도 문제

절단되거나 반올림된 십진수 값에 대해서는 쿼리, 데이터 및 연산 문제 문제 해결을 참조하세요.

유니코드 인코딩 문제

복잡한 특수 문자와 유니코드 열 유형에 대해서는 쿼리 , 데이터 및 연산 문제 문제 해결을 참조하세요.

성능 문제

느린 쿼리 실행

인덱싱, 대규모 결과 집합, 연결 풀링에 대해서는 쿼리, 데이터 및 작업 문제 문제 해결을 참조하세요.

큰 결과에서의 메모리 문제

대규모 결과 세트의 스트리밍 및 페이지 지정에 대해서는 '쿼리, 데이터 및 운영 문제 문제 해결'을 참조하세요.

거래 문제

자동 커밋을 이용한 임시 테이블 스코핑

롤백 후 사라지는 임시 테이블과 자동 커밋이 필요한 DDL 문장에 대해서는 쿼리, 데이터, 연산 문제 문제 해결을 참조하세요.

트랜잭션 미완료

연결이 종료된 후에도 지속되지 않는 데이터 변경 사항은 ' 쿼리, 데이터 및 운영 문제 문제 해결'을 참조하세요.

교착 상태 오류

SQLSTATE 40001, 재시도 지침, 반복 교착 상태에 대해서는 쿼리 , 데이터 및 운영 문제 문제 해결을 참조하세요.

벌크 로드 문제

대량 복사 중 제약 조건 위반

대량 복사 중 주요 키, 고유 키, 검사 또는 외래 키 위반에 대해서는 쿼리 , 데이터 및 운영 문제 문제 해결을 참조하세요.

열 매핑 오류

대량 복사본 열수 및 열 순서 불일치에 대해서는 쿼리, 데이터 및 작업 문제 문제 해결을 참조하세요.

대량 복사 중 형식 불일치

대량 복사 후 잘렸거나 반올림되거나 잘못된 값에 대해서는 ' 문제 해결 쿼리, 데이터 및 운영 문제'를 참조하세요.

NumPy 타입 바인딩 실패

NumPy 정수 또는 float 타입의 매개변수 바인딩 실패에 대해서는 쿼리, 데이터 및 연산 문제 문제 해결을 참조하세요.

임시 테이블을 이용한 벌크카피

세션 임시 테이블과 함께 사용할 bulkcopy() 때의 오류는 Invalid object name 쿼리, 데이터 및 운영 문제 문제 해결을 참조하세요.

컨테이너 및 CI 문제

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

리눅스 환경에서 누락 libltdl 되거나 Kerberos 라이브러리가 없는 경우는 설치 및 연결 문제 문제 해결을 참조하세요.

macOS 설치 후 SSL 오류

macOS의 SSL 관련 오류(Apple silicon 포함)는 설치 및 연결 문제 문제 해결을 참조하세요.

진단 도구

드라이버 로깅 활성화

DEBUG 로그를 활성화하는 데 사용 mssql_python.setup_logging() 하세요. 드라이버는 SQL 문, 매개변수, 내부 ODBC 작업, 연결 상태 변경 등을 기록합니다.

import mssql_python

# Enable logging to file (default)
mssql_python.setup_logging()

# Output to stdout (useful for CI/CD and containers)
mssql_python.setup_logging(output="stdout")

# Output to both file and stdout
mssql_python.setup_logging(output="both")

# Custom log file path (must use .txt, .log, or .csv extension)
mssql_python.setup_logging(log_file_path="/var/log/myapp/mssql.log")

로그 파일은 CSV 형식을 사용하며 512MB로 자동 회전하며 5개의 백업을 제공합니다. 드라이버는 비밀번호와 접근 토큰과 같은 민감한 데이터를 로그 출력에서 소독합니다.

드라이버 로그에 애플리케이션 항목을 추가하려면 다음을 사용하세요 driver_logger:

import mssql_python
from mssql_python.logging import driver_logger

mssql_python.setup_logging()

driver_logger.debug("[App] Starting data processing")
driver_logger.error("[App] Failed to process record")

주의

로깅에는 성능 오버헤드가 있습니다. 문제를 해결할 때만 활성화하세요. 기본적으로 프로덕션 환경에서 활성화하지 마세요.

운전자 정보 받기

활성 연결에서 드라이버 버전과 서버 정보를 조회하세요:

import mssql_python

conn = mssql_python.connect(connection_string)

print(f"Version: {mssql_python.__version__}")
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

연결 상태 확인

연결이 아직 열려 있는지 테스트하기 위해 가벼운 쿼리를 실행하세요:

import mssql_python

try:
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    print("Connection is open")
except mssql_python.Error:
    print("Connection is closed or broken")

빠른 참고: 흔한 오류

오류	SQLSTATE	일반적 원인	Troubleshooting
클라이언트가 연결을 설정할 수 없음	08001	서버에 연결할 수 없음	서버에 연결할 수 없습니다
로그인 실패	28000	잘못된 자격 증명	로그인 실패
시간 제한 만료됨	HYT00 또는 HYT01	느린 네트워크	연결 제한 시간
잘못된 개체 이름	42S02	잘못된 표 또는 스키마	테이블 또는 객체를 찾지 못함
구문 오류	42000	SQL 오류	구문 오류
제약 조건 위반	23000	외래키 또는 주 키 위반	벌크복사 중 제약 위반
교착 상태	40001	잠금 경합	교착 상태 오류

관련 콘텐츠

• mssql-python용 오류 처리 및 SQLSTATE 코드
• mssql-python용 연결 문자열
• mssql-python을 이용한 연결 풀링
• GitHub 이슈