Python 및 Pyodbc를 사용하여 Microsoft SQL Server에 연결

pyodbc를 사용하면 ODBC를 통해 Python 애플리케이션을 Microsoft SQL Server에 연결할 수 있습니다. Python 패키지와 호환되는 SQL Server ODBC 드라이버를 모두 설치한 다음, 서버·데이터베이스·드라이버·인증 설정을 pyodbc.connect()에 전달합니다. 이 안내에서는 SQL을 직접 사용합니다. 데이터베이스 테이블을 Python 객체로 다루고 싶다면 ORM을 사용하는 방법도 있습니다. (Microsoft SQL Server)

pyodbc와 SQL Server ODBC 드라이버 설치

애플리케이션을 실행하는 것과 동일한 Python 환경에 pyodbc를 설치합니다. 예를 들어 python -m pip install pyodbc를 실행하면 됩니다. 이 명령은 Python 인터페이스를 설치하지만 Microsoft의 ODBC 드라이버까지 설치하지는 않습니다. 프로그램이 실행될 컴퓨터나 컨테이너에 SQL Server ODBC 드라이버를 별도로 설치하고, 드라이버 이름이 실제 설치된 이름과 정확히 일치하는지 확인하세요. 흔히 사용하는 드라이버 이름은 ODBC Driver 18 for SQL Server입니다. 시스템에서 사용할 수 있는 이름을 입력해야 합니다.

연결하기 전에 서버 주소와 데이터베이스 이름을 확인하세요. 서버에는 호스트 이름, 주소 또는 db.example.net\SQLEXPRESS와 같은 호스트 및 인스턴스 이름을 사용할 수 있습니다. 호스팅 환경에서는 포트도 필요할 수 있습니다. 관리자에게 선택한 데이터베이스에 계정이 접근할 수 있도록 권한을 요청해야 할 수도 있습니다. SQL Server 연결 정보는 Python의 작업 디렉터리와 무관하지만, 운영체제의 ODBC 관리자가 드라이버를 사용할 수 있어야 합니다.

드라이버와 신뢰된 인증으로 연결

통합 인증이 설정된 Windows 환경에서는 Trusted_Connection=yes를 포함한 드라이버 기반 연결 문자열을 사용하세요. 드라이버, 서버, 데이터베이스 값을 현재 설치 환경에 맞게 바꿉니다. 다음 간단한 프로그램은 필드가 어떻게 결합되는지 확인할 수 있도록 연결 문자열을 만들고 출력합니다. 데이터베이스에 접속하지는 않습니다.

다음 예제를 실행하세요.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

driver = "ODBC Driver 18 for SQL Server"
server = "db.example.net"
database = "Sales"
connection_string = (
    f"Driver={{{driver}}};"
    f"Server={server};"
    f"Database={database};"
    "Trusted_Connection=yes;"
)
print(connection_string)

Driver={ODBC Driver 18 for SQL Server};Server=db.example.net;Database=Sales;Trusted_Connection=yes;

애플리케이션에서 연결을 열려면 해당 문자열을 pyodbc.connect(connection_string)에 전달하세요. 통합 인증은 프로세스가 사용하는 운영체제 계정을 사용하며 운영체제, 드라이버, SQL Server 설정에 따라 달라집니다. SQL Server 사용자 이름과 비밀번호를 제공하는 방식과는 다릅니다. TLS 설정은 조직의 인증서 정책을 따르세요. 드라이버 버전에 따라 기본 암호화 설정이 다를 수 있으므로, 연결을 성공시키려고 인증서 검사를 비활성화하지 마세요.

자격 증명을 사용해 DSN으로 연결

DSN(Data Source Name)은 호스트에 설정하는 ODBC 구성입니다. 서버와 드라이버의 공통 설정을 여기에 저장하면 애플리케이션은 DSN 이름과 필요한 경우 자격 증명만 제공하면 됩니다. 연결 문자열 형식은 DSN=SalesReadOnly;UID=app_reader;PWD=<secret>;입니다. DSN은 Python 프로세스와 동일한 환경에 존재하고 해당 프로세스에서 접근할 수 있어야 합니다. 대화형 사용자 계정으로 설정한 DSN은 서비스 계정이나 컨테이너에서 사용할 수 없을 수도 있습니다.

자격 증명은 소스 코드에 커밋하지 말고 비밀 관리 도구나 환경별 설정을 통해 전달하세요. 비밀 값에 특수 문자가 있으면 ODBC 연결 문자열의 인용 규칙을 따르거나 자격 증명을 별도로 설정해야 합니다. 그렇지 않으면 세미콜론이 필드 구분자로 처리될 수 있습니다. 비밀번호가 로그에 노출될 수 있으므로 완성된 연결 문자열을 출력하지 마세요. DSN 문자열을 사용해 동일하게 pyodbc.connect(...)를 호출하고, DSN과 서버 설정에 맞춰 통합 인증 또는 SQL 인증을 선택합니다.

