연결 속성 설정

JDBC 드라이버 다운로드

연결 문자열 속성은 다음과 같은 다양한 방법으로 지정할 수 있습니다.

  • DriverManager 클래스를 사용하여 연결할 때 연결 URL의 name=value 속성으로 지정합니다. 연결 문자열 구문은 연결 URL 빌드를 참조하세요.

  • DriverManager 클래스의 Connect 메서드속성 매개 변수에 name=value 속성으로 지정합니다.

  • 드라이버 데이터 원본의 해당 setter 메서드에서 값으로 지정합니다. 예시:

    datasource.setServerName(value)
    datasource.setDatabaseName(value)
    

설명

속성 이름은 대/소문자를 구분하지 않으며 중되는복 속성 이름은 다음 순서로 확인됩니다.

  1. API 인수(예: 사용자 및 비밀번호)
  2. 속성 컬렉션
  3. 연결 문자열의 마지막 인스턴스

속성 이름에 알 수 없는 값이 허용되며 JDBC 드라이버는 대/소문자 유효성을 검사하지 않습니다.

중복되는 속성 이름과 마찬가지로 동의어도 허용되며 순서대로 확인됩니다.

속성

다음 표에서는 JDBC 드라이버에 현재 사용할 수 있는 모든 연결 문자열 속성을 나열합니다.

속성
Type
기본값
설명
accessToken

문자열

null
(버전 6.0 이상) 액세스 토큰을 사용하여 데이터베이스에 연결하려면 이 속성을 사용합니다. accessToken은 연결 URL을 사용하여 설정할 수 없습니다.
accessTokenCallbackClass

문자열

null
(버전 12.4 이상) 액세스 토큰 콜백과 함께 사용할 콜백 구현 클래스의 이름입니다.
applicationIntent

문자열

ReadWrite
(버전 6.0 이상) 서버에 연결할 애플리케이션 워크로드 유형을 선언합니다.

가능한 값은 ReadOnlyReadWrite입니다.

재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.
applicationName

문자열
[<=128개 문자]

null
응용 프로그램 이름, 또는 이름이 제공되지 않은 경우 "Microsoft JDBC Driver for SQL Server"입니다.

다양한 SQL Server 프로파일링 및 로깅 도구에서 특정 애플리케이션을 식별하는 데 사용합니다.
authentication

문자열

NotSpecified
(버전 6.0 이상) 이 선택적 속성은 연결에 사용할 인증 방법을 나타냅니다. 가능한 값은 ActiveDirectoryIntegrated, ActiveDirectoryPassword, ActiveDirectoryManagedIdentity(버전 12.2 이상), ActiveDirectoryMSI(버전 7.2 이상), ActiveDirectoryInteractive(버전 9.2 이상), ActiveDirectoryServicePrincipal(버전 9.2 이상), SqlPassword와 기본값 NotSpecified입니다.

Windows 통합 인증으로 SQL에 연결하려면 ActiveDirectoryIntegrated(버전 6.0 이상)를 사용합니다.

Microsoft Entra 보안 주체 이름과 비밀번호를 사용해 SQL에 연결하려면 ActiveDirectoryPassword(버전 6.0 이상)를 사용합니다.

Azure 리소스 내에서 SQL에 연결하려면 ActiveDirectoryManagedIdentity(버전 12.2 이상) 또는 ActiveDirectoryMSI(버전 7.2 이상)를 사용합니다. 예를 들어 Azure 가상 머신, App Service 또는 함수 앱에서 관리 ID 인증을 사용합니다.

ActiveDirectoryManagedIdentity 또는 ActiveDirectoryMSI 인증 모드를 사용할 때 드라이버에서 지원하는 두 가지 유형의 관리 ID는 다음과 같습니다.
1. 시스템이 할당한 관리 ID: 기본적으로 accessToken을 가져오는 데 사용됩니다.
2. 사용자가 할당한 관리 ID: 관리 ID의 클라이언트 ID가 msiClientId 연결 속성으로 지정된 경우 accessToken을 가져오는 데 사용됩니다.

대화형 인증 흐름을 사용하여 데이터베이스에 연결하려면 ActiveDirectoryInteractive를 사용합니다.

서비스 주체 ID의 클라이언트 ID 및 비밀을 사용하여 데이터베이스에 연결하려면 ActiveDirectoryServicePrincipal(버전 9.2 이상)을 사용합니다. userName 속성에서 클라이언트 ID를 지정하고 암호 속성(10.2 이상)에서 비밀을 지정합니다.

사용자 이름/사용자비밀번호호 속성을 사용하여 SQL에 연결하려면 SqlPassword를 사용합니다.

이러한 인증 방법이 필요하지 않은 경우 NotSpecified를 사용합니다.

중요: 인증이 ActiveDirectoryIntegrated로 설정된 경우 mssql-jdbc_auth-<version>-<arch>.dll(JDBC 드라이버 패키지에서 사용 가능) 및 SQL Server용 Microsoft 인증 라이브러리(ADAL.DLL)라는 두 라이브러리를 설치해야 합니다. Microsoft 인증 라이브러리는 Microsoft ODBC Driver for SQL Server 또는 Microsoft OLE DB Driver for SQL Server에서 설치할 수 있습니다. JDBC 드라이버는 ADAL.DLL에 대해 버전 1.0.2028.318 이상만 지원합니다.

참고: 인증 속성이 NotSpecified 이외의 값으로 설정되어 있으면, 드라이버는 기본적으로 이전에 SSL(Secure Sockets Layer)로 알려진 TLS(전송 계층 보안) 암호화를 사용합니다.

Microsoft Entra 인증을 구성하는 방법에 대한 자세한 내용은 Microsoft Entra 인증 사용을 참조하세요.
authenticationScheme

문자열

NativeAuthentication
응용 프로그램에서 사용하려는 통합 보안의 종류를 나타냅니다. 가능한 값은 JavaKerberos, NTLM(버전 7.4 이상)과 기본값 NativeAuthentication입니다.

NativeAuthentication을 사용하면 드라이버가 Windows에서 mssql-jdbc_auth-<version>-<arch>.dll(예 mssql-jdbc_auth-8.2.2.x64.dll)을 로드하며 이는 통합 인증 정보를 가져오는 데 사용됩니다.

