Microsoft ODBC 드라이버 - SQL Server용

ODBC 드라이버 다운로드

ODBC는 SQL Server용 C 및 C++로 작성한 애플리케이션을 위한 기본 원시 데이터 액세스 API입니다. Microsoft ODBC Driver for SQL Server는 SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, 그리고 Microsoft Fabric의 SQL 데이터베이스에 연결됩니다. 각 드라이버 릴리스가 지원하는 데이터베이스 버전에 대해서는 SQL 버전 호환성을 참조하세요.

ODBC를 사용할 수 있는 다른 언어는 COBOL, Perl, PHP 및 Python을 포함합니다. ODBC는 데이터 통합 시나리오에서 널리 사용되며, Microsoft PHP for SQL Server 드라이버는 이 드라이버를 기반으로 구축되었습니다.

sqlcmd와 bcp 유틸리티는 이 드라이버와 함께 작동하지만, 별도로 설치됩니다: mssql-tools18 리눅스와 macOS에서는 패키지를, Windows에서는 Microsoft 명령줄 유틸리티를 사용합니다. sqlcmd를 사용해 Transact-SQL(T-SQL) 문, 시스템 프로시저, 스크립트 파일을 실행하세요. bcp를 사용해 SQL Server 인스턴스와 데이터 파일 간에 양방향으로 데이터를 대량 복사할 수 있습니다.

시작점 선택

드라이버를 설치하려면 Windows용 시스템 요구사항, 설치 및 드라이버 파일로 가거나, Linux에 ODBC 드라이버를 설치하고, macOS에 ODBC 드라이버를 설치한 후 unixODBC 드라이버 관리자를 설치하세요.
첫 애플리케이션을 작성하려면 Connect to로 가서 C++, DSN, 연결 문자열 키워드와 속성 으로 데이터베이스를 조회하세요.
비밀번호 없는 인증으로 Azure SQL에 연결하려면 ODBC 드라이버와 함께 Microsoft Entra ID로 가세요.
기존 앱을 일시적 장애에 대해 복원력 있게 만들려면 Connection resiliency 와 High availability and disaster recovery로 가세요.
버전 17에서 업그레이드하려면 Major 버전 차이 와 연결 암호화 문제 해결 항목으로 가세요.
연결 문제나 쿼리 문제를 진단하려면 '연결 암호화 문제 해결 '과 '알려진 문제(Linux 및 macOS)'로 가세요.

Azure SQL 대한 프로덕션 기준

이 코드 조각을 프로덕션 지향 Azure SQL 연결의 시작점으로 사용합니다. 애플리케이션 구성에서 서버 이름과 데이터베이스 이름을 불러오고, 관리 신원으로 인증하여 연결 문자열에 비밀이 나타나지 않게 하며, 완전한 인증서 검증과 함께 Tabular Data Stream(TDS) 8.0 암호화를 지원합니다. 로그인 시도마다 제한 시간을 설정하고, 일시적인 오류가 발생하면 지수 백오프와 지터를 적용해 재시도합니다.

이 글의 C++ 스니펫은 간결함을 위해 include, handle allocation, log helper를 생략했습니다.

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount 그리고 ConnectRetryInterval유휴 연결 복원력을 활성화하여 유휴 중에 끊긴 연결을 투명하게 복원합니다. 초기 연결을 재시도하지 않기 때문에 이 스니펫은 애플리케이션 레벨 재시도도 구현합니다. 둘 다 보관하세요.

ODBC는 진단 결과를 반환 코드만이 아닌 방식으로 SQLGetDiagRec 보고하므로, 재시도 전에 실패를 분류하세요. 인증이나 설정 오류가 발생하면 재시도 예산 전체를 소모하지 않고 즉시 실패합니다.

이 구성의 각 부분에 대한 자세한 내용은 다음을 참조하세요.

Azure SQL 일시적 오류 목록은 일시적 결함 오류 코드(transient fault error codes)를 참조하세요.

주요 기능