쿼리를 실행하고 리소스 닫기

연결한 뒤 커서를 만들고 SQL을 실행한 다음, 반환된 행을 가져오거나 순회합니다. 사용자 입력이나 애플리케이션 데이터에서 가져온 값에는 매개변수 표시자를 사용하세요. pyodbc에서 위치 기반 표시자는 ?입니다. 값을 SQL 문자열과 분리해 전달하면 데이터가 SQL 텍스트와 뒤섞이지 않습니다. 매개변수는 데이터 값에 사용하는 것이며 테이블 이름이나 열 이름에는 사용할 수 없습니다. 식별자를 바꿔야 한다면 고정된 허용 목록에서 선택하고 SQL Server 규칙에 맞게 인용하세요.

일반적인 애플리케이션 흐름은 connection = pyodbc.connect(connection_string)으로 연결한 다음 cursor = connection.cursor()와 cursor.execute("SELECT name FROM dbo.Customers WHERE customer_id = ?", customer_id)를 실행하는 것입니다. 행을 처리하려면 cursor를 순회하고, 결과가 메모리에 담을 수 있을 만큼 작다면 fetchall()을 호출할 수 있습니다. 결과가 큰 경우에는 행을 조금씩 처리하세요. 쿼리에 지정한 테이블과 열이 선택한 데이터베이스에 존재한다고 가정하므로 실제 스키마에 맞게 바꿔야 합니다.

connection = pyodbc.connect(connection_string)이 성공하면 커서 작업을 try 블록 안에서 수행하고 finally 절에서 연결을 닫으세요. 즉, try: ... finally: connection.close() 형태로 작성합니다. 커서를 정리하려면 그 블록 안에서 with connection.cursor() as cursor:를 사용하면 됩니다. 커서 컨텍스트를 벗어나면 커서가 닫힙니다. with connection:과 같은 pyodbc 연결 컨텍스트는 트랜잭션 범위를 관리합니다. 정상적으로 종료되면 커밋하고 예외가 전파되면 롤백하지만, 연결 자체를 닫지는 않습니다. try 안에서 트랜잭션 컨텍스트와 커서 컨텍스트를 함께 사용한 뒤 finally에서 connection.close()를 호출할 수 있습니다. 연결이 성공적으로 열린 경우, 이렇게 하면 정상 종료와 예외 종료 모두에서 쿼리 처리가 끝난 뒤 연결이 닫힙니다. 데이터를 변경한다면 트랜잭션을 어느 시점에 커밋할지 명시적으로 정하세요. 이 사용 패턴에는 설정된 SQL Server, 드라이버, 스키마가 필요하며 이 문서에서는 실행하지 않았습니다.

일반적인 연결 오류 진단

pyodbc에서 드라이버를 찾을 수 없다고 보고하면, 프로그램의 실행 환경에 ODBC 드라이버가 설치되어 있는지 확인하세요. 또한 Driver={...} 값이 공백과 버전을 포함해 등록된 이름과 일치하는지 확인합니다. 서버에 연결할 수 없다면 DNS 또는 호스트 이름 철자, 포트와 인스턴스 설정, 방화벽 접근, SQL Server의 네트워크 연결 허용 여부를 확인하세요. 시간 초과는 대체로 연결 문제나 서버 부하를 가리킵니다. 제한 시간을 늘려도 대상 주소가 잘못된 문제는 해결되지 않습니다.

로그인에 실패하면 연결에서 실제로 어떤 계정을 사용하는지 확인하세요. 신뢰된 인증은 프로세스의 계정을 사용하고 UID와 PWD는 SQL 자격 증명을 요청합니다. 두 방식을 혼용하면 잘못된 계정 정보가 전달될 수 있습니다. 그런 다음 데이터베이스 접근 권한과 데이터베이스 이름을 확인하세요. 인증서 또는 암호화 오류가 발생하면 검증을 약화시키지 말고 관리자와 함께 서버 인증서 체인과 드라이버의 암호화 설정을 확인합니다. 마지막으로 연결 문자열에 세미콜론이 빠졌는지, 드라이버 이름을 감싼 중괄호가 맞는지, 키에 실수로 공백이 들어갔는지, 특수 문자가 올바르게 처리됐는지 살펴보세요. 진단 로그에는 필요한 정보를 남기되 비밀번호와 다른 비밀 값은 가리세요.

드라이버와 연결 문자열에 대한 자세한 내용은 pyodbc SQL Server 연결 안내와 공식 pyodbc 문서를 참조하세요. 쿼리 결과를 읽는 관련 예제는 Python에서 fetchall()을 사용해 데이터베이스 요소 추출하기를 참조하세요. 한국어 대상 페이지는 제공되지 않아 이 링크는 영어 페이지로 연결됩니다.