(로드된 기본 인증 라이브러리는 드라이버 버전 6.0~7.4를 사용할 때 이름이 sqljdbc_auth.dll로 지정됩니다.)

authenticationScheme=JavaKerberos를 사용하는 경우 serverName 또는 serverSpn 속성에서 FQDN(정규화된 도메인 이름)을 지정해야 합니다. 그렇지 않으면 오류가 발생합니다(Kerberos 데이터베이스에서 서버를 찾을 수 없음).

authenticationScheme=JavaKerberos 사용 방법에 대한 자세한 내용은 Kerberos 통합 인증을 사용하여 SQL Server에 연결을 참조하세요.

authenticationScheme=NTLM을 사용할 때는 domain 또는 domainName 속성, useruserName 속성의 Windows 자격 증명, 그리고 password 속성을 사용하여 Windows 도메인을 지정해야 합니다. 그렇지 않으면 오류가 발생합니다(연결 속성 지정이 필요함).
calcBigDecimalPrecision

부울 값
[“true” | “false”]

false
(버전 12.6 이상) 전체 자릿수에 허용되는 최댓값(38)을 사용하는 것과 달리, 드라이버가 BigDecimal 입력의 전체 자릿수를 계산해야 하는지 여부를 나타내는 플래그입니다.
cancelQueryTimeout

int

-1
(버전 6.4 이상) 이 속성을 사용하여 연결에 설정된 queryTimeout을 취소할 수 있습니다. 서버에 대한 TCP 연결이 자동으로 삭제되면 쿼리 실행이 중단되고 예외가 발생하지 않습니다. 이 속성은 연결에 'queryTimeout'도 설정된 경우에만 적용할 수 있습니다.

드라이버에서는 연결을 삭제하고 채널을 닫기 위해 cancelQueryTimeout + queryTimeout초의 총 시간을 기다립니다.

이 속성의 기본값은 -1이며 동작은 무기한 대기하는 것입니다.
clientCertificate

문자열

null
(버전 8.4 이상) 클라이언트 인증서 인증에 사용할 인증서의 위치를 지정합니다. JDBC 드라이버는 PFX, PEM, DER, CER 파일 확장을 지원합니다.

자세한 내용은 루프백 시나리오를 위한 클라이언트 인증서 인증을 참조하세요.
clientKey

문자열

null
(버전 8.4 이상) clientCertificate 특성에 지정된 PEM, DER 및 CER 인증서에 대해 프라이빗 키의 파일 위치를 지정합니다.

자세한 내용은 루프백 시나리오를 위한 클라이언트 인증서 인증을 참조하세요.
clientKeyPassword

문자열

null
(버전 8.4 이상) clientKey 파일의 프라이빗 키에 액세스하기 위한 선택적 암호 문자열을 지정합니다.

자세한 내용은 루프백 시나리오를 위한 클라이언트 인증서 인증을 참조하세요.
columnEncryptionSetting

문자열
[“사용” | “사용 안 함”]

사용 안 함
(버전 6.0 이상) AE(Always Encrypted) 기능을 사용하려면 "사용"으로 설정합니다. AE를 사용하도록 설정하면 JDBC 드라이버는 서버의 암호화된 데이터베이스 열에 저장된 중요한 데이터를 투명하게 암호화하고 암호 해독합니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.

참고: Always Encrypted는 SQL Server 2016 이상 및 Azure SQL Database에서 사용할 수 있습니다.
connectRetryCount

int
[0..255]

1
(버전 9.4 이상) 연결 오류가 있는 경우 다시 연결 시도 횟수입니다.
connectRetryInterval

int
[1..60]

10
(버전 9.4 이상) 각 연결 재시도 사이의 시간(초)입니다.
databaseName,
database

문자열
[<=128개 문자]

null
연결할 데이터베이스 이름입니다.

명시되지 않은 경우 기본 데이터베이스에 연결됩니다.
datetimeParameterType

문자열
["datetime" | "datetime2" | "datetimeoffset"]

datetime2
(버전 12.2 이상) Java 날짜/타임스탬프 매개 변수에 사용할 SQL 데이터 형식입니다.

SQL Server 2016 이상에 연결하고 레거시 "datetime" 값과 상호 작용할 때 클라이언트가 "datetime"으로 속성을 설정하면 도움이 될 수 있습니다. "datetime" 값과 "datetime2" 값 간의 서버 쪽 변환 문제가 이 설정을 통해 완화되기 때문입니다. 자세한 내용은 SQL Server 2016부터 datetime에서 datetime2로의 변환 동작 변경 처리를 참조 하세요
delayLoadingLobs

부울 값
[“true” | “false”]

true
ResultSet에서 검색되는 모든 LOB 개체를 스트리밍할지 여부를 나타내는 플래그입니다. 이 속성을 “false”로 설정하면 전체 LOB 개체가 스트리밍 없이 메모리에 로드됩니다.
domainName,
도메인

문자열
null
(버전 7.4 이상) NTLM 인증을 사용할 때 인증할 Windows 도메인입니다.
disableStatementPooling

부울 값
[“true” | “false”]

true
문 풀링을 사용해야 할지 여부를 나타내는 플래그입니다.
enablePrepareOnFirst...
PreparedStatementCall

부울 값
[“true” | “false”]

false
준비된 문의 첫 번째 실행에 sp_prepexec를 호출하여 준비된 문 핸들 만들기를 사용하도록 설정하려면 “true”로 설정합니다.

준비된 문의 첫 번째 실행을 변경하여 sp_executesql를 호출하고 문을 준비하지 않도록 하려면 "false"로 설정합니다. 두 번째 실행이 발생하면 sp_prepexec를 호출하여 준비된 문 핸들을 설정합니다.
enclaveAttestationUrl

문자열

null
(버전 8.2 이상) 이 선택적 속성은 보안 Enclave를 사용한 Always Encrypted에 사용하기 위한 증명 서비스 엔드포인트 URL을 나타냅니다.

보안 Enclave를 사용한 Always Encrypted에 대한 자세한 내용은 보안 Enclave를 사용한 Always Encrypted를 참조하세요.
enclaveAttestationProtocol

문자열