크로스 플랫폼: Windows, Linux, macOS에서 동일한 API를 사용합니다.
Microsoft Entra ID 인증: 관리되는 신원, 서비스 주체, 인터랙티브 및 통합 플로우가 포함된 비밀번호 없는 연결.
엄격한 암호화: 버전 18 및 이후 버전에서 완전한 인증서 검증이 가능한 TDS 8.0 연결.
항상 암호화: 민감한 열에 대한 클라이언트 측 암호화, 맞춤형 키스토어 제공자 지원
연결 복원력: 유휴 상태에서 끊긴 연결을 투명하게 복원합니다.
고가용성: MultiSubnetFailover을 사용하는 가용성 그룹 수신기 지원.
데이터 분류: 분류된 열의 민감도 메타데이터.
벡터 데이터 타입: 벡터 타입에 대한 네이티브 지원.
분산 트랜잭션: Microsoft Distributed Transaction Coordinator(MSDTC)를 통한 XA 트랜잭션 지원.
동반 도구: sqlcmd 와 bcp, 별도로 설치.

시작하기

문서	Description
SQL Server용 ODBC 드라이버 다운로드	지원되는 모든 드라이버 버전에 대한 설치 및 패키지 다운로드가 세 플랫폼 모두에서 제공됩니다.
C++로 데이터베이스에 연결하고 쿼리합니다	연결, 쿼리 실행, 결과를 읽는 완전한 C++ 샘플로, 처음부터 끝까지 설정을 확인할 수 있습니다.
지원 수명 주기	어떤 드라이버 버전이 아직 지원되는지, 그리고 각 버전이 언제 지원 종료일인지 알려주세요.
주 버전 차이점	버전 17에서 버전 18로 넘어가면 무엇이 깨지는지, 암호화 기본 변경부터 시작됩니다.

드라이버 설치

문서	Description
시스템 요구사항, 설치 및 드라이버 파일 (Windows)	지원되는 Windows 버전, 무음 배포를 위한 설치 명령줄, 그리고 각 드라이버 파일이 디스크에 위치하는 위치.
시스템 요구사항 (리눅스 및 macOS)	각 드라이버 버전이 지원하는 리눅스 배포판과 macOS 릴리스, 그리고 SQL Server 버전 호환성도 고려해야 합니다.
Linux에 ODBC 드라이버를 설치하세요	Alpine, Debian, Red Hat, SUSE, Ubuntu, Azure Linux용 패키지 관리자 단계와 오프라인 설치, 드라이버 파일 위치 등도 포함됩니다.
macOS에 ODBC 드라이버를 설치하세요	macOS용 홈브류 탭 및 공식 단계, 버전 18, 17, 또는 13.1 설치 방법도 포함됩니다.
유닉스 ODBC 드라이버 관리자 (리눅스 및 macOS) 설치	Linux와 macOS에서 ODBC 드라이버를 로드하는 드라이버 관리자인 unixODBC를 설치하거나 업그레이드하세요.

구성 및 연결

문서	Description
DSN 및 연결 문자열 키워드 및 특성	연결 문자열 키워드, DSN 항목, `SQLSetConnectAttr` 속성의 전체 카탈로그와 각 항목에 대한 허용 가능한 값이 포함되어 있습니다.
연결 문자열 키워드 및 데이터 소스 이름 (리눅스 및 macOS)	Linux와 macOS에서 DSN을 어떻게 `odbc.ini` 정의하고 `odbcinst.ini` 정의하는지, 그리고 해당 플랫폼에 특화된 TLS와 TCP keep-alive 설정에 대해 알려주세요.
ODBC 데이터 소스 관리자 DSN (Windows)	Windows DSN 마법사 페이지에 있는 모든 옵션, UI를 통해 데이터 소스를 구성할 때 연결 문자열 대신 사용할 수 있습니다.
드라이버 인식 연결 풀링 (Windows)	어떤 연결 문자열 키워드와 특성이 연결을 별도의 풀로 분리하며, 또 어떤 항목이 재설정 시 추가 왕복 비용을 발생시키나요?

인증 및 보안

문서	Description
Microsoft Entra ID를 ODBC 드라이버와 함께 사용하세요	모든 `Authentication` 키워드 값(관리 ID 및 서비스 주체부터 대화형 및 통합까지)과 각각에 필요한 설정을 포함합니다.
ODBC 드라이버와 함께 항상 암호화를 사용하세요	클라이언트 프로세스의 민감한 열을 암호화하여 평문이 서버에 도달하지 않도록 하며, 드라이버의 API 요약과 문서화된 제한 사항을 포함합니다.
데이터 분류	서버가 기밀 열에 부착하는 민감성 라벨을 읽으면, 애플리케이션이 자체 데이터 보호 정책을 적용할 수 있습니다.
통합 인증 사용(리눅스 및 macOS)	Kerberos를 설정해서 리눅스나 macOS 클라이언트가 SQL Server 로그인 대신 Windows 자격 증명으로 연결할 수 있게 하세요.

