DSN 및 연결 문자열 키워드 및 특성
이 페이지에는 연결 문자열과 DSN용 키워드, 그리고 SQL Server용 ODBC 드라이버에서 사용할 수 있는 SQLSetConnectAttr 및 SQLGetConnectAttr용 연결 특성을 나열합니다.
지원되는 DSN/연결 문자열 키워드 및 특성
다음 테이블에서는 각 플랫폼(L: Linux, M: Mac, W: Windows)에 이용 가능한 키워드 및 특성을 나열합니다. 키워드 또는 특성을 선택하여 자세히 살펴봅니다.
다음은 SQL Server Native Client로 연결 문자열 키워드 사용, SQLSetConnectAttr, SQLSetConnectAttr 함수에 설명되어 있지 않은 몇 가지 연결 문자열 키워드 및 연결 특성입니다.
설명
데이터 원본을 설명하는 데 사용됩니다.
SQL_COPT_SS_ANSI_OEM
ANSI에서 OEM으로의 데이터 변환을 제어합니다.
| 특성 값 | 설명 |
|---|---|
| SQL_AO_OFF | (기본값) 변환이 수행되지 않습니다. |
| SQL_AO_ON | 변환이 완료되었습니다. |
SQL_COPT_SS_AUTOBEGINTXN
버전 17.6+ 자동 커밋이 해제된 상태에서 ROLLBACK 또는 COMMIT 후 자동 BEGIN TRANSACTION을 제어합니다.
| 특성 값 | 설명 |
|---|---|
| SQL_AUTOBEGINTXN_ON | (기본값) ROLLBACK 또는 COMMIT 이후 자동 BEGIN TRANSACTION이 수행됩니다. |
| SQL_AUTOBEGINTXN_OFF | ROLLBACK 또는 COMMIT 이후 자동 BEGIN TRANSACTION이 수행되지 않습니다. |
SQL_COPT_SS_FALLBACK_CONNECT
SQL Server 대체 연결 사용을 제어합니다. 이 값은 더 이상 지원되지 않습니다.
| 특성 값 | 설명 |
|---|---|
| SQL_FB_OFF | (기본값) 대체 연결을 사용하지 않습니다. |
| SQL_FB_ON | (기본값) 대체 연결을 사용합니다. |
새로운 연결 문자열 키워드 및 연결 특성
인증 - SQL_COPT_SS_AUTHENTICATION
SQL Server에 연결할 때 사용하는 인증 모드를 설정합니다. 자세한 내용은 Microsoft Entra ID 사용을 참조하세요.
| 키워드 값 | 특성 값 | 설명 |
|---|---|---|
| SQL_AU_NONE | (기본값) 설정하지 않습니다. 다른 특성의 조합으로 인증 모드를 결정합니다. | |
| SqlPassword | SQL_AU_PASSWORD | 사용자 이름 및 암호를 사용한 SQL Server 인증 |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Microsoft Entra 통합 인증. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Microsoft Entra 암호 인증. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Microsoft Entra 대화형 인증. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Microsoft Entra 관리 ID 인증. 사용자 할당 ID의 경우 UID를 사용자 ID의 개체 ID로 설정합니다. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Microsoft Entra 서비스 주체 인증. 서비스 주체의 클라이언트 ID에 UID가 설정됩니다. PWD는 클라이언트 암호로 설정됩니다. |
| SQL_AU_RESET | 설정하지 않습니다. DSN 또는 연결 문자열 설정을 재정의합니다. |
참고 항목
Authentication 키워드 또는 특성을 사용하는 경우, 연결 문자열/DSN/연결 특성에서 원하는 값으로 Encrypt 설정을 명시적으로 지정합니다. 자세한 내용은 SQL Server Native Client에서 연결 문자열 키워드 사용을 참조하세요.
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
투명한 열 암호화(Always Encrypted)를 제어합니다. 자세한 내용은 Always Encrypted 사용(ODBC)을 참조하세요.
| 키워드 값 | 특성 값 | 설명 |
|---|---|---|
| 사용 | SQL_CE_ENABLED | Always Encrypted를 사용하도록 설정합니다. |
| 사용 안 함 | SQL_CE_DISABLED | (기본값) Always Encrypted를 사용하지 않도록 설정합니다. |
| SQL_CE_RESULTSETONLY | 암호 해독만 사용하도록 설정합니다(결과 및 반환 값). |
암호화
연결이 네트워크를 통해 TLS 암호화를 사용하는지 여부를 지정합니다. 가능한 값은 yes, /, mandatory(18.0+), no/optional(18.0+), strict(18.0+)입니다. 기본값은 버전 18.0 이상에서는 yes이고 이전 버전에서는 no입니다.
Encrypt에 대한 설정과 관계없이 서버 로그인 자격 증명(사용자 이름 및 암호)은 상시 암호화됩니다.
Encrypt, TrustServerCertificate와 서버 쪽 Force Encryption 설정은 네트워크를 통해 연결이 암호화되는지 여부에 영향을 줍니다. 다음 표에는 이러한 설정의 효과를 보여 줍니다.
ODBC 드라이버 18 이상
| 설정 암호화 | 서버 인증서 신뢰 | 서버 강제 암호화 | 결과 |
|---|---|---|---|
| 아니요 | 아니요 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터는 암호화되지 않습니다. |
| 예 | 예 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터는 암호화되지 않습니다. |
| 예 | 아니요 | 아니요 | 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 아니요 | 아니요 | 예 | 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 예 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 아니요 | 예 | 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 예 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 엄격 | - | - | TrustServerCertificate는 무시됩니다. 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
참고 항목
Strict는 TDS 8.0 연결을 지원하는 서버에서만 사용할 수 있습니다.
ODBC 드라이버 17 이하
| 설정 암호화 | 서버 인증서 신뢰 | 서버 강제 암호화 | 결과 |
|---|---|---|---|
| 아니요 | 아니요 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터는 암호화되지 않습니다. |
| 예 | 예 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터는 암호화되지 않습니다. |
| 예 | 아니요 | 아니요 | 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 아니요 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 아니요 | 아니요 | 예 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 예 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 아니요 | 예 | 서버 인증서가 확인됩니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
| 예 | 예 | 예 | 서버 인증서가 확인되지 않습니다. 클라이언트와 서버 간에 전송된 데이터가 암호화됩니다. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
MultiSubnetFailover와 상호 작용하여 더 빠르게 재연결을 시도할 수 있는 투명 네트워크 IP 확인 기능을 제어합니다. 자세한 내용은 투명 네트워크 IP 확인 사용을 참조하세요.
| 키워드 값 | 특성 값 | 설명 |
|---|---|---|
| 사용 | SQL_IS_ON | (기본값) 투명 네트워크 IP 확인을 사용하도록 설정합니다. |
| 사용 안 함 | SQL_IS_OFF | 투명 네트워크 IP 확인을 사용하지 않도록 설정합니다. |
UseFMTONLY
SQL Server 2012 이상에 연결할 때 메타데이터에 대한 SET FMTONLY 사용을 제어합니다.
| 키워드 값 | 설명 |
|---|---|
| 아니요 | (기본값) 사용 가능한 경우 메타데이터에 sp_describe_first_result_set를 사용합니다. |
| 예 | 메타데이터에 SET FMTONLY를 사용합니다. |
복제
ODBC 드라이버 버전 17.8 이상에서 복제본 로그인 사용을 지정합니다.
| 키워드 값 | 설명 |
|---|---|
| 아니요 | (기본값) 복제 로그인은 사용되지 않습니다. |
| 예 | NOT FOR REPLICATION 옵션이 있는 트리거가 연결 시 실행되지 않습니다. |
RetryExec
구성 가능한 재시도 논리는 버전 18.1부터 사용할 수 있습니다. 구성 가능한 조건에 따라 특정 ODBC 함수 호출을 자동으로 다시 실행합니다. 이 기능은 RetryExec 키워드와 재시도 규칙 목록을 사용하여 연결 문자열을 통해 사용할 수 있습니다. 각 재시도 규칙에는 오류 일치, 재시도 정책 및 쿼리 일치, 이상 세 가지의 콜론으로 구분된 구성 요소가 있습니다.
쿼리 일치는 지정된 실행에 사용되는 재시도 규칙을 결정하고, 들어오는 명령 텍스트(SQLExecDirect) 또는 문 개체(SQLExecute)의 준비된 명령 텍스트와 일치합니다. 둘 이상의 규칙이 일치하는 경우 목록에서 일치하는 첫 번째 규칙이 사용됩니다. 이 동작을 통해 일반성이 높은 순서로 규칙을 나열할 수 있습니다. 일치하는 규칙이 없으면 재시도가 이루어지지 않습니다.
실행 시 오류가 발생하고, 적용 가능한 재시도 규칙이 있는 경우 해당 오류 일치를 사용하여 실행을 재시도해야 하는지 여부를 확인합니다.
RetryExec 키워드의 값은 세미콜론으로 구분된 재시도 규칙 목록입니다.
RetryExec={rule1;rule2}
재시도 규칙은 다음과 같습니다. <errormatch>:<retrypolicy>:<querymatch>
오류 일치: 오류 코드의 쉼표로 구분된 목록입니다. 예를 들어 1000,2000을 지정하면 재시도하려는 오류 코드가 됩니다.
재시도 정책: 다음 재시도까지의 지연을 지정합니다. 첫 번째 매개 변수는 재시도 횟수이고 두 번째 매개 변수는 지연입니다. 예를 들어 3,10+7은 10에서 시작하는 3번의 시도이고, 다음 재시도는 각각 7초씩 증가합니다. +7을 지정하지 않으면 다음 재시도는 두 배가 됩니다.
쿼리 일치: 일치시킬 쿼리를 지정합니다. 아무 것도 지정하지 않으면 모든 쿼리에 적용됩니다. SELECT를 지정하면 select로 시작하는 모든 쿼리에 대해 의미가 있습니다.
위의 세 개의 구성 요소를 모두 결합하여 연결 문자열에 사용할 수 있습니다.
RetryExec={1000,2000:3,10+7:SELECT}
이는 다음과 같습니다. “SELECT로 시작하는 쿼리에서 오류 1000 및 2000의 경우. 최초 10초 지연 후 다음 시도마다 7초를 추가하여 2회 재시도합니다.”
예제
40501,40540:4,5
오류 40501 및 40540의 경우 5초의 최초 지연으로 최대 4회 재시도하고, 다음 시도마다 재시도 사이에 지수가 두 배로 증가합니다. 이 규칙은 모든 쿼리에 적용됩니다.
49919:2,10+:CREATE
CREATE로 시작하는 쿼리의 오류 49919의 경우 10초 후와 20초 후, 최대 2회 재시도합니다.
49918,40501,10928:5,10+5:SELECT c1
SELECT c1로 시작하는 쿼리의 49918, 40501 및 10928 오류의 경우 최대 5회 재시도하고 첫 번째 재시도에서 10초를 기다린 이후에는 대기 시간이 5초씩 증가합니다.
위의 3개 규칙은 다음과 같이 연결 문자열에서 함께 지정할 수 있습니다.
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
가장 일반적인(모든 일치) 규칙이 마지막에 배치되어 해당 쿼리와 일치하기 전에 두 개의 특정 규칙을 허용합니다.
ClientCertificate
인증에 사용할 사용자 인증서를 지정합니다. 옵션은 다음과 같습니다.
| 옵션 값 | 설명 |
|---|---|
sha1:<hash_value> |
ODBC 드라이버는 SHA1 해시를 사용하여 Windows 인증서 저장소에서 인증서를 찾습니다 |
subject:<subject> |
ODBC 드라이버는 제목을 사용하여 Windows 인증서 저장소에서 인증서를 찾습니다. |
file:<file_location>[,password:<password>] |
ODBC 드라이버에서 인증서 파일을 사용합니다. |
인증서가 PFX 형식이고 PFX 인증서 내의 프라이빗 키가 암호로 보호되는 경우 암호 키워드가 필요합니다. PEM 및 DER 형식의 인증서에는 ClientKey 특성이 필요합니다
ClientKey
ClientCertificate 속성으로 지정된 PEM 또는 DER 인증서에 대한 프라이빗 키의 파일 위치를 지정합니다. 형식:
| 옵션 값 | 설명 |
|---|---|
file:<file_location>[,password:<password>] |
프라이빗 키 파일의 위치를 지정합니다. |
프라이빗 키 파일이 암호로 보호되는 경우 암호 키워드(keyword)가 필요합니다. 비밀번호에 , 문자가 포함된 경우 각 문자 바로 후에 또 다른 , 문자가 추가됩니다. 예를 들어 비밀번호가 a,b,c인 경우 연결 문자열에 있는 이스케이프된 비밀번호는 a,,b,,c입니다.
HostnameInCertificate
Addr/Address/Server에서 파생된 기본값과 다른 경우 암호화 가 협상될 때 서버 인증서에 예상되는 호스트 이름을 지정합니다. ServerCertificate 옵션을 사용하면 HostnameInCertificate 옵션이 무시됩니다.
IpAddressPreference
버전 18.1부터 사용할 수 있는 이 옵션을 사용하면 사용자가 연결에 우선 순위를 지정할 IP 주소 유형을 지정할 수 있습니다. 가능한 옵션은 "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]"입니다. UsePlatformDefault는 시스템 호출에서 제공하는 순서대로 주소에 연결하여 서버 이름을 확인합니다. 기본값은 이전 버전의 동작에 해당하는 IPv4First입니다.
ServerCertificate
버전 18.1부터 사용할 수 있는 이 옵션은 엄격한 암호화 모드에서 사용할 수 있습니다. ServerCertificate 키워드는 SQL Server TLS/SSL 인증서와 일치하는 인증서 파일의 경로를 지정하는 데 사용됩니다. 해당 일치는 표준 인증서 유효성 검사(만료, 호스트 이름, 신뢰 체인 등) 대신 수행됩니다. 허용되는 인증서 형식은 PEM, DER, CER입니다. 지정된 경우 제공된 ServerCertificate이 정확히 일치하는지 확인하여 SQL Server 인증서가 확인됩니다.
SQL_COPT_SS_ACCESS_TOKEN
인증에 Microsoft Entra 액세스 토큰을 사용할 수 있습니다. 자세한 내용은 Microsoft Entra ID 사용을 참조하세요.
| 특성 값 | 설명 |
|---|---|
| NULL | (기본값) 액세스 토큰이 제공되지 않습니다. |
| ACCESSTOKEN* | 액세스 토큰에 대한 포인터입니다. |
SQL_COPT_SS_CEKEYSTOREDATA
로드된 키 저장소 공급자 라이브러리와 통신합니다. 투명 열 암호화(Always Encrypted) 제어를 참조하세요. 이 특성에는 기본값이 없습니다. 자세한 내용은 사용자 지정 키 저장소 공급자를 참조하세요.
| 특성 값 | 설명 |
|---|---|
| CEKEYSTOREDATA * | 키 저장소 공급자 라이브러리에 대한 통신 데이터 구조 |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Always Encrypted에 대한 키 저장소 공급자 라이브러리를 로드하거나 로드된 키 저장소 공급자 라이브러리의 이름을 검색합니다. 자세한 내용은 사용자 지정 키 저장소 공급자를 참조하세요. 이 특성에는 기본값이 없습니다.
| 특성 값 | 설명 |
|---|---|
| char * | 키 저장소 공급자 라이브러리의 경로 |
SQL_COPT_SS_ENLIST_IN_XA
XA 준수 TP(트랜잭션 프로세서)를 사용하여 XA 트랜잭션을 사용하도록 설정하려면, 응용 프로그램에서는 SQL_COPT_SS_ENLIST_IN_XA 및 XACALLPARAM 개체에 대한 포인터를 사용하여 SQLSetConnectAttr을 호출해야 합니다. 이 옵션은 Windows(17.3 이상), Linux, macOS에서 지원됩니다.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
XA 트랜잭션을 ODBC 연결에만 연결하려면 SQLSetConnectAttr 호출 시 포인터 대신 SQL_COPT_SS_ENLIST_IN_XA에 TRUE 또는 FALSE를 제공합니다. 이 설정은 Windows에서만 유효하며 클라이언트 애플리케이션을 통해 XA 작업을 지정하는 데 사용할 수 없습니다.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| 값 | 설명 | 플랫폼 |
|---|---|---|
| XACALLPARAM 개체* | XACALLPARAM 개체에 대한 포인터입니다. |
Windows, Linux, macOS |
| TRUE | XA 트랜잭션을 ODBC 연결과 연결합니다. 관련된 모든 데이터베이스 작업은 XA 트랜잭션의 보호 아래 수행됩니다. | Windows |
| FALSE | ODBC 연결과 트랜잭션의 연결을 해제합니다. | Windows |
XA 트랜잭션에 대한 자세한 내용은 XA 트랜잭션 사용을 참조하세요.
SQL_COPT_SS_LONGASMAX
긴 형식 데이터를 최대 형식 데이터로 서버에 보낼 수 있습니다.
| 특성 값 | 설명 |
|---|---|
| 아니요 | (기본값) 전송 시 긴 형식을 최대 형식으로 변환하지 마세요. |
| 예 | 전송 시 데이터를 긴 형식에서 최대 형식으로 변환합니다. |
SQL_COPT_SS_SPID
연결의 서버 프로세스 ID를 검색합니다. 이 속성은 서버로 왕복이 추가로 발생하지 않는다는 점을 제외하고는 T-SQL @@SPID 변수와 같습니다.
| 특성 값 | 설명 |
|---|---|
| DWORD | SPID |