null
(버전 8.2 이상) 이 선택적 속성은 보안 Enclave를 사용한 Always Encrypted에 사용하기 위한 증명 프로토콜을 나타냅니다. 현재 이 필드에서는 만 지원됩니다(NONE은 버전 11.2 이상에서만 지원됨).

보안 Enclave를 사용한 Always Encrypted에 대한 자세한 내용은 보안 Enclave를 사용한 Always Encrypted를 참조하세요.
encrypt

문자열

null
서버에 인증서가 설치된 경우 SQL Server에서 클라이언트와 서버 간에 전송되는 모든 데이터에 TLS 암호화를 사용하도록 지정하려면 “true”로 설정합니다. 기본값은 버전 10.2 이상에서는 “true”이고 9.4 이하에서는 “false”입니다.

버전 6.0 이상에는 기본값으로 TLS 암호화를 사용하는 새 연결 설정 '인증'이 있습니다.

이 속성에 대한 자세한 내용은 ‘authentication’ 속성을 참조하세요.

버전 11.2.0 이상에서는 암호화부울에서 문자열로 변경되어 속성이 strict로 설정된 경우 TDS 8.0을 지원할 수 있습니다.
failoverPartner

문자열

null
데이터베이스 미러링 구성 시 사용되는 장애 조치(failover) 서버의 이름입니다. 이 속성은 주 서버에 대한 초기 연결 실패에 사용됩니다. 초기 연결을 설정한 후에는 이 속성이 무시됩니다. databaseName 속성과 함께 사용해야 합니다.

참고: 드라이버는 연결 문자열에서 failoverPartner 속성의 일부로 장애 조치(failover) 파트너 인스턴스의 서버 인스턴스 포트 번호를 지원하지 않습니다. 그러나 주 서버 인스턴스의 serverName, instanceName, portNumber 속성과 연결 문자열이 동일한 장애 조치(failover) 파트너 인스턴스의 failoverPartner 속성을 지정하는 것이 지원됩니다.

서버 연결 속성에서 Virtual Network 이름을 지정하는 경우 데이터베이스 미러링을 사용할 수 없습니다. 재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.
fips

부울 값
[“true” | “false”]

"false"
FIPS가 사용 설정된 JVM(Java Virtual Machine)의 경우에는 이 속성이 true여야 합니다.
fipsProvider

문자열

null
JVM에서 구성된 FIPS 공급자입니다. 예를 들어 BCFIPS 또는 SunPKCS11-NSS입니다. 버전 6.4.0에서 제거되었습니다. 자세한 내용은 GitHub 문제 460을 참조하세요.
gsscredential

org.ietf.jgss.GSSCredential

null
(버전 6.2 이상) Kerberos 제한 위임에 사용되는 사용자 자격 증명은 이 속성에 전달될 수 있습니다.

이 설정은 integratedSecuritytrue로, JavaKerberosauthenticationScheme으로 사용해야 합니다.
hostNameInCertificate

문자열

null
SQL Server TLS/SSL 인증서의 유효성을 검사하는 데 사용할 호스트 이름입니다.

hostNameInCertificate 속성이 지정되지 않았거나 Null로 설정된 경우 SQL Server용 Microsoft JDBC 드라이버에서는 연결 URL의 serverName 속성 값을 SQL Server TLS/SSL 인증서의 유효성을 검사할 호스트 이름으로 사용합니다.

참고: 이 속성은 encrypt/authentication 속성 및 trustServerCertificate 속성과 함께 사용이 가능합니다. 연결에서 TLS 암호화를 사용하고 trustServerCertificate가 "false"로 설정된 경우 이 속성은 인증서 유효성 검사에 영향을 줍니다. TLS 연결이 성공하려면 hostNameInCertificate에 전달된 값이 서버 인증서의 SAN(주체 대체 이름)에 있는 CN(일반 이름) 또는 DNS 이름과 정확히 일치해야 합니다. 암호화 지원에 대한 자세한 내용은 암호화 지원 이해를 참조하세요.
INSTANCENAME

문자열
[<=128개 문자]

null
연결할 데이터베이스 인스턴스 이름입니다. 지정하지 않으면 기본 인스턴스에 연결합니다. instanceName과 포트가 모두 지정된 경우 포트에 대한 참고 사항을 참조하세요.

서버 연결 속성에서 Virtual Network 이름을 지정하는 경우 instanceName 연결 속성을 사용할 수 없습니다. 재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.
integratedSecurity

부울 값
["true"|"false"]

false
“true”로 설정되면 Windows 운영 체제의 SQL Server에서 Windows 자격 증명을 사용한다는 뜻입니다. "true"일 경우 JDBC 드라이버는 로컬 컴퓨터 자격 증명 캐시에서 사용자가 컴퓨터 또는 네트워크에 로그인할 때 제공된 자격 증명을 검색합니다.

“true”(authenticationscheme=JavaKerberos)로 설정되면 SQL Server에서 Kerberos 자격 증명을 사용한다는 뜻합니다. Kerberos 인증에 대한 자세한 내용은 Kerberos 통합 인증을 사용하여 SQL Server에 연결을 참조하세요.

“true”(authenticationscheme=NTLM)로 설정되면 SQL Server에서 NTLM 자격 증명을 사용한다는 뜻합니다.

“false”로 설정하는 경우 사용자 이름과 암호를 입력해야 합니다.
ipaddresspreference

문자열
[<=128개 문자]

IPv4First
클라이언트 애플리케이션이 사용하는 IP 기본 설정.

IPV4First를 사용하면 드라이버가 IPv4 주소를 먼저 트래버스합니다. IPv4 주소를 성공적으로 연결할 수 없는 경우 드라이버는 계속 IPv6 주소를 시도합니다(있는 경우).

IPV6First를 사용하면 드라이버가 IPv6 주소를 먼저 트래버스합니다. IPv6 주소를 성공적으로 연결할 수 없는 경우 드라이버는 계속 IPv4 주소를 시도합니다(있는 경우).

UsePlatformDefault를 사용하면 드라이버는 DNS 확인에서 초기 순서로 모든 IP 주소를 트래버스합니다.
jaasConfigurationName

문자열