고가용성 및 복원력

문서	Description
연결 복원력	서버가 유휴 상태인 동안 연결을 끊을 때 `IMCxx`와 `ConnectRetryCount`가 연결을 복원하는 방법과, 복구가 불가능할 때 드라이버가 반환하는 `ConnectRetryInterval` 오류입니다.
고가용성 및 재해 복구	가용성 그룹 리스너를 통해 연결하고 `MultiSubnetFailover`를 사용하여 서브넷 시간 초과로 인해 장애 조치가 지연되지 않도록 하세요.
투명한 네트워크 IP 해상도를 사용하세요	레거시 `TransparentNetworkIPResolution` 폴백이 여러 IP 주소에 대해 연결 시도 순서를 정하는 방식과, `MultiSubnetFailover`가 이를 대체하는 이유

데이터 작업

문서	Description
벡터 데이터 형식	벡터 타입을 원래의 C 표현과 대량 복사 지원을 포함해 바인딩, 전송, 검색을 할 수 있습니다.
DTC와 함께 XA 거래를 사용하세요	SQL Server를 Windows, Linux 또는 macOS의 Microsoft Distributed Transaction Coordinator를 통해 분산 트랜잭션에 참여시키세요.
프로그래밍 가이드라인 (리눅스 및 macOS)	어떤 기능은 Linux와 macOS에서 드라이버가 지원하는지, 지원하지 않는지, 그리고 문자 집합과 OpenSSL 처리가 Windows와 어떻게 다른지에 대해 궁금합니다.

진단 및 문제 해결

문서	Description
연결 암호화 문제 해결	버전 18이 기본적으로 암호화하기 때문에 나타나는 인증서 및 암호화 오류를 수정하세요.
데이터 접근 추적 (리눅스 및 macOS)	드라이버 추적을 켜고, 애플리케이션이 실제로 어떤 호출을 하는지 볼 수 있을 때 로그 파일을 캡처하세요.
알려진 문제들 (리눅스와 macOS)	확인된 결함과 그 우회 방법들. 지원 요청을 접수하기 전에 여기를 확인하세요.
자주 묻는 질문 (리눅스와 macOS)	리눅스와 macOS에서 드라이버에 대해 가장 자주 묻는 질문들에 대한 짧은 답변입니다.

출시 노트 및 버그 수정

문서	Description
Windows용 릴리스 노트	각 Windows 드라이버 릴리스마다 새로운 기능, 동작 변경 사항, 그리고 수정 사항이 추가되었습니다.
리눅스와 macOS용 릴리스 노트	새로운 기능, 동작 변경, 그리고 각 리눅스 및 macOS 드라이버 릴리스의 수정 사항들.
SQL Server 도구 릴리스 노트	Linux와 macOS에서 드라이버와 별도로 설치되는 sqlcmd 및 bcp 유틸리티의 변경 사항.

Reference

문서	Description
Windows용 ODBC 드라이버	Windows에서 드라이버가 지원하는 버전을 요약한 버전별 요약과 Windows 전용 문서들의 색인입니다.
Windows에서 ODBC 드라이버의 특징	어떤 릴리스가 각 Windows 기능과 그에 따른 동작 변화를 도입했는지.

ODBC 프로그래머 참고문헌: 이 드라이버가 구현하는 ODBC API 명세서로, 드라이버와는 별도로 문서화되어 있습니다.
SQL Server 네이티브 클라이언트 기능: 드라이버 동작은 네이티브 클라이언트 콘텐츠에만 문서화되어 있습니다. 이 문서들은 OLE DB를 설명하는 경우를 제외하고는 SQL Server용 ODBC 드라이버에 적용됩니다.
BCP 유틸리티: 드라이버와 별도로 설치된 대량 복사 유틸리티입니다.
SQLcmd 유틸리티: 드라이버와 별도로 설치된 명령줄 쿼리 유틸리티입니다.
드라이버 기능 지원 매트릭스
SQL Server 드라이버 블로그

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-10