이 글은 Linux 또는 macOS용 Microsoft SQL Server ODBC 드라이버를 사용하는 애플리케이션의 프로그래밍 고려사항을 설명합니다. 일부 링크는 SQL Server Native Client 자료를 가리킵니다. 그 페이지들은 과거 API 맥락을 제공합니다.
드라이버 버전 선택
새로운 개발을 위해서는 현재 드라이버 라인인 SQL Server용 Microsoft ODBC Driver 18을 사용하세요. Microsoft ODBC Driver 17 for SQL Server는 지원 수명주기에 설명된 대로 이미 이를 배포하고 있는 애플리케이션에 대해서도 계속 지원됩니다. SQL Server 2017과 함께 제공된 ODBC 드라이버 13은 2027년 10월 12일까지 연장 지원 자격이 있으며, 이는 연장 지원 계약에 의해서만 가능합니다.
연결 문자열에 설치된 드라이버 이름을 지정하고, 괄호로 감싸세요:
Driver={ODBC Driver 18 for SQL Server}
Driver={ODBC Driver 17 for SQL Server}
odbc.ini의 데이터 소스 이름(DSN)에서는 예를 들어 Driver = ODBC Driver 18 for SQL Server처럼 중괄호 없이 이름을 사용하세요. DSN 문법에 대해서는 연결 문자열 키워드 및 데이터 소스 이름(DSN들)을 참조하세요.
버전별 연결 설정에 대해서는 주요 버전 차이를 참조하세요. 지원 날짜와 운영체제 호환성에 대해서는 지원 수명주기 및 시스템 요구사항을 참조하세요.
애플리케이션 빌드
헤더 위치를 포함해 순서, 컴파일러 명령어, 라이브러리 이름 및 C++ 샘플에 대해서는 ODBC 드라이버로 C 및 C++ 애플리케이션 개발, C++ 및 ODBC로 연결 및 쿼리를 참조하세요.
ODBC 애플리케이션은 unixODBC 헤더(sqltypes.h, sqlext.h, sqlucode.h 및 msodbcsql.h) 뒤에 sql.h를 포함하여 다중 활성 결과 집합(MARS) 및 기타 SQL Server 고유 기능을 사용할 수 있습니다. SQL Server 전용 항목에는 Windows ODBC 애플리케이션에서 사용하는 것과 동일한 심볼릭 이름을 사용하세요.
드라이버 기능 확인
표준 애플리케이션 프로그래밍 인터페이스(API)를 위한 ODBC 프로그래머 참고서부터 시작하세요. 그 다음 드라이버별 동작에 대해 현재 드라이버 문서를 사용하세요.
Microsoft ODBC SQL Server용 드라이버 개요는 드라이버 문서로 연결됩니다. 다음 SQL Server 네이티브 클라이언트 관련 기사들은 Linux와 macOS에서 드라이버를 사용하는 애플리케이션에 대한 API 맥락을 제공합니다:
- SQL Server와 통신(ODBC)
- 연결 및 쿼리 시간 제한 지원
- 커서들
- 날짜/시간 개선 (ODBC)
- 쿼리 실행 (ODBC)
- 오류 및 메시지 처리
- Kerberos 인증
- 큰 공통 언어 런타임(CLR) 사용자 정의 형식(ODBC)
- 트랜잭션 수행 (ODBC). 리눅스와 macOS에서 분산 트랜잭션을 할 때는 DTC와 함께 XA 트랜잭션을 사용하세요.
- 처리 결과 (ODBC)
- 저장 프로시저 실행
- 희소 열 지원 (ODBC)
- 검증 없이 암호화 사용
- 테이블 값 매개 변수
- 명령어 및 데이터 API를 위한 UTF-8 및 UTF-16
- 카탈로그 함수 사용
Limitations
다음 기능들은 리눅스와 macOS의 ODBC 드라이버에서 제대로 작동하는지 검증되지 않았습니다:
- 장애 조치 클러스터 연결.
- ODBC 드라이버 17 이전의 투명 네트워크 IP 확인.
- Linux 및 macOS ODBC 드라이버 기본 제공 진단(BID) 추적 ODBC 드라이버 17.3 이전.
지원되지 않는 기능
다음 기능들은 리눅스와 macOS의 ODBC 드라이버에는 제공되지 않습니다:
SQL_ATTR_ENLIST_IN_DTC특성을 통해 분산 트랜잭션을 처리합니다. 이 드라이버는 Microsoft Distributed Transaction Coordinator(DTC)를 통해 XA 트랜잭션을 지원합니다. 자세한 내용은 DTC와 함께 XA 트랜잭션 사용을(를) 참조하세요.데이터베이스 미러링.
FILESTREAM.
SQLSetConnectAttr에서 논의된 ODBC 드라이버 성능 프로파일링 및 다음과 같은 성능 관련 연결 속성:
SQL_COPT_SS_PERF_DATASQL_COPT_SS_PERF_DATA_LOGSQL_COPT_SS_PERF_DATA_LOG_NOWSQL_COPT_SS_PERF_QUERYSQL_COPT_SS_PERF_QUERY_INTERVALSQL_COPT_SS_PERF_QUERY_LOG
SQLBrowseConnect버전 17.2 이전.예를 들어 와 같은 C 구간 유형은
SQL_C_INTERVAL_YEAR_TO_MONTH에 문서화되어 있습니다.SQL_CUR_USE_ODBC의SQL_ATTR_ODBC_CURSORS속성의SQLSetConnectAttr값입니다.
문자 데이터 처리
리눅스와 macOS에서는 네이티브 SQLWCHAR 타입 대신 ODBC 와이드 문자 API가 적용된 UTF-16 wchar_t 버퍼를 사용하세요. 드라이버 인터페이스는 16비트 코드 단위를 사용합니다.
문자 인코딩
ODBC 드라이버 13 및 13.1의 경우 SQLCHAR 데이터에 UTF-8을 사용해야 합니다. 이 버전들은 다른 인코딩을 지원하지 않습니다.
ODBC 드라이버 17부터 지원되는 SQLCHAR 데이터에 대한 문자 집합과 인코딩에는 다음이 포함됩니다:
참고
musl와 iconv 간의 차이로 인해 glibc 많은 지역이 Alpine Linux에서 지원되지 않습니다. 자세한 내용은 glibc와의 기능적 차이를 참조하세요.
| 이름 | 설명 |
|---|---|
| UTF-8 | Unicode |
| CP437 | MS-DOS 라틴어 US |
| CP850 | MS-DOS 라틴어 1 |
| CP874 | 라틴어/태국어 |
| CP932 | 일본어 (Windows 코드 페이지 932) |
| CP936 | 중국어(간체), GBK |
| CP949 | 한국어 (Windows 코드 페이지 949) |
| CP950 | 중국어(번체), Big5 |
| CP1250 | 중부 유럽 |
| CP1251 | 키릴 문자 |
| CP1252 | 서유럽 |
| CP1253 | 그리스어 |
| CP1254 | 터키어 |
| CP1255 | 히브리어 |
| CP1256 | 아랍어 |
| CP1257 | 발트 |
| CP1258 | 베트남어 |
| ISO-8859-1 | 라틴어-1 |
| ISO-8859-2 | 라틴어-2 |
| ISO-8859-3 | 라틴어-3 |
| ISO-8859-4 | 라틴어-4 |
| ISO-8859-5 | 라틴/키릴 문자 |
| ISO-8859-6 | 라틴어/아랍어 |
| ISO-8859-7 | 라틴/그리스 문자 |
| ISO-8859-8 | 히브리어 |
| ISO-8859-9 | 터키어 |
| ISO-8859-13 | 라틴어-7 |
| ISO-8859-15 | 라틴어-9 |
연결하면 드라이버가 로드된 프로세스의 현재 로캘을 감지합니다. 로캘이 나열된 인코딩 중 하나를 사용하면 드라이버는 SQLCHAR (좁은 문자) 데이터에 대해 해당 인코딩을 사용합니다. 그렇지 않으면 기본값은 UTF-8입니다. 프로세스는 기본적으로 C 로캘에서 시작되므로, 드라이버는 UTF-8을 기본값으로 사용합니다. 애플리케이션이 나열된 인코딩 중 하나가 필요하다면, 연결하기 전에 먼저 setlocale를 호출하세요. 로캘을 명시적으로 지정하거나, 빈 문자열(예: setlocale(LC_ALL, ""))을 사용해 환경의 로캘 설정을 사용할 수 있습니다.
일반적인 리눅스나 macOS 환경에서는 인코딩이 UTF-8이기 때문에, ODBC 드라이버 17 사용자들이 13 또는 13.1에서 업그레이드해도 차이를 느끼지 못할 것입니다.
setlocale를 통해 나열된 비-UTF-8 인코딩을 사용하는 애플리케이션은 UTF-8 대신 드라이버와 주고받는 데이터에 해당 인코딩을 사용해야 합니다.
SQLWCHAR 데이터는 반드시 UTF-16LE(리틀 엔디언)를 사용해야 합니다.
입력 매개변수 SQLBindParameter를 바인딩할 때, SQL_VARCHAR와 같은 좁은 문자 SQL 타입을 지정하면 드라이버는 제공된 데이터를 클라이언트 인코딩에서 해당 매개변수의 서버 측 인코딩으로 변환합니다. 인코딩은 콜레이션에 따라 다릅니다; 항상 코드 페이지 1252만 있는 것은 아닙니다. 출력 매개 변수의 경우 드라이버는 데이터 정렬 정보에 지정된 인코딩을 데이터와 관련된 클라이언트 인코딩으로 변환합니다. 원본 인코딩에서 대상 인코딩으로 표현할 수 없는 문자는 물음표(?)로 변환됩니다.
입력 매개변수를 결합할 때 이러한 데이터 손실을 피하기 위해 SQL_WVARCHAR와 같은 유니코드 SQL 문자 형식을 지정하세요. 드라이버는 클라이언트 인코딩을 UTF-16으로 변환하여 모든 유니코드 문자를 표현할 수 있습니다. 대상 열이나 매개변수는 유니코드 타입(nchar, nvarchar, ntext)이거나, 모든 원본 소스 데이터를 표현할 수 있는 콜레이션 또는 인코딩이 포함된 타입이어야 합니다. 출력 매개변수는 유니코드 SQL 타입과, 이 경우 드라이버가 데이터를 UTF-16으로 반환하게 되는 유니코드 C 타입(SQL_C_WCHAR) 또는 소스 데이터를 표현할 수 있는 클라이언트 인코딩이 포함된 좁은 C 타입을 지정하세요. UTF-8은 항상 이 데이터를 표현할 수 있습니다.
콜레이션과 인코딩에 대한 자세한 내용은 콜레이션 및 유니코드 지원을 참조하세요.
Windows와 Linux 또는 macOS iconv 버전 간에는 변환 차이가 있습니다:
- 코드 페이지 1255의 경우, 바이트
0xCA는 Windows에서는 UTF-16 코드 포인트0x00CA로, macOS 및 Linux에서는0x05BA버전 1.15 이전에서libiconv로 변환됩니다. - Linux
BIG5-2003라이브러리 중 2003년 Big5/CP950 개정판(iconv)이 없는 것은 그 개정판에서 추가된 문자를 올바르게 변환하지 않습니다. - 코드 페이지 932(일본어, Shift-JIS)의 경우 인코딩 표준에 정의되지 않은 문자를 디코딩하는 방식이 다릅니다. 예를 들어, Windows에서는 바이트
0x80가 U+0080으로 변환되고, Linux와 macOS에서는iconv버전에 따라 U+30FB가 될 수 있습니다.
ODBC 드라이버 13과 13.1에서는 UTF-8 멀티바이트 문자나 UTF-16 서로게이트를 SQLPutData 버퍼에 걸쳐 분할하면 데이터 손상이 발생합니다. 부분 문자 인코딩으로 끝나지 않는 스트리밍 버퍼를 사용하세요. 이 제한은 ODBC 드라이버 17에서 제거되었습니다.
문자 인코딩, 변환, 매개변수 바인딩, 버퍼 크기 조정에 관한 지침은 알려진 문제를 참조하세요.
OpenSSL
ODBC 드라이버 17.4부터 드라이버는 OpenSSL을 동적으로 로드하여, 별도의 드라이버 파일 없이도 OpenSSL 버전 1.0 또는 1.1이 설치된 시스템에서 실행될 수 있습니다. 버전 17.9부터 드라이버는 이전 버전 외에도 OpenSSL 3.0을 지원합니다. 여러 버전의 OpenSSL이 존재할 경우, 드라이버는 라이브러리 검색 경로에서 지원되는 버전을 불러오려고 시도합니다.
| 드라이버 버전 | 지원되는 OpenSSL 버전 |
|---|---|
| 17.4부터 17.8까지 | 1.0, 1.1 |
| 17.9 및 이후 17.x 버전, 그리고 모든 드라이버 18 버전 | 1.0, 1.1, 3.0 |
OpenSSL 4는 지원되지 않습니다. macOS에서는 OpenSSL 4를 가리키는 홈브류 openssl 링크가 OpenSSL 3가 설치되어 있어도 드라이버가 OpenSSL을 로드하지 못하게 할 수 있습니다. 라이브러리 경로와 설치된 버전도 확인해 보세요.
참고
드라이버를 사용하는 애플리케이션이나 그 구성 요소 중 하나가 다른 버전의 OpenSSL과 연결되거나 동적으로 로드할 경우 잠재적 충돌이 발생할 수 있습니다. 시스템에 여러 버전의 OpenSSL이 존재하고 애플리케이션이 이를 사용한다면, 애플리케이션과 드라이버에서 로드되는 버전이 일치하지 않는 일이 없도록 하세요. 오류가 메모리 손상을 초래할 수 있고, 명확하거나 일관된 방식으로 나타나지 않을 수도 있습니다.
알파인 리눅스
실행 파일이 더 큰 기본값을 요청하지 않는 한 새 스레드의 musl 기본 스택 크기는 128KB입니다. 스레드는 드라이버를 호출할 때 이 한계를 초과할 수 있습니다. Alpine Linux에서 -Wl,-z,stack-size=<size_in_bytes>으로 ODBC 애플리케이션을 링크하여 더 큰 기본 스레드 스택을 요청하세요. 명시적인 스택 크기를 가진 스레드를 생성하는 애플리케이션은 해당 스레드에 적합한 크기를 또한 선택해야 합니다.
메인 스레드의 스택과 새 스레드의 기본 스택은 같은 설정이 아닙니다.
glibc 시스템에서 새 스레드의 기본값은 보통 프로세스의 스택 자원 한도를 따르며, 해당 제한이 무제한일 경우 아키텍처별 대체값이 적용됩니다. 리눅스 시스템 전반에 고정된 2MB 기본 사양을 가정하지 마세요.
추가적인 참고 사항
ODBC 애플리케이션에서 전용 관리자 연결(DAC)을 만들려면, 연결 문자열에 Server=tcp:<server>,<dac_port>를 설정하세요. 인스턴스의 일반 연결 포트가 아니라 발견된 DAC 포트를 사용하세요. 예를 들어, DAC 포트가 33000이면 Server=tcp:<server>,33000로 설정하세요. 이 연결 문자열 조각들은 인증이 아닌 엔드포인트만 지정합니다. 인증과 서버 인증서 검증을 별도로 설정하세요.
로그인은 sysadmin 서버 역할의 멤버여야 합니다. 원격 접속을 하려면 서버의 원격 관리자 연결 옵션이 활성화되어 있어야 합니다. 접근 요구사항, 서버 구성 및 명령줄 관리 절차에 대해서는 데이터베이스 관리자용 진단 연결을 참조하세요. 포트 발견에 대해서는 DAC 포트를 참조하세요.
unixODBC 드라이버 관리자는 Windows 드라이버 관리자와 동일한 방식으로 전달 SQLSetConnectAttr 된 문 속성을 처리합니다. ODBC 2.x 문 옵션(예: SQL_ATTR_QUERY_TIMEOUT 및 SQL_ATTR_MAX_ROWS)은 연결의 기존 문과 새 문에 적용됩니다. ODBC 3.x 문장 전용 속성(예: SQL_ATTR_ROW_ARRAY_SIZE 및 SQL_ATTR_PARAMSET_SIZE)은 SQLSTATE HY092를 반환합니다. 연결 및 문 수준 모두에서 정의된 속성(예: SQL_ATTR_METADATA_ID)은 두 수준 중 어느 쪽에서나 설정할 수 있습니다. 연결 수준에서 문장 전용 속성을 설정하는 것은 ODBC 3.x에서 사용 중단되었으므로, 대신 SQLSetStmtAttr를 호출하세요. 자세한 내용은 SQLSetConnectAttr 함수를 참조하세요.
고도로 멀티스레드가 적용되는 애플리케이션에서는 unixODBC 핸들 검증이 성능 병목 현상이 될 수 있습니다. UnixODBC를 --enable-fastvalidate 컴파일하면 성능이 향상될 수 있습니다. 하지만 이 옵션은 잘못된 핸들을 ODBC API에 전달하는 애플리케이션이 SQL_INVALID_HANDLE를 반환하는 대신 충돌하게 할 수 있습니다.
플랫폼 설치 및 구성 단계에 대해서는 다음을 참조하세요:
- Linux에 ODBC 드라이버를 설치하세요.
- macOS에 ODBC 드라이버를 설치하세요.
- unixODBC 드라이버 관리자를 설치하세요.
- 연결 문자열과 DSN을 구성하세요.
- 시스템 요구사항을 검토하세요.