SQLJDBCDriver
(버전 6.2 이상) SQL Server에 대한 각 연결에는 Kerberos 연결을 설정하기 위한 자체 JAAS 로그인 구성 이름을 사용할 수 있습니다. 이 속성을 통해 구성 입력 이름을 전달할 수 있습니다. 이는 Kerberos 구성 파일을 만들 때 사용하기 위한 것입니다. 기본값으로 드라이버는 SQLJDBCDriver의 이름을 찾습니다.

외부 구성을 찾을 수 없는 경우 드라이버가 IBM JVM에는 useDefaultCcache = true를, 다른 JVM에는 useTicketCache = true를 설정합니다.
keyStoreAuthentication

문자열

null
(버전 6.0 이상) 이 속성은 Always Encrypted와 함께 사용할 키 저장소를 식별하고 해당 키 저장소의 인증에 사용될 인증 메커니즘을 결정합니다. 드라이버는 "keyStoreAuthentication=JavaKeyStorePassword"를 설정할 때 Java 키 저장소 설정을 원활하게 지원합니다. 이 속성을 사용하려면 Java 키 저장소에 대해 keyStoreLocationkeyStoreSecret 속성 설정도 필요합니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.

Microsoft JDBC Driver 8.4부터 관리 ID를 사용해 "keyStoreAuthentication=KeyVaultManagedIdentity" 또는 "keyStoreAuthentication=KeyVaultClientSecret"을 설정하여 Azure Key Vault에 인증할 수 있습니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.
keyStoreLocation

문자열

null
(버전 6.0 이상) keyStoreAuthentication=JavaKeyStorePassword의 경우 keyStoreLocation 속성이 Always Encrypted 데이터와 함께 사용할 열 마스터 키가 저장되는 Java 키 저장소 파일로의 경로를 식별합니다. 경로에는 키 저장소 파일 이름이 포함되어야 합니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.
keyStorePrincipalId

문자열

null
(버전 8.4 이상) keyStoreAuthentication=KeyVaultManagedIdentity인 경우 keyStorePrincipalId 속성은 유효한 Microsoft Entra 응용 프로그램 클라이언트 ID를 지정합니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.
keyStoreSecret

문자열

null
(버전 6.0 이상) keyStoreAuthentication=JavaKeyStorePassword인 경우 keyStoreSecret 속성은 키 저장소 및 키에 사용할 비밀번호를 식별합니다. Java 키 저장소를 사용하려면 키 저장소와 키 비밀번호가 동일해야 합니다.

Always Encrypted에 대한 자세한 내용은 JDBC 드라이버로 Always Encrypted 사용을 참조하세요.
lastUpdateCount

부울 값
[“true” | “false”]

true
“true” 값을 설정할 경우 서버에 전달된 SQL 문에서 마지막 업데이트 횟수만 반환되며, 이 값을 단일 SELECT, INSERT 또는 DELETE 문에서 사용하면 서버 트리거로 인한 다른 업데이트 횟수를 무시할 수 있습니다. 이 속성을 “false”로 설정하면 서버 트리거로 인해 반환된 업데이트 횟수를 포함하여 모든 업데이트 횟수가 반환됩니다.

참고: 이 속성은 executeUpdate 메서드와 함께 사용될 경우에만 적용됩니다. 다른 모든 실행 메서드는 모든 결과 및 업데이트 수를 반환합니다. 이 속성은 서버 트리거에서 반환된 업데이트 수에만 영향을 줍니다. 트리거 실행의 일부로 발생하는 결과 집합 또는 오류에는 영향을 주지 않습니다.
lockTimeout

int

-1
데이터베이스가 잠금 시간 제한을 보고하기 전에 대기할 시간(밀리초)입니다. 기본 동작은 무기한 대기하는 것입니다. 지정되어 있다면 이 값은 연결의 모든 문에서 기본값입니다.

또는, Statement.setQueryTimeout()을 사용하여 특정 문에 쿼리 시간 제한을 설정할 수 있습니다. 값은 0일 수 있으며 이 값은 대기하지 않도록 지정합니다.
loginTimeout

int
[0..65535]

30(버전 11.2 이상)
15(버전 10.2 이하)
드라이버가 연결 실패 제한 시간까지 대기해야 하는 시간(초)입니다. 값이 0이면 시간 제한이 기본 시스템 시간 제한임을 나타내는데, 버전 11.2 이상이면 기본값으로 30초이고 버전 10.2 이하이면 기본값으로 15초입니다. 0이 아닌 값은 드라이버가 연결 실패 제한 시간까지 대기해야 하는 시간(초)입니다.

Virtual Network 이름을 Server 연결 속성에 지정하는 경우 시간 제한 값을 3분 이상으로 지정하여 장애 조치(failover) 연결이 성공하도록 충분한 시간을 허용해야 합니다. 재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.
maxResultBuffer

문자열

null
(버전 9.2 이상) 결과 집합을 읽을 때 maxResultBuffer를 사용하여 읽어들일 최대 바이트를 설정할 수 있습니다. 지정하지 않으면 전체 결과 집합을 읽습니다. 크기는 다음과 같은 두 가지 스타일로 지정할 수 있습니다.
1. 바이트 크기(예: 100, 150M, 300K, 400G)
2. 최대 힙 메모리의 비율(예: 10p, 15pct, 20percent).
msiClientId

문자열

null
(사용되지 않음) (버전 7.2 이상) ActiveDirectoryManagedIdentity 또는 ActiveDirectoryMSI 인증 모드와의 연결을 설정하기 위해 accessToken을 획득하는 데 사용되는 관리 ID(MSI)의 클라이언트 ID입니다.
multiSubnetFailover

부울

false
SQL Server 가용성 그룹 또는 SQL Server 장애 조치(failover) 클러스터 인스턴스의 가용성 그룹 수신기에 연결하려면 항상 multiSubnetFailover=true를 지정합니다. multiSubnetFailover=true는 (현재) 활성 상태인 서버를 더 빠르게 감지하고 연결하도록 드라이버를 구성합니다. 가능한 값은 true와 false입니다. 재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.

getPropertyInfo, getMultiSubnetFailoversetMultiSubnetFailover를 사용하여 multiSubnetFailover 연결 속성에 프로그래밍 방식으로 액세스할 수 있습니다.

