프로그래밍 지침
macOS 및 Linux에서 Microsoft ODBC driver for SQL Server의 프로그래밍 기능은 SQL Server Native Client의 ODBC(SQL Server Native Client (ODBC))를 기반으로 합니다. SQL Server Native Client는 Windows 데이터 액세스 구성 요소의 ODBC를 기반으로 합니다(ODBC 프로그래머 참조).
ODBC 애플리케이션은 unixODBC 헤더(/usr/local/include/msodbcsql.h, sql.h, sqlext.h 및 sqltypes.h)를 포함시킨 후 sqlucode.h를 포함시켜 MARS(Multiple Active Result Set) 및 기타 SQL Server 특정 기능을 사용할 수 있습니다. 그런 다음 Windows ODBC 애플리케이션에서 사용되는 동일한 SQL Server 관련 항목에 동일한 기호 이름을 사용합니다.
사용 가능한 기능
ODBC(SQL Server Native Client (ODBC)(ODBC))에 대한 SQL Server Native Client 설명서의 다음 섹션은 macOS 및 Linux 기반 ODBC 드라이버를 사용하는 경우에 유효합니다.
- SQL Server와 통신(ODBC)
- 연결 및 쿼리 시간 제한 지원
- 커서
- 날짜/시간 기능 향상(ODBC)
- 쿼리 실행(ODBC)
- 오류 및 메시지 처리
- Kerberos 인증
- 큰 CLR 사용자 정의 형식(ODBC)
- 트랜잭션 수행(ODBC)(분산 트랜잭션 제외)
- 결과 처리(ODBC)
- 저장 프로시저 실행
- 스파스 열 지원(ODBC)
- 유효성 검사 없이 암호화 사용
- 테이블 반환 매개 변수
- 명령 및 데이터 API용 UTF-8 및 UTF-16
- 카탈로그 함수 사용
지원되지 않는 기능
다음 기능은 macOS 및 Linux 기반 ODBC 드라이버에서 올바르게 작동하는 것으로 확인되지 않았습니다.
- 장애 조치(failover) 클러스터 연결
- 투명한 네트워크 IP 확인(ODBC 드라이버 17 이전)
- Linux 및 macOS ODBC 드라이버 BID 추적(ODBC 드라이버 17.3 이전)
다음 기능은 macOS 및 Linux 기반 ODBC 드라이버에서 사용할 수 없습니다.
- 분산 트랜잭션(SQL_ATTR_ENLIST_IN_DTC 특성이 지원되지 않음)
- 데이터베이스 미러링
- FILESTREAM
- SQLSetConnectAttr 및 다음과 같은 성능 관련 연결 특성에 설명된 ODBC 드라이버 성능 프로파일링:
- SQL_COPT_SS_PERF_DATA
- SQL_COPT_SS_PERF_DATA_LOG
- SQL_COPT_SS_PERF_DATA_LOG_NOW
- SQL_COPT_SS_PERF_QUERY
- SQL_COPT_SS_PERF_QUERY_INTERVAL
- SQL_COPT_SS_PERF_QUERY_LOG
- SQLBrowseConnect(17.2 버전 이전)
- SQL_C_INTERVAL_YEAR_TO_MONTH와 같은 C 간격 유형(데이터 형식 식별자 및 설명자에 문서화됨)
- SQLSetConnectAttr 함수에서 SQL_ATTR_ODBC_CURSORS 특성의 SQL_CUR_USE_ODBC 값.
문자 집합 지원
ODBC 드라이버 13 및 13.1의 경우 SQLCHAR 데이터는 UTF-8이어야 합니다. 기타 인코딩은 지원되지 않습니다.
ODBC Driver 17의 경우 다음 문자 집합/인코딩 중 하나의 SQLCHAR 데이터가 지원됩니다.
| 속성 | 설명 |
|---|---|
| UTF-8 | Unicode |
| CP437 | MS-DOS 라틴어 US |
| CP850 | MS-DOS 라틴어 1 |
| CP874 | 라틴어/태국어 |
| CP932 | 일본어, Shift-JIS |
| CP936 | 중국어 간체, GBK |
| CP949 | 한국어, EUC-KR |
| CP950 | 중국어 번체, Big5 |
| CP1251 | 키릴 자모 |
| CP1253 | 그리스어 |
| CP1256 | 아랍어 |
| CP1257 | 발틱어 |
| CP1258 | 베트남어 |
| ISO-8859-1 / CP1252 | 라틴어-1 |
| ISO-8859-2 / CP1250 | 라틴어-2 |
| ISO-8859-3 | 라틴어-3 |
| ISO-8859-4 | 라틴어-4 |
| ISO-8859-5 | 라틴어/키릴 자모 |
| ISO-8859-6 | 라틴어/아랍어 |
| ISO-8859-7 | 라틴어/그리스 문자 |
| ISO-8859-8 / CP1255 | 히브리어 |
| ISO-8859-9 / CP1254 | 터키어 |
| ISO-8859-13 | 라틴어-7 |
| ISO-8859-15 | 라틴어-9 |
연결 시 드라이버에서 로드된 프로세스의 현재 로캘을 검색합니다. 위의 인코딩 중 하나를 사용하는 경우 드라이버는 SQLCHAR(좁은 문자) 데이터에 해당 인코딩을 사용합니다. 그렇지 않으면 기본값은 UTF-8입니다. 모든 프로세스는 기본적으로 "C" 로케일로 시작되므로(드라이버가 기본적으로 UTF-8로 설정됨), 애플리케이션이 위의 인코딩 중 하나를 사용해야 하는 경우 연결하기 전에 setlocale 함수를 사용하여 로케일을 적절하게 설정해야 합니다. 로캘을 명시적으로 지정하거나 빈 문자열(예: setlocale(LC_ALL, ""))을 사용하여 환경의 로캘 설정을 사용할 수 있습니다.
그러므로 인코딩이 UTF-8인 일반적인 Linux 또는 macOS 환경에서 ODBC 드라이버 13 또는 13.1에서 17로 업그레이드하는 사용자의 경우 해당 차이점이 발생하지 않습니다. 그러나 setlocale()을 통해 위 목록의 UTF-8이 아닌 인코딩을 사용하는 애플리케이션은 드라이버에 대한 데이터에 UTF-8 대신 해당 인코딩을 사용해야 합니다.
SQLWCHAR 데이터는 UTF-16LE(Little Endian)이어야 합니다.
SQLBindParameter로 입력 매개 변수를 바인딩할 때 SQL_VARCHAR와 같은 좁은 문자 SQL 형식이 지정되면 드라이버는 제공된 데이터를 클라이언트 인코딩에서 기본(일반적으로 코드 페이지 1252) SQL Server 인코딩으로 변환합니다. 출력 매개 변수의 경우 드라이버는 데이터 정렬 정보에 지정된 인코딩을 데이터와 관련된 클라이언트 인코딩으로 변환합니다. 그러나 데이터 손실이 발생할 수 있습니다 --- 소스 인코딩에서 대상 인코딩으로 표현할 수 없는 문자는 물음표('?')로 변환됩니다.
입력 매개 변수를 바인딩할 때 이러한 데이터 손실을 방지하려면 SQL_NVARCHAR와 같은 유니코드 SQL 문자 유형을 지정합니다. 이 경우 드라이버는 클라이언트 인코딩을 모든 UNICODE 문자를 표현할 수 있는 UTF-16으로 변환합니다. 또한 서버의 대상 열 또는 매개 변수는 원본 소스 데이터의 모든 문자를 나타낼 수 있는 UNICODE 유형(nchar, nvarchar, ntext)이거나 데이터 정렬/인코딩이 있는 유형이어야 합니다. 출력 매개 변수에서 데이터 손실을 방지하려면 유니코드 SQL 형식 및 드라이버에서 데이터를 UTF-16으로 변환하게 하는 유니코드 C 형식(SQL_C_WCHAR) 또는 반각 C 형식을 지정하고 클라이언트 인코딩이 원본 데이터의 모든 문자를 표현할 수 있는지(이 표현은 UTF-8에서는 항상 가능) 확인합니다.
데이터 정렬 및 인코딩에 대한 자세한 내용은 데이터 정렬 및 유니코드 지원을 참조하세요.
Windows 및 Linux와 macOS의 여러 버전의 iconv 라이브러리 간에는 인코딩 변환에 약간의 차이가 있습니다. 코드 페이지 1255(히브리어)의 텍스트 데이터에는 유니코드로 변환하면 다르게 동작하는 하나의 코드 포인트(0xCA)가 있습니다. Windows의 경우 이 문자는 UTF-16 코드 포인트 0x05BA로 변환됩니다. 1.15 이전 버전 libiconv를 포함하는 macOS 및 Linux의 경우 0x00CA로 변환됩니다. Big5/CP950의 2003 개정판(BIG5-2003)을 지원하지 않는 iconv 라이브러리가 있는 Linux에서는 해당 개정판으로 추가된 문자가 올바르게 변환되지 않습니다. 코드 페이지 932(일본어, Shift-JIS)의 경우 원래 인코딩 표준에 정의되지 않은 문자를 해독한 결과도 다릅니다. 예를 들어, 0x80 바이트는 Windows에서는 U+0080으로 변환되지만 iconv 버전에 따라 Linux 및 macOS에서는 U+30FB로 변환될 수 있습니다.
ODBC 드라이버 13 및 13.1에서 UTF-8 다중 바이트 문자 또는 UTF-16 서로게이트가 SQLPutData 버퍼에 분할되면 데이터가 손상될 수 있습니다. 버퍼를 부분 문자 인코딩으로 끝나지 않는 SQLPutData 스트리밍에 사용합니다. 이 제한 사항은 ODBC 드라이버 17에서 제거되었습니다.
OpenSSL
버전 17.4부터는 드라이버가 OpenSSL을 동적으로 로드하므로, 별도의 드라이버 파일 없이 버전 1.0 또는 1.1이 설치된 시스템에서 실행할 수 있습니다. 버전 17.9부터 드라이버는 이전 버전 외에도 OpenSSL 3.0을 지원합니다. 여러 버전의 OpenSSL가 있는 경우에는 드라이버에서 최신 버전의 로드를 시도합니다.
| 드라이버 버전 | 지원되는 OpenSSL 버전 |
|---|---|
| 17.4+ | 1.0, 1.1 |
| 17.9, 18.0 이상 | 1.0, 1.1, 3.0 |
참고 항목
드라이버나 그 구성 요소 중 하나를 사용하는 애플리케이션이 서로 다른 버전의 OpenSSL를 연결하거나 동적으로 로드하는 경우 잠재적 충돌 가능성이 있습니다. 시스템에 여러 버전의 OpenSSL이 있고 애플리케이션이 이를 사용하는 경우, 오류로 인해 메모리가 손상될 수 있고 오류가 명확하거나 일관적인 방식으로 발생하지 않을 수 있으므로 애플리케이션이 로드하는 버전과 드라이버가 일치하지 않도록 각별히 주의하는 것이 좋습니다.
Alpine Linux
이 문서를 작성한 시점을 기준으로 MUSL의 기본 스택 크기는 128K이어서 기본 ODBC 드라이버 기능에 충분하지만 애플리케이션이 무얼 하느냐에 따라 이 한도를 쉽게 초과할 수도 있으며, 특히 여러 스레드에서 드라이버를 호출하는 경우가 여기에 해당합니다. 스택 크기를 늘리려면 Alpine Linux 기반 ODBC 애플리케이션을 -Wl,-z,stack-size=<VALUE IN BYTES>를 사용하여 컴파일하는 것이 좋습니다. 참고로 대부분 GLIBC 시스템에서 기본 스택 크기는 2MB입니다.
추가 참고 사항
SQL Server 인증 및 호스트 포트를 사용하여 DAC(관리자 전용 연결)를 만들 수 있습니다. Sysadmin 역할의 구성원은 먼저 DAC 포트를 검색해야 합니다. 방법을 알아보려면 데이터베이스 관리자용 진단 연결을 참조하세요. 예를 들어, DAC 포트가 33000인 경우
sqlcmd를 사용하여 다음과 같이 연결할 수 있습니다.sqlcmd -U <user> -P <pwd> -S <host>,33000참고 항목
DAC 연결은 반드시 SQL Server 인증을 사용해야 합니다.
UnixODBC 드라이버 관리자는 SQLSetConnectAttr을 통해 전달될 때 모든 문 특성에 대해 "잘못된 특성/옵션 식별자"를 반환합니다. Windows에서 SQLSetConnectAttr이 문 특성 값을 받으면 드라이버가 연결 핸들의 하위에 해당하는 모든 활성 문에 해당 값을 설정하도록 합니다.
멀티스레드가 많은 애플리케이션에서 드라이버를 사용하는 경우, unixODBC의 핸들 유효성 검사에서 성능 병목 현상이 발생할 수 있습니다. 이러한 시나리오에서는
--enable-fastvalidate옵션을 사용하여 unixODBC를 컴파일하면 더 높은 성능을 얻을 수 있습니다. 그러나 이 옵션을 사용하면 잘못된 핸들을 ODBC API에 전달하는 애플리케이션이SQL_INVALID_HANDLE오류를 반환하는 대신 충돌을 일으킬 수 있으므로 주의해야 합니다.