참고: SQL Server용 Microsoft JDBC Driver 6.0부터는 가용성 그룹 수신기 연결 시 multiSubnetFailover를 “true”로 설정하지 않아도 됩니다. 기본값으로 사용하도록 설정된 새 속성인 transparentNetworkIPResolution은 (현재) 활성 상태인 서버를 감지하고 연결하도록 합니다.
packetSize

int
[-1 | 0 | 512..32767]

8000
서버와 통신하는 데 사용되는 네트워크 패킷의 크기이며 바이트 단위로 나타냅니다. 값 -1은 서버의 기본 패킷 크기를 사용함을 나타내고 값 0은 최댓값인 32767을 사용함을 나타냅니다. 이 속성이 허용 범위를 벗어난 값으로 설정되면 예외가 발생합니다.

중요: 암호화가 설정된 경우(encrypt=true)에는 packetSize 속성을 사용하지 않는 것이 좋습니다. 그렇지 않으면 드라이버에서 연결 오류가 발생할 수 있습니다. 이 속성에 대한 자세한 내용은 SQLServerDataSource 클래스의 setPacketSize 메서드를 참조하세요.
password

문자열
[<=128개 문자]

null
SQL 사용자 및 비밀번호에 연결하는 경우의 데이터베이스 비밀번호입니다.
보안 주체 이름과 비밀번호를 사용하는 Kerberos 연결의 경우 이 속성은 Kerberos 보안 주체 비밀번호로 설정됩니다.

(버전 10.2 이상) authentication=ActiveDirectoryServicePrincipal인 경우 password 속성은 Active Directory 보안 주체에 사용할 암호를 식별합니다.
portNumber,
port

int
[0..65535]

1433
서버에서 수신 중인 포트입니다. 포트 번호가 연결 문자열에 지정된 경우, SQLbrowser에 대한 요청이 발생하지 않습니다. 포트와 instanceName을 모두 지정하면 지정된 포트에 연결됩니다. 그러나 instanceName의 유효성을 검사하여 포트와 일치하지 않으면 오류가 발생합니다.

중요: SQLbrowser를 사용하는 것보다 더 안전하므로 항상 포트 번호를 지정하는 것이 좋습니다.
prepareMethod

문자열

prepexec
(버전 11.2.0 이상) 준비된 문이 있는 드라이버에서 사용할 기본 prepare 메서드를 지정합니다.

prepare로 설정하여 sp_prepare를 prepare 메서드로 사용합니다. 이렇게 하면 데이터베이스가 실행 계획에서 고려할 초기 값 없이 문을 준비하기 위한 데이터베이스에 대한 별도의 초기 이동이 발생합니다. prepexec으로 설정하여 sp_prepexec를 prepare 메서드로 사용합니다. 이 메서드는 준비 작업을 첫 번째 실행과 결합하여 왕복을 줄입니다. 또한 데이터베이스가 실행 계획에서 고려할 수 있는 초기 매개 변수 값을 데이터베이스에 제공합니다.
queryTimeout

int

-1
쿼리에서의 시간 제한까지 대기하는 시간(초)입니다. 기본값은 -1이며, 무한 시간 제한을 의미합니다. 이 값이 0으로 설정되면 무기한 대기를 뜻합니다.
realm

문자열

null
(버전 9.4 이상) Kerberos 인증 영역입니다. 이 값을 설정하면 드라이버가 서버 영역에서 자동으로 검색하는 Kerberos 인증 영역이 재정의됩니다.
복제

부울 값
[“true” | “false”]

false
(버전 9.4 이상) 이 설정은 복제본에 연결이 사용되는지 여부를 서버에 알려줍니다. 사용하도록 설정하면 연결에서 NOT FOR REPLICATION 옵션이 있는 트리거가 실행되지 않습니다.
responseBuffering

문자열
[“full” | “adaptive”]

적응형
이 속성을 "adaptive"로 설정하면 필요한 경우 가능한 최소 데이터가 버퍼링됩니다. 기본 모드는 "adaptive"입니다.

이 속성이 “full”로 설정되어 있으면 문이 실행될 때 전체 결과 집합을 서버에서 읽습니다.

참고: JDBC 드라이버 버전 1.2 이후 업그레이드한 후 기본 버퍼링 동작은 “adaptive”입니다. 응용 프로그램에서 버전 1.2 기본 동작을 유지하려면 연결 속성에서 responseBufferring 속성을 “full”로 설정하거나 SQLServerStatement 개체의 setResponseBuffering 메서드를 사용해야 합니다.
selectMethod

문자열
[“direct” | “cursor”]

direct
이 속성을 "cursor"로 설정하면 TYPE_FORWARD_ONLYCONCUR_READ_ONLY 커서에 대한 연결에서 생성된 각 쿼리에 대해 데이터베이스 커서가 만들어집니다. 이 속성은 대개 애플리케이션에서 클라이언트 메모리에 완전히 집어넣을 수 없는 큰 결과 집합을 생성하는 경우에만 필요합니다. 이 속성이 “cursor”로 설정되어 있으면 클라이언트 메모리에 제한된 수의 결과 집합 행만 유지됩니다.

기본 동작은 모든 결과 집합 행을 클라이언트 메모리에 유지하는 것입니다. 이 동작은 애플리케이션에서 모든 행을 처리하는 경우에 성능 면에서 가장 효과적입니다.
sendStringParameters...
AsUnicode

부울 값
[“true” | “false”]

true
sendStringParametersAsUnicode 속성을 “true”로 설정하면 문자열 매개 변수가 유니코드 형식으로 서버에 전송됩니다.

sendStringParametersAsUnicode 속성을 "false"로 설정하면 문자열 매개 변수가 유니코드 대신 ASCII/MBCS 등 유니코드가 아닌 형식으로 서버에 전송됩니다.

sendStringParametersAsUnicode 속성의 기본값은 "true"입니다.

참고:sendStringParametersAsUnicode 속성은 매개 변수 값을 CHAR, VARCHAR 또는 LONGVARCHAR JDBC 형식으로 보내기 위해서만 선택됩니다. SQLServerPreparedStatementSQLServerCallableStatement 클래스의 setNString, setNCharacterStream, setNClob 메서드와 같은 새 JDBC 4.0 국가별 문자 메서드는 이 속성의 설정에 관계없이 항상 매개 변수 값을 유니코드로 서버에 보냅니다.

CHAR, VARCHARLONGVARCHAR JDBC 데이터 형식을 사용할 때 성능을 최적화하려면 애플리케이션에서 sendStringParametersAsUnicode 속성을 "false"로 설정하고 SQLServerPreparedStatementSQLServerCallableStatement 클래스의 국가별 문자 메서드가 아닌 setString, setCharacterStream 및 setClob를 사용해야 합니다.

응용 프로그램에서 sendStringParametersAsUnicode 속성을 "false"로 설정하고 국가 이외의 문자 메서드를 사용하여 서버 쪽의 유니코드 데이터 형식(예: nchar, nvarcharntext)에 액세스하는 경우, 데이터베이스 데이터 정렬이 국가 이외의 문자 메서드로 전달된 문자열 매개 변수의 문자를 지원하지 않는 경우 일부 데이터가 손실될 수 있습니다.

응용 프로그램에서는 NCHAR, NVARCHARLONGNVARCHAR JDBC 데이터 형식에 대해 SQLServerPreparedStatementSQLServerCallableStatement 클래스의 setNString, setNCharacterStream, setNClob 국가별 문자 메서드를 사용해야 합니다.

이 값을 변경하면 데이터베이스의 결과 정렬에 영향을 줄 수 있습니다. 유니코드 문자와 유니코드가 아닌 문자에 대한 정렬 규칙이 다양해서 정렬에 차이가 나타납니다.
sendTemporalDataTypes...
AsStringForBulkCopy

부울 값
[“true” | “false”]

true
(버전 8.4 이상) 이 연결 속성을 “false”로 설정하면 DATE, DATETIME, DATIMETIME2, DATETIMEOFFSET, SMALLDATETIME, TIME 데이터 형식을 문자열로 전송하는 대신 각각의 형식으로 전송합니다.

이 연결 속성을 "false"로 설정하면 드라이버는 각 temporal 데이터 형식의 기본 문자열 리터럴 형식만 허용합니다. 예를 들면 다음과 같습니다.

DATE: YYYY-MM-DD
DATETIME: YYYY-MM-DD hh:mm:ss[.nnn]
DATETIME2: YYYY-MM-DD hh:mm:ss[.nnnnnnn]
DATETIMEOFFSET: YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]
SMALLDATETIME: YYYY-MM-DD hh:mm:ss
TIME: hh:mm:ss[.nnnnnnn]
sendTimeAsDatetime

부울 값
[“true” | “false”]

true
이 속성은 SQL Server JDBC Driver 3.0에 추가되었습니다.

“true”로 설정하면 java.sql.Time 값이 SQL Server datetime 값으로서 서버에 보내집니다.
“false”로 설정하면 java.sql.Time 값이 SQL Server time 값으로서 서버에 보내집니다.

이 속성의 기본값은 현재 “true”이며, 이후 버전에서 변경될 수 있습니다.

SQL Server용 Microsoft JDBC Driver에서 java.sql.Time 값을 서버로 보내기 전에 구성하는 방법에 대한 자세한 내용은 java.sql.Time 값을 서버에 보내는 방법 구성을 참조하세요.
serverCertificate,
server

문자열

null
(버전 11.2.0 이상) 서버 인증서 파일의 경로입니다. strict로 설정된 암호화를 사용할 때 유효성 검사에 사용됩니다. 드라이버는 PEM 파일 형식을 사용하여 인증서 파일을 지원합니다.
serverName,
server

문자열

null
SQL Server 또는 Azure SQL 데이터베이스를 실행하는 컴퓨터입니다.

가용성 그룹의 Virtual Network 이름을 지정할 수도 있습니다. 재해 복구에 대한 자세한 내용은 고가용성, 재해 복구를 위한 JDBC 드라이버 지원을 참조하세요.
serverNameAsACE

부울 값
[“true” | “false”]

false
(버전 6.0 이상) "true"로 설정하면 드라이버가 유니코드 서버 이름을 ASCII 호환 인코딩(Punycode)으로 변환해서 연결해야 합니다. 이 설정이 false이면 드라이버는 제공된 서버 이름을 사용하여 연결합니다.

국제 기능에 대한 자세한 내용은 JDBC 드라이버의 국제 기능을 참조하세요.
serverPreparedStatement...
DiscardThreshold

정수

10
(버전 6.2 이상) 서버의 미처리 핸들을 정리하기 위한 호출 실행 전에 연결별로 처리되지 않을 수 있는 미처리 준비 문 삭제 작업(sp_unprepare)의 수를 제어하는 데 이 속성을 사용할 수 있습니다.

이 속성이 <= 1로 설정되어 있다면 준비된 문이 종료되자마자 준비 취소 작업이 곧바로 실행됩니다. > 1로 설정된 경우 sp_unprepare를 너무 자주 호출하지 않도록 이러한 호출은 일괄 처리 처리됩니다.
serverSpn

문자열

null
(버전 4.2 이상) 이 선택적 속성은 Java Kerberos 연결에 대한 SPN(서비스 사용자 이름)을 지정하는 데 사용할 수 있습니다. authenticationScheme와 함께 사용됩니다.

SPN을 지정하려면 “MSSQLSvc/fqdn:port@REALM” 형식이 될 수 있습니다. 여기서 fqdn은 정규화된 도메인 이름이고, port는 포트 번호이며, REALM은 대문자로 표시된 SQL Server의 Kerberos 영역입니다.

참고: @REALM은 Kerberos 구성에 지정된 클라이언트의 기본 영역이 SQL Server의 Kerberos 영역과 동일한 경우 선택 사항입니다.

Java Kerberos에서 serverSpn을 사용하는 방법에 대한 자세한 내용은 Kerberos 통합 인증을 사용하여 SQL Server에 연결을 참조하세요.
socketFactoryClass

문자열

null
(버전 8.4 이상) 기본 소켓 팩터리 대신 사용할 사용자 지정 소켓 팩터리의 클래스 이름을 지정합니다.
socketTimeout

int

0
소켓 읽기 또는 허용 시 시간 제한이 발생하기 전까지 대기할 시간(밀리초)입니다. 기본값은 0이며, 이는 무한 시간 제한을 의미합니다.
statementPooling...
CacheSize

int

0
(버전 6.4 이상) 드라이버 내의 준비 문 핸들 캐싱을 사용하도록 설정하는 데 이 속성을 사용할 수 있습니다.

이 속성은 문 풀링의 캐시 크기를 정의합니다.

이 속성은 “false”로 설정되어야 하는 disableStatementPooling 연결 속성과만 함께 사용할 수 있습니다. disableStatementPooling을 "true"로, 또는 statementPoolingCacheSize를 0으로 설정하면 준비된 문 핸들 캐싱이 비활성화됩니다.
sslProtocol

문자열

TLS
(버전 6.4 이상) 보안 연결 중에 고려할 TLS 프로토콜을 지정하는 데 이 속성을 사용할 수 있습니다.
가능한 값은 TLS, TLSv1, TLSv1.1TLSv1.2입니다.

SSL(Secure Sockets Layer) 프로토콜에 대한 자세한 내용은 SSLProtocol을 참조하세요.
transparentNetwork...
IPResolution

부울 값
[“true” | “false”]

true
(버전 6.0 이상) 이 속성은 현재 활성 상태인 서버를 빠르게 감지하여 연결할 수 있도록 제공합니다. 가능한 값은 "true" 및 "false"이고 기본값은 "true"입니다.

SQL Server용 Microsoft JDBC Driver 6.0 이전에는 애플리케이션이 연결 문자열을 설정하여 “multiSubnetFailover=true”를 포함함으로써 Always On 가용성 그룹으로 연결되었음을 나타내야 했습니다. multiSubnetFailover 연결 키워드를 "true"로 설정하지 않으면 Always On 가용성 그룹 연결 중 애플리케이션에 시간 제한이 적용될 수 있습니다. 버전 6.0 이상에서는 애플리케이션이 multiSubnetFailover를 더 이상 true로 설정할 필요가 없습니다.

참고: transparentNetworkIPResolution=true의 경우에는 첫 연결 시도에서 500ms가 시간 제한으로 사용됩니다. 이후의 모든 시도에서는 multiSubnetFailover 속성에서 사용되는 것과 동일한 시간 제한 논리가 사용됩니다.
trustManagerClass

문자열

null
(버전 6.4 이상) 사용자 지정 javax.net.ssl.TrustManager 구현의 정규화된 클래스 이름입니다.
trustManager...
ConstructorArg

문자열

null
(버전 6.4 이상) TrustManager의 생성자에 전달할 선택적 인수입니다. trustManagerClass가 지정되고 암호화된 연결이 요청되면 기본 시스템 JVM 키 저장소 기반 TrustManager 대신 사용자 지정 TrustManager가 사용됩니다.
trustServerCertificate

부울 값
[“true” | “false”]

false
드라이버가 서버 TLS/SSL 인증서의 유효성을 검사하지 않도록 지정하려면 “true”로 설정합니다.

“true”이면, 통신 계층이 TLS를 사용하여 암호화된 경우 서버 TLS/SSL 인증서가 자동으로 신뢰됩니다.

“false”이면, 드라이버가 서버 TLS/SSL 인증서의 유효성을 검사합니다. 서버 인증서 유효성 검사에 실패하면 드라이버에서 오류가 발생하고 연결이 닫힙니다. 기본값은 “false”입니다. TLS/SSL 연결이 성공하려면 serverName에 전달된 값이 서버 인증서의 주체 대체 이름에 있는 CN(일반 이름) 또는 DNS 이름과 정확히 일치해야 합니다. 암호화 지원에 대한 자세한 내용은 암호화 지원 이해를 참조하세요.

참고: 이 속성은 암호화/인증 속성과 함께 사용됩니다. 이 속성은 TLS 암호화가 연결에 사용되는 경우에만 서버 TLS/SSL 인증서의 유효성 검사에 영향을 줍니다.
trustStore

문자열

null
인증서 trustStore 파일에 대한 경로(파일 이름 포함)입니다. trustStore 파일에는 클라이언트가 신뢰하는 인증서 목록이 포함됩니다.

이 속성이 지정되지 않았거나 null로 설정된 경우 드라이버에서는 트러스트 관리자 팩터리의 조회 규칙에 따라 사용할 인증서 저장소를 결정합니다.

기본 SunX509 TrustManagerFactory에서는 다음 검색 순서에 따라 트러스트 자료를 찾으려고 합니다.

"javax.net.ssl.trustStore" JVM 시스템 속성으로 지정된 파일.

<java-home>/lib/security/jssecacerts 파일.

<java-home>/lib/security/cacerts 파일.



SUNX509 TrustManager 인터페이스에 대한 자세한 내용은 Sun Microsystems 웹 사이트에서 SUNX509 TrustManager 인터페이스 설명서를 참조하세요.

참고: TLS 암호화가 연결에 사용되고 trustServerCertificate 속성이 “false”로 설정된 경우 이 속성은 인증서 trustStore 조회에만 영향을 줍니다.
trustStorePassword

문자열

null
trustStore 데이터의 무결성을 검사하는 데 사용되는 암호입니다.

trustStore 속성은 설정되어 있지만 trustStorePassword 속성이 설정되어 있지 않는 경우 trustStore의 무결성을 검사하지 않습니다.

trustStore 및 trustStorePassword 속성이 모두 지정되지 않은 경우 드라이버는 JVM 시스템 속성인 "javax.net.ssl.trustStore" 및 "javax.net.ssl.trustStorePassword"를 사용합니다. "javax.net.ssl.trustStorePassword" 시스템 속성을 지정하지 않으면 trustStore의 무결성이 검사 않습니다.

trustStore 속성은 설정되어 있지 않지만 trustStorePassword 속성이 설정되어 있는 경우 JDBC 드라이버에서는 “javax.net.ssl.trustStore”에 의해 지정된 파일을 트러스트 저장소로 사용하여 지정된 trustStorePassword로 트러스트 저장소의 무결성을 검사합니다. 클라이언트 응용 프로그램이 JVM 시스템 속성에 비밀번호를 저장하지 않으려는 경우 이 설정이 필요합니다.

참고: TLS 연결이 연결에 사용되고 trustServerCertificate 속성이 “false”로 설정된 경우 trustStorePassword 속성은 인증서 trustStore 조회에만 영향을 줍니다.
trustStoreType

문자열

JKS
FIPS 모드에 사용할 신뢰 저장소 유형을 지정하려면 이 속성을 설정합니다.

가능한 값은 PKCS12 또는 FIPS 공급자가 정의한 형식입니다.
useBulkCopyFor...
BatchInsert

부울 값
[“true” | “false”]

false
(버전 9.2 이상) 이 연결 속성으로 java.sql.PreparedStatement를 사용한 대량 삽입 작업을 수행할 때 대량 복사 API를 투명하게 사용할 수 있습니다. 이 기능을 사용하도록 설정하면 성능이 훨씬 더 높아질 수 있습니다.

이 기능은 기본적으로 비활성화되어 있습니다. 이 기능을 사용하려면 이 속성을 "true"로 설정합니다.

중요 정보: 이 기능은 완전히 매개 변수화된 INSERT 쿼리만 지원 합니다. INSERT 쿼리가 다른 SQL 쿼리로 결합되거나 값에 데이터가 포함된 경우 실행은 기본 일괄 삽입 작업으로 돌아갑니다.

이 속성의 사용 방법에 대한 자세한 내용은 일괄 삽입 작업에 대량 복사 API 사용을 참조하세요.
useDefaultGSSCredential

부울 값
[“true” | “false”]

false
(버전 12.6 이상) 드라이버가 Kerberos 인증에 네이티브 GSS-API를 사용하기 위해 사용자를 대신하여 GSSCredential을 만들어야 하는지 여부를 나타내는 플래그입니다.
useDefaultJaasConfig

부울 값
[“true” | “false”]

false
(버전 12.6 이상) 시스템 수준에서 JAAS를 구성하는 라이브러리와 함께 응용 프로그램이 있으면, true로 설정할 경우 드라이버가 동일한 구성을 사용하여 Kerberos 인증을 수행할 수 있습니다.
useFlexibleCallableStatements

부울 값
[“true” | “false”]

true
(버전 12.6 이상) true로 설정하면 인덱스 또는 매개 변수 이름을 혼합하여 문 매개 변수 설정을 수행할 수 있습니다. 또한 이러한 매개 변수 설정을 sproc 정의와 다른 순서로 수행할 수 있습니다. 이 두 가지 모두 추가 매개 변수 메타데이터 조회를 통해 가능합니다.

false로 설정할 때 매개 변수 설정은 인덱스 또는 매개 변수 이름으로 수행해야 하지만 두 가지를 모두 함께 설정하지는 말아야 합니다. 또한 준비된 문 정의에 정의된 순서와 동일한 순서로 설정해야 합니다. 이 옵션을 false로 설정해도 위에서 언급된 추가 메타데이터 조회가 트리거되지는 않습니다.
useFmtOnly

부울 값
[“true” | “false”]

false
(버전 7.4 이상) 서버에서 매개 변수 메타데이터를 쿼리하는 다른 방법을 제공합니다. 매개 변수 메타데이터를 쿼리할 때 드라이버가 SET FMTONLY 논리를 사용하도록 지정하려면 이 속성을 "true"로 설정합니다. 이 기능은 기본값으로 꺼져 있으며 SET FMTONLY가 사용되지 않음이라고 표시되어 있으므로 사용하지 않는 것이 좋습니다. useFmtOnlysp_describe_undeclared_parameters의 알려진 문제 및 제한 사항에 대한 해결 방법으로만 사용할 수 있습니다.

이 기능은 현재 단일 SELECT/INSERT/UPDATE/DELETE 쿼리만 지원합니다. 지원되지 않는/여러 쿼리에서 이 기능을 사용하려고 하면 드라이버가 쿼리를 구문 분석하려고 시도하지만, 예외가 발생할 가능성이 큽니다.

이 속성에 대한 자세한 내용은 useFmtOnly를 통해 ParameterMetaData 검색을 참조 하세요.
userName,
user

문자열
[<=128개 문자]

null
SQL 사용자 및 암호에 연결하는 경우의 데이터베이스 사용자입니다.

보안 주체 이름과 암호를 사용하는 Kerberos 연결의 경우 이 속성은 Kerberos 보안 주체 이름으로 설정됩니다.

(버전 10.2 이상) authentication=ActiveDirectoryServicePrincipal인 경우 userName 속성은 유효한 Azure Active Directory 보안 클라이언트 ID를 지정합니다.
workstationID

문자열
[<=128개 문자]

<empty string>
워크스테이션 ID입니다. 다양한 프로파일링 및 로깅 도구에서 특정 워크스테이션을 식별하는 데 사용합니다.

지정한 것이 없으면 <empty string>가 사용됩니다.
xopenStates

부울 값
[“true” | “false”]

false
드라이버가 예외에서 XOPEN 준수 상태 코드를 반환하도록 지정하려면 "true"로 설정합니다.

기본값은 SQL 99 상태 코드를 반환하는 것입니다.

참고 항목

SQL Server용 Microsoft JDBC 드라이버에서는 ANSI_DEFAULTS 및 IMPLICIT_TRANSACTIONS를 제외한 연결 속성에 서버 기본값을 사용합니다. SQL Server용 Microsoft JDBC 드라이버에서는 자동으로 ANSI_DEFAULTS를 ON으로 설정하고 IMPLICIT_TRANSACTIONS를 OFF로 설정합니다.

Important

인증이 ActiveDirectoryPassword로 설정된 경우 클래스 경로에 microsoft-authentication-library-for-java 라이브러리를 포함해야 합니다. Maven 리포지토리에서 찾을 수 있습니다. 라이브러리 및 해당 종속성을 가장 간단히 다운로드하는 방법은 Maven을 사용하는 것입니다.

  1. 시스템에 Maven을 설치합니다
  2. 드라이버의 GitHub 페이지로 이동합니다.
  3. pom.xml 파일 다운로드
  4. Maven 명령(mvn dependency:copy-dependencies)을 실행하여 라이브러리 및 해당 종속성을 다운로드합니다.

참고 항목

JDBC 드라이버로 SQL Server에 연결
FIPS 모드