Definir as propriedades de conexão

Baixar driver JDBC

Você pode especificar as propriedades cadeia de conexão de várias maneiras:

• Como <name>=<value> propriedades na URL de conexão quando você se conecta usando a classe DriverManager. Para obter a sintaxe da cadeia de conexão, confira Como criar a URL de conexão.

• Como <name>=<value> propriedades no parâmetro Properties do método Connect na classe DriverManager.

• Como valores no método setter apropriado da fonte de dados do driver. Por exemplo:

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

Comentários

• Os nomes de propriedades não diferenciam maiúsculas de minúsculas. O driver resolve nomes de propriedade duplicados na seguinte ordem:

  1. Argumentos de API, como user e password
  2. Coleção de propriedades
  3. Última instância na cadeia de conexão

• Você pode usar valores desconhecidos para nomes de propriedade. O driver JDBC não valida sensibilidade a maiúsculas e minúsculas.

• Você pode usar sinônimos. O driver os resolve em ordem, assim como faz com os nomes de propriedade duplicados.

• O Microsoft JDBC Driver for SQL Server usa os valores padrão do servidor para propriedades de conexão, exceto para ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. O Microsoft JDBC Driver for SQL Server define automaticamente ANSI_DEFAULTS como ON e IMPLICIT_TRANSACTIONS como OFF.

• Se você definir a autenticação como ActiveDirectoryPassword [DEPRECATED], inclua a seguinte biblioteca no classpath: microsoft-authentication-library-for-java. Localize-o no Repositório Maven. A maneira mais simples de baixar a biblioteca e suas dependências é usar o Maven:

  1. Instale o Maven em seu sistema.
  2. Vá para a página GitHub do driver.
  3. Baixe o pom.xml arquivo.
  4. Execute o seguinte comando Maven para baixar a biblioteca e suas dependências: mvn dependency:copy-dependencies.

Propriedades

As seções a seguir descrevem todas as propriedades de cadeia de conexão disponíveis no momento para o driver JDBC.

accessToken

• Tipo: String
• Padrão: null

(Versão 6.0+) Use essa propriedade para se conectar a um banco de dados usando um token de acesso. Você não pode definir accessToken usando a URL de conexão.

accessTokenCallbackClass

• Tipo: String
• Padrão: null

(Versão 12.4+) O nome da classe que implementa o retorno de chamada a ser usado com o retorno de chamada do token de acesso.

applicationIntent

• Tipo: String
• Padrão: ReadWrite

(Versão 6.0 ou superior) Declara o tipo de carga de trabalho do aplicativo para conectar-se a um servidor.

Os valores possíveis são: ReadOnly e ReadWrite.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

applicationName

• Tipo: String [<=128 char]
• Padrão: null

O nome do aplicativo ou "Microsoft JDBC Driver for SQL Server" se você não fornecer um nome.

Utilize este nome para identificar o aplicativo específico em várias ferramentas de monitoramento de performance e registro em log do SQL Server.

autenticação

• Tipo: String
• Padrão: NotSpecified

(Versão 6.0+) Essa propriedade opcional indica qual método de autenticação usar para conexão.

Os valores possíveis são ActiveDirectoryIntegrated, (versão 12.2+), ActiveDirectoryManagedIdentity (versão 7.2+), ActiveDirectoryMSI (versão 9.2+), ActiveDirectoryInteractive (versão 9.2+), ActiveDirectoryServicePrincipalActiveDirectoryPassword [DEPRECATED]e o padrão SqlPasswordNotSpecified .

Use ActiveDirectoryIntegrated (versão 6.0+) para se conectar ao SQL usando autenticação integrada do Windows.

Use ActiveDirectoryManagedIdentity (versão 12.2+) ou ActiveDirectoryMSI (versão 7.2+) para se conectar ao SQL de dentro de um recurso de Azure. Por exemplo, um Azure Máquina Virtual, Serviço de Aplicativo ou Aplicativo de Funções usando a autenticação de identidade gerenciada.

Os dois tipos de identidades gerenciadas compatíveis com o driver ao usar o modo de autenticação ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI são:

• Identidade Gerenciada Atribuída pelo Sistema: usado para adquirir accessToken por padrão.

• Identidade Gerenciada Atribuída ao Usuário: usada para adquirir accessToken se a ID do cliente de uma identidade gerenciada for especificada com a propriedade de conexão msiClientId.

Use ActiveDirectoryInteractive para se conectar a um banco de dados usando um fluxo de autenticação interativo.

Use ActiveDirectoryServicePrincipal (versão 9.2+) para se conectar a um banco de dados usando o identificador do cliente e o segredo de uma identidade principal de serviço. Especifique o ID do cliente na propriedade userName e o segredo na propriedade password (10.2+).

Use ActiveDirectoryServicePrincipalCertificate (versão 12.4+) para se conectar a um banco de dados usando a ID do cliente e o certificado de uma identidade de entidade de serviço. Especifique o ID do cliente na propriedade userName e o caminho para o certificado na propriedade clientCertificate.

Para obter mais opções, consulte Conectar usando o modo de autenticação ActiveDirectoryServicePrincipalCertificate.

Use ActiveDirectoryPassword [DEPRECATED] para se conectar ao SQL usando um nome de entidade de Microsoft Entra e senha.

ActiveDirectoryPassword foi preterido.

Para obter mais informações, confira Conectar-se usando o modo de autenticação ActiveDirectoryPassword.

Use SqlPassword para se conectar ao SQL usando userName/user e propriedades password.

Use NotSpecified se nenhum desses métodos de autenticação for necessário.

Quando você define a propriedade de autenticação como qualquer valor diferente NotSpecified, o driver usa TLS (Transport Layer Security), anteriormente conhecido como SSL (Secure Sockets Layer), criptografia por padrão.

Para obter informações sobre como configurar Microsoft Entra autenticação, consulte Microsoft Entra autenticação para SQL do Azure.

authenticationScheme

• Tipo: String
• Padrão: NativeAuthentication

Indica que tipo de segurança integrada você deseja que o seu aplicativo use.

Os valores possíveis são JavaKerberos, NTLM (versão 7.4+) e o padrão NativeAuthentication.

NativeAuthentication faz com que o driver carregue mssql-jdbc_auth-<version>-<arch>.dll (por exemplo, mssql-jdbc_auth-8.2.2.x64.dll) no Windows, que é usado para obter informações de autenticação integradas.

(A biblioteca de autenticação nativa carregada é nomeada sqljdbc_auth.dll ao usar as versões de driver 6.0 a 7.4.)

Ao usar authenticationScheme=JavaKerberos, você deve especificar o FQDN (nome de domínio totalmente qualificado) na propriedade serverName ou serverSpn. Caso contrário, ocorrerá um erro (Servidor não encontrado no banco de dados de Kerberos).

Para obter mais informações sobre como usar authenticationScheme=JavaKerberos, consulte Usar autenticação integrada do Kerberos para se conectar ao SQL Server.

Ao usar authenticationScheme=NTLM, você deve especificar o domínio Windows usando a propriedade domain ou domainName, as credenciais Windows na propriedade user ou userName e na propriedade password. Caso contrário, ocorrerá um erro (as propriedades de conexão devem ser especificadas).

bulkCopyForBatchInsertAllowEncryptedValueModifications

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Quando você definir useBulkCopyForBatchInsert como true, defina esta opção para true para habilitar a cópia em massa de dados criptografados entre tabelas ou bancos de dados, sem descriptografar os dados.

Para obter mais informações e avisos sobre como usar essa propriedade, consulte a opção allowEncryptedValueModifications em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertBatchSize

• Tipo: int
• Padrão: 0

(Versão 12.10+) Quando você define useBulkCopyForBatchInsert como true, essa propriedade especifica o tamanho do lote para operações de cópia em massa que o driver cria a partir de operações de inserção em lote.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção BatchSize em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertCheckConstraints

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Ao usar useBulkCopyForBatchInsert=true, defina essa opção para true habilitar restrições de verificação ao inserir dados. Defina essa opção para false para desabilitar as restrições de verificação.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção CheckConstraints em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertFireTriggers

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Ao usar useBulkCopyForBatchInsert=true, defina esta opção como true para habilitar a ativação de gatilhos de inserção ao inserir linhas no banco de dados. Defina essa opção para false para desabilitar gatilhos de inserção.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção FireTriggers em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertKeepIdentity

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Ao usar useBulkCopyForBatchInsert=true, defina essa opção para true preservar valores de identidade de origem ao inserir dados. Configure a opção false para atribuir valores de identidade pelo destino.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção KeepIdentity em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertKeepNulls

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Ao usar useBulkCopyForBatchInsert=true, defina essa opção para true preservar valores nulos na tabela de destino, independentemente das configurações de valor padrão. Configure esta opção para false permitir que os padrões de destino substituam valores nulos.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção KeepNulls em SQLServerBulkCopyOptions.

bulkCopyForBatchInsertTableLock

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.10+) Quando você definir useBulkCopyForBatchInsert como true, defina essa opção para true obter um bloqueio de atualização em massa durante a operação de cópia em massa. Defina essa opção para false para usar bloqueios por linha.

Para obter mais informações sobre os efeitos dessa configuração, consulte a opção TableLock em SQLServerBulkCopyOptions.

cacheBulkCopyMetadata

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.8+) Ao usar useBulkCopyForBatchInsert=true, essa propriedade informa ao driver se ele deve armazenar em cache metadados de coluna de destino no nível da conexão. Se definido como true, verifique se o destino não é alterado entre inserções em massa, pois o driver não tem uma maneira de lidar com essa alteração.

calcBigDecimalPrecision

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.6+) Indicador para determinar se o driver deve calcular a precisão para entradas do tipo BigDecimal, em vez de usar o valor máximo permitido para precisão (38).

cancelQueryTimeout

• Tipo: int
• Padrão: -1

(Versão 6.4+) Use essa propriedade para cancelar uma queryTimeout definição na conexão. A execução da consulta para de responder e não gera uma exceção se a conexão TCP com o servidor for descartada silenciosamente. Essa propriedade só será aplicável se queryTimeout também estiver definida na conexão.

O driver aguarda a quantidade total de cancelQueryTimeout + queryTimeout segundos para remover a conexão e fechar o canal.

O valor padrão dessa propriedade é -1 e o comportamento é aguardar indefinidamente.

Clientcertificate

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica o local do certificado a ser usado para autenticação de certificado do cliente. O driver JDBC dá suporte às extensões de arquivo PFX, PEM, DER e CER.

Para maiores detalhes, consulte Autenticação de certificado do cliente para cenários de loopback.

clientKey

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica o local da chave privada para certificados PEM, DER e CER especificados pelo clientCertificate atributo.

Para maiores detalhes, consulte Autenticação de certificado do cliente para cenários de loopback.

clientKeyPassword

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica a cadeia de caracteres de senha opcional para acessar a clientKey chave privada do arquivo.

Para maiores detalhes, consulte Autenticação de certificado do cliente para cenários de loopback.

configuraçãoDeCriptografiaDeColuna

• Tipo: String [Enabled | Disabled]
• Padrão: Disabled

(Versão 6.0+) Defina para Enabled usar o recurso Always Encrypted (AE). Quando o AE está habilitado, o driver JDBC criptografa e descriptografa de modo transparente os dados confidenciais armazenados em colunas de banco de dados criptografado no servidor.

Para obter mais informações sobre o Always Encrypted, consulte Use Always Encrypted com o driver JDBC.

concatNullYieldsNull

• Tipo: String [ON | OFF]
• Padrão: ON

(Versão 13.2+) Quando você define essa opção como OFF, o driver define a variável CONCAT_NULL_YIELDS_NULL de sessão de banco de dados para OFF quando ela estabelece a conexão. O resultado é que concatenar um valor nulo com uma cadeia de caracteres gera a cadeia de caracteres em si (o valor nulo é tratado como uma cadeia de caracteres vazia).

Para saber mais, confira SET CONCAT_NULL_YIELDS_NULL.

connectRetryCount

• Tipo: int [0..255]
• Padrão: 1

(Versão 9.4 ou superior) O número de tentativas de reconexão quando há uma falha de conexão.

connectRetryInterval

• Tipo: int [1..60]
• Padrão: 10

(Versão 9.4 ou superior) O número de segundos entre cada nova tentativa de conexão.

databaseName, banco de dados

• Tipo: String [<=128 char]
• Padrão: null

O nome do banco de dados ao qual se conectar.

Se você não especificar um nome de banco de dados, a conexão usará o banco de dados padrão.

datetimeParameterType

• Tipo: String [datetime | datetime2 | datetimeoffset]
• Padrão: datetime2

(Versão 12.2+) O tipo de dados SQL a ser usado para parâmetros de data e carimbo de data/hora do Java.

Quando você se conectar ao SQL Server 2016 ou posterior e interagir com valores datetime herdados, defina essa propriedade como datetime. Essa configuração reduz os problemas de conversão do lado do servidor entre os valores datetime e datetime2.

Para obter mais informações, consulte Endereçar a mudança de comportamento da conversão de datetime para datetime2 a partir do SQL Server 2016.

delayLoadingLobs

• Tipo: Boolean [true | false]
• Padrão: true

Sinalizar para indicar se todos os objetos LOB recuperados do ResultSet devem ser transmitidos. Definir essa propriedade para false carregar todo o objeto LOB na memória sem streaming.

disableStatementPooling

• Tipo: Boolean [true | false]
• Padrão: true

Sinalizador que indica se o agrupamento de instruções deve ser usado.

domainName, domínio

• Tipo: String
• Padrão: null

(Versão 7.4+) O domínio Windows para autenticar ao usar a autenticação NTLM.

enablePrepareOnFirstPreparedStatementCall

• Tipo: Boolean [true | false]
• Padrão: false

Defina true para habilitar a criação do identificador de instrução preparada ao chamar sp_prepexec com a primeira execução de uma instrução preparada.

Configure false para modificar a primeira execução de uma instrução preparada para chamar sp_executesql sem preparar uma instrução. Se ocorrer uma segunda execução, ele chamará sp_prepexec para configurar um identificador de instrução preparado.

enclaveAttestationProtocol

• Tipo: String
• Padrão: null

(Versão 8.2+) Essa propriedade opcional indicará o protocolo de atestado a ser usado para o Always Encrypted com enclaves seguros. Atualmente, os únicos valores com suporte para esse campo são HGS, AASe NONE (NONE só tem suporte na versão 11.2+).

Para obter mais informações sobre o Always Encrypted com enclaves seguros, consulte Como usar o Always Encrypted com enclaves seguros com o driver JDBC.

enclaveAttestationUrl

• Tipo: String
• Padrão: null

(Versão 8.2+) Essa propriedade opcional indicará a URL do ponto de extremidade de serviço de atestado a ser usada para o Always Encrypted com enclaves seguros.

Para obter mais informações sobre o Always Encrypted com enclaves seguros, consulte Como usar o Always Encrypted com enclaves seguros com o driver JDBC.

criptografar

• Tipo: String
• Padrão: null

Defina como true para especificar que o SQL Mecanismo de Banco de Dados usa criptografia TLS para todos os dados enviados entre o cliente e o servidor se o servidor tiver um certificado instalado. O valor padrão está true na versão 10.2 e posterior e false na 9.4 e anterior.

Na versão 6.0 e posterior, há uma nova configuração authentication de conexão que usa a criptografia TLS por padrão.

Para obter mais informações sobre essa propriedade, consulte a propriedade authentication.

Na versão 11.2.0 e posterior, encrypt foi alterado de Boolean para string, permitindo o suporte ao TDS 8.0 quando a propriedade é definida como strict.

A alteração padrão na versão 10.2 é uma alteração significativa. Se você estiver atualizando do 9.4 ou anterior e seu servidor não tiver um certificado TLS válido, defina trustServerCertificate para true ou forneça um certificado válido.

Failover Partner

• Tipo: String
• Padrão: null

O nome do servidor de failover usado em uma configuração de espelhamento de banco de dados. Essa propriedade é usada para uma falha de conexão inicial ao servidor principal. Depois de fazer a conexão inicial, essa propriedade será ignorada. Deve ser usado com a propriedade databaseName.

Se você especificar um nome de Rede Virtual na propriedade de conexão Server, não poderá usar o espelhamento de banco de dados.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

FIPS

• Tipo: Boolean [true | false]
• Padrão: false

Defina essa propriedade como true para a JVM (Máquina Virtual Java) habilitada para FIPS.

fipsProvider

• Tipo: String
• Padrão: null

Provedor FIPS configurado em JVM, como BCFIPS ou SunPKCS11-NSS. Removido na versão 6.4.0.

Para obter mais informações, confira problema 460 do GitHub.

gsscredential

• Tipo: org.ietf.jgss.GSSCredential
• Padrão: null

(Versão 6.2+) Passe as credenciais do usuário para Delegação Restrita Kerberos nesta propriedade.

Use essa configuração com integratedSecurity como true e JavaKerberos como authenticationScheme.

HostnameInCertificate

• Tipo: String
• Padrão: null

O nome do host a ser usado para validar o certificado TLS/SSL SQL Server.

A hostNameInCertificate opção pode ser usada para especificar o nome do host em situações em que o nome ou os nomes usados no certificado não correspondem ao nome passado para a serverName propriedade. No entanto, se houver uma correspondência, a opção hostNameInCertificate não deverá ser usada.

Em situações em que a propriedade hostNameInCertificate não está especificada ou definida como nula, o Microsoft JDBC Driver for SQL Server usa o valor da propriedade serverName na URL de conexão como o nome do host para validar o certificado TLS/SSL SQL Server.

Use essa propriedade em combinação com a encrypt propriedade e a authentication propriedade, e a trustServerCertificate propriedade. Essa propriedade afetará a validação do certificado se a conexão usar a criptografia TLS e ela trustServerCertificate estiver definida como false. Verifique se o valor que você passa para hostNameInCertificate corresponde ao nome comum (CN) ou nome DNS no SAN (Nome Alternativo do Sujeito) no certificado do servidor para que uma conexão TLS seja bem-sucedida.

Para obter mais informações sobre suporte à criptografia, confira Noções básicas sobre suporte à criptografia.

Instancename

• Tipo: String [<=128 char]
• Padrão: null

O nome da instância do banco de dados à qual se conectar. Quando você não especifica essa propriedade, você se conecta à instância padrão. Para o caso em que você especifica tanto o instanceName quanto a porta, consulte as notas para a porta.

Se você especificar um nome de Rede Virtual na propriedade de conexão Server, não poderá usar a propriedade de conexão instanceName.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

Integratedsecurity

• Tipo: Boolean [true | false]
• Padrão: false

Defina como true para indicar que as credenciais de Windows são usadas por SQL Server em sistemas operacionais Windows. Se true, o driver JDBC pesquisará no cache de credenciais do computador local as credenciais fornecidas quando um usuário entrou no computador ou na rede.

Defina como true (com authenticationscheme=JavaKerberos), para indicar que as credenciais Kerberos são usadas por SQL Server.

Para obter mais informações sobre a autenticação do Kerberos, confira Como usar uma autenticação integrada do Kerberos para se conectar ao SQL Server.

Defina como true (com authenticationscheme=NTLM), para indicar que as credenciais NTLM são usadas por SQL Server.

Se false, o nome de usuário e a senha devem ser fornecidos.

ipaddresspreference

• Tipo: String [<=128 char]
• Padrão: IPv4First

A preferência de IP usada pelo aplicativo cliente.

Com IPV4First, o driver percorre primeiro os endereços IPv4. Se nenhum endereço IPv4 puder ser conectado com êxito, o driver prosseguirá e tentará endereços IPv6, se houver algum.

Com IPV6First, o driver percorre primeiro os endereços IPv6. Se nenhum endereço IPv6 puder ser conectado com êxito, o driver prosseguirá e tentará endereços IPv4, se houver algum.

Com UsePlatformDefault, o driver percorre todos os endereços IP na ordem inicial da resolução DNS.

jaasConfigurationName

• Tipo: String
• Padrão: SQLJDBCDriver

(Versão 6.2+) Cada conexão com o SQL Server pode usar seu próprio arquivo de configuração de logon JAAS para estabelecer uma conexão Kerberos. Você pode passar o nome da entrada de configuração por meio dessa propriedade. Use essa propriedade ao criar um arquivo de configuração Kerberos. Por padrão, o driver procura pelo nome SQLJDBCDriver.

Se o driver não encontrar uma configuração externa, ele definirá useDefaultCcache=true para JVMs IBM e useTicketCache=true para outras JVMs.

keyStoreAuthentication

• Tipo: String
• Padrão: null

(Versão 6.0+) Essa propriedade identifica qual repositório de chaves usar com Always Encrypted e determina um mecanismo de autenticação usado para autenticação no repositório de chaves. O driver suporta a configuração perfeita do Repositório de Chaves do Java quando você define keyStoreAuthentication=JavaKeyStorePassword. Para usar essa propriedade, você também deve definir as propriedades keyStoreLocation e keyStoreSecret para o Repositório de Chaves Java.

Começando com Microsoft JDBC Driver 8.4, você pode definir keyStoreAuthentication=KeyVaultManagedIdentity ou keyStoreAuthentication=KeyVaultClientSecret para autenticar para Azure Key Vault usando Identidades Gerenciadas.

Para obter mais informações sobre o Always Encrypted, consulte Use Always Encrypted com o driver JDBC.

keyStoreLocation

• Tipo: String
• Padrão: null

(Versão 6.0+) Quando keyStoreAuthentication=JavaKeyStorePassword, a propriedade keyStoreLocation identifica o caminho para o arquivo de repositório de chaves Java que armazena a Chave Mestra de Coluna para uso com dados Always Encrypted. O caminho deverá incluir o nome de arquivo do repositório de chaves.

Para obter mais informações sobre o Always Encrypted, consulte Use Always Encrypted com o driver JDBC.

keyStorePrincipalId

• Tipo: String
• Padrão: null

(Versão 8.4+) Quando keyStoreAuthentication=KeyVaultManagedIdentity, a propriedade keyStorePrincipalId especifica uma ID válida do cliente do aplicativo Microsoft Entra.

Para obter mais informações sobre o Always Encrypted, consulte Use Always Encrypted com o driver JDBC.

keyStoreSecret

• Tipo: String
• Padrão: null

(Versão 6.0+) Quando keyStoreAuthentication=JavaKeyStorePassword, a keyStoreSecret propriedade identifica a senha a ser usada para o repositório de chaves e a chave. Quando você usa o repositório de chaves Java, o repositório de chaves e a senha da chave devem ser os mesmos.

Para obter mais informações sobre o Always Encrypted, consulte Use Always Encrypted com o driver JDBC.

lastUpdateCount

• Tipo: Boolean [true | false]
• Padrão: true

Um true valor retorna apenas a última contagem de atualizações de uma instrução SQL que você passa para o servidor. Use esse valor com apenas instruções únicas SELECT, INSERT, ou DELETE para ignorar outras contagens de atualização que os gatilhos de servidor podem causar. Defina esta propriedade como false para retornar todas as contagens de atualizações, incluindo aquelas que os gatilhos de servidor retornam.

Locktimeout

• Tipo: int
• Padrão: -1

O número de milissegundos a aguardar antes que o banco de dados reporte um tempo limite de bloqueio. O comportamento padrão é aguardar indefinidamente. Se você não especificar um valor para essa propriedade, esse valor será o padrão para todas as instruções na conexão.

Como alternativa, use Statement.setQueryTimeout() para definir o prazo de execução da consulta para declarações específicas. O valor pode ser 0, que especifica a ausência de espera.

Logintimeout

• Tipo: int [0..65535]
• Padrão: 30 (versão 11.2 e posterior) ou 15 (versão 10.2 e anterior)

O número de segundos que o driver deve aguardar antes que o tempo limite de uma conexão com falha seja alcançado. Um valor igual a zero indica que o tempo limite é o tempo limite padrão do sistema. Esse valor é de 30 segundos (o padrão na versão 11.2 e posterior) ou 15 segundos (o padrão na versão 10.2 e anterior). Um valor diferente de zero é o número de segundos que o driver deve aguardar antes do tempo limite de uma conexão com falha.

Se você especificar um Nome de Rede Virtual na propriedade de conexão Server, especifique um valor de tempo limite de pelo menos três minutos para permitir tempo suficiente para que uma conexão de contingência seja bem-sucedida.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

maxResultBuffer

• Tipo: String
• Padrão: null

(Versão 9.2+) Use maxResultBuffer para definir o número máximo de bytes a serem lidos ao ler um conjunto de resultados. Se você não especificar esse valor, o driver lerá todo o conjunto de resultados. Você pode especificar o tamanho em dois estilos:

• Como um tamanho em bytes (por exemplo, , 100, 150M, 300K, 400G).
• Como um percentual da memória máxima do heap (por exemplo, 10p, 15pct, 20percent).

msiClientId

• Tipo: String
• Padrão: null

(Preterido) (Versão 7.2+) O ID do Cliente da Identidade Gerenciada (MSI) usado para adquirir uma accessToken para estabelecer uma conexão usando o modo de autenticação ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI.

multiSubnetFailover

• Tipo: Boolean [true | false]
• Padrão: false

Sempre especifique multiSubnetFailover=true para se conectar ao ouvinte de um grupo de disponibilidade do SQL Server ou a uma Instância de Cluster de Failover do SQL Server. multiSubnetFailover=true configura o driver para fornecer detecção e conexão mais rápidas ao servidor ativo.

Os valores possíveis são: true e false.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

Você pode acessar programaticamente a multiSubnetFailover propriedade de conexão usando getPropertyInfo, getMultiSubnetFailover e setMultiSubnetFailover.

Packetsize

• Tipo: int [-1 | 0 | 512..32767]
• Padrão: 8000

O tamanho do pacote de rede usado para se comunicar com o SQL Server, especificado em bytes. Um valor igual a -1 indica que o tamanho de pacote padrão do servidor deve ser usado. Um valor de 0 indica que o valor máximo de 32767 deve ser usado. Se você definir essa propriedade como um valor fora do intervalo aceitável, ocorrerá uma exceção.

Para obter mais informações sobre essa propriedade, confira o método setPacketSize da classe SQLServerDataSource.

password

• Tipo: String [<=128 char]
• Padrão: null

A senha do banco de dados, se você se conectar com um usuário e senha do SQL.

Para conexão Kerberos com nome principal e senha, defina essa propriedade como a senha do Principal Kerberos.

(Versão 10.2+) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade password identifica a senha a ser usada para a entidade de Active Directory.

númeroDaPorta, porta

• Tipo: int [0..65535]
• Padrão: 1433

A porta em que o servidor está escutando. Se você especificar o número da porta no cadeia de conexão, nenhuma solicitação ao SQLbrowser será feita. Quando você especifica a porta e instanceName, a conexão é feita para a porta especificada. No entanto, o instanceName valor será validado e um erro será gerado se ele não corresponder à porta.

Preparemethod

• Tipo: String [prepexec | prepare | scopeTempTablesToConnection | none]
• Padrão: prepexec

(Versão 11.2.0+) Especifica o método de preparação subjacente que o driver usa com instruções preparadas.

Defina prepare para usar sp_prepare como método de preparação. A definição de prepareMethod como esse valor resulta em uma viagem inicial separada ao banco de dados para preparar a instrução sem nenhum valor inicial para o banco de dados considerar no plano de execução. Defina prepexec para usar sp_prepexec como método de preparação. Esse método combina a ação de preparação com a primeira execução, reduzindo as viagens de ida e volta. Ele também fornece ao banco de dados valores de parâmetro iniciais que o banco de dados pode considerar no plano de execução.

(Versão 13.4.0+) Defina como scopeTempTablesToConnection para definir o escopo de tabelas temporárias criadas em instruções preparadas na conexão, usando substituição literal de parâmetros em vez de identificadores preparados do lado do servidor. Definir como none para impor a substituição de parâmetros literais durante a execução em lote do SQL, ignorando os identificadores de instruções preparadas no lado do servidor (sp_prepexec / sp_prepare).

Limitações e isenção de responsabilidade para scopeTempTablesToConnection e none:

Essas prepareMethod opções se destinam a cenários de compatibilidade e migração, não para uso geral de desempenho.

• Nenhuma instrução preparada do lado do servidor; o SQL sempre é executado como um lote.
• Requer FORCED_PARAMETERIZATION para reutilização eficaz de plano.
• Os parâmetros são embutidos como literais em vez de tipos vinculados.
• A precisão e a escala numéricas podem ser diferentes da associação de parâmetros do lado do servidor.
• Os valores de data e hora são formatados como cadeias de caracteres pelo driver.
• Parâmetros de cadeia de caracteres grandes aumentam o tamanho do texto SQL e o uso da memória.
• Os parâmetros BLOB e CLOB podem causar alto uso de memória ou condições de memória insuficiente.
• SQL Server infere tipos de dados de parâmetro no momento da análise SQL.
• Os planos de consulta podem variar devido a diferenças nos valores literais.
• Erros são detectados no momento da execução, ao invés de no tempo de vinculação.
• O SQL executado inclui valores literais e fica visível em logs e rastreamentos do servidor.

Querytimeout

• Tipo: int
• Padrão: -1

O número de segundos a aguardar antes que um tempo limite ocorra em uma consulta. O valor padrão é -1, que significa tempo limite infinito. Definir esse valor como 0 também implicará em uma espera por tempo indeterminado.

quotedIdentifier

• Tipo: String [ON | OFF]
• Padrão: ON

(Versão 13.2+) Quando você define essa opção como OFF, o driver define a variável QUOTED_IDENTIFIER de sessão de banco de dados para OFF quando ela estabelece a conexão. O banco de dados trata aspas duplas como delimitadores de cadeia de caracteres para literais de caractere e você não pode colocar identificadores entre aspas duplas.

Para saber mais, confira SET QUOTED_IDENTIFIER.

Domínio

• Tipo: String
• Padrão: null

(Versão 9.4 ou superior) O realm da autenticação Kerberos. Definir esse valor substituirá o realm de autenticação Kerberos que o driver detecta automaticamente por meio do realm do servidor.

Replicação

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 9.4 ou superior) Essa configuração informa ao servidor se a conexão é usada para replicação. Quando habilitada, os gatilhos com a opção NOT FOR REPLICATION não são acionados na conexão.

Responsebuffering

• Tipo: String [full | adaptive]
• Padrão: adaptive

Se você definir essa propriedade como adaptive, o driver armazenará em buffer a quantidade mínima de dados quando necessário. O modo padrão é adaptive.

Se você definir essa propriedade como full, o driver lerá todo o conjunto de resultados do servidor quando ele executar uma instrução.

Selectmethod

• Tipo: String [direct | cursor]
• Padrão: direct

Se você definir essa propriedade como cursor, o driver criará um cursor de banco de dados para cada consulta que ele configura na conexão para os cursores TYPE_FORWARD_ONLY e CONCUR_READ_ONLY. Normalmente, você só precisará dessa propriedade se o aplicativo gerar grandes conjuntos de resultados que não cabem inteiramente na memória do cliente. Se você definir essa propriedade como cursor, o driver manterá apenas um número limitado de linhas de conjunto de resultados na memória do cliente.

Por padrão, o driver mantém todas as linhas do conjunto de resultados na memória do cliente. Esse comportamento padrão fornece o desempenho mais rápido quando o aplicativo processa todas as linhas.

sendStringParametersAsUnicode

• Tipo: Boolean [true | false]
• Padrão: true

Se você definir a sendStringParametersAsUnicode propriedade como true, o driver enviará parâmetros de cadeia de caracteres para o servidor no formato Unicode.

Se você definir a sendStringParametersAsUnicode propriedade como false, o driver enviará parâmetros de cadeia de caracteres para o servidor em formatos não Unicode, como ASCII ou MBCS, em vez de Unicode.

O valor padrão para essa propriedade sendStringParametersAsUnicode é true.

Para obter um desempenho ideal com os tipos de dados CHAR, VARCHAR e LONGVARCHAR JDBC, o aplicativo deve definir a propriedade sendStringParametersAsUnicode para false e usar os métodos de caracteres não nacionais setString, setCharacterStream e setClob das classes Classe SQLServerPreparedStatement e Classe SQLServerCallableStatement.

Quando o aplicativo define a propriedade sendStringParametersAsUnicode para false e utiliza um método de caractere não nacional para acessar tipos de dados Unicode do lado do servidor (como nchar, nvarchar e ntext), alguns dados poderão ser perdidos caso a ordenação do banco de dados não ofereça suporte aos caracteres nos parâmetros String passados pelo método de caractere não nacional.

Um aplicativo deve usar os métodos de caracteres nacionais setNString, setNCharacterStream e setNClob das classes SQLServerPreparedStatement Class e SQLServerCallableStatement Class para os tipos de dados JDBC NCHAR, NVARCHAR e LONGNVARCHAR.

Alterar esse valor pode afetar a classificação dos resultados do banco de dados. As diferenças de classificação se devem a regras de classificação diferentes para caracteres Unicode versus não Unicode.

sendTemporalDataTypesAsStringForBulkCopy

• Tipo: Boolean [true | false]
• Padrão: true

(Versão 8.4+) Quando você define essa propriedade de conexão como false, o driver envia DATE, DATETIME, DATETIME2, DATETIMEOFFSET, SMALLDATETIMEe TIME tipos de dados como seus respectivos tipos em vez de enviá-los como String.

Quando você define essa propriedade de conexão como false, o driver aceita o formato literal de cadeia de caracteres padrão de cada tipo de dados temporal, por exemplo:

• 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

• Tipo: Boolean [true | false]
• Padrão: true

Essa propriedade foi adicionada ao JDBC Driver 3.0 para SQL Server.

• Defina como true para enviar valores java.sql.Time para o servidor como valores SQL Server datetime.

• Defina como false para enviar valores java.sql.Time para o servidor como valores SQL Server time.

O valor padrão dessa propriedade é atualmente true e pode ser alterado em uma versão futura.

Para obter mais informações sobre como o Microsoft JDBC Driver for SQL Server configura valores java.sql.Time antes de enviar ao servidor, consulte Configurando como os valores java.sql.Time são enviados.

certificado do servidor, servidor

• Tipo: String
• Padrão: null

(Versão 11.2.0+) O caminho para o arquivo de certificado do servidor. O driver usa esse certificado para validação quando você define encrypt como strict. O driver dá suporte a arquivos de certificado que usam o formato de arquivo PEM.

nome do servidor, server

• Tipo: String
• Padrão: null

O computador que está executando o SQL Server ou um banco de dados SQL do Azure.

Você também pode especificar o Nome da Rede Virtual de um grupo de disponibilidade.

Para obter mais informações sobre a recuperação de desastre, confira Suporte ao JDBC Driver para obter Alta Disponibilidade e Recuperação de Desastre.

serverNameAsACE

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 6.0+) Defina para true indicar que o driver deve traduzir o nome do servidor Unicode para codificação compatível com ASCII (Punycode) para a conexão. Se essa configuração for false, o driver usará o nome do servidor conforme fornecido para se conectar.

Para obter mais informações sobre recursos internacionais, confira o artigo Recursos internacionais do driver JDBC.

serverPreparedStatementDiscardThreshold

• Tipo: int
• Padrão: 10

(Versão 6.2+) Use essa propriedade para controlar quantas ações de descarte de instrução preparada pendente (sp_unprepare) podem ser pendentes por conexão antes que o driver limpe as alças pendentes no servidor.

Se você definir essa propriedade como <= 1, o driver executará imediatamente ações despreparadas no fechamento da instrução preparada. Se você definir a propriedade como > 1, o driver agrupa essas chamadas para evitar a sobrecarga de chamar sp_unprepare com muita frequência.

serverSpn

• Tipo: String
• Padrão: null

(Versão 4.2+) Use essa propriedade opcional para especificar o SPN (Nome da Entidade de Serviço) para uma conexão kerberos Java. Use-o com authenticationScheme.

Para especificar o SPN, use o formato: MSSQLSvc/fqdn:port@REALM onde fqdn é o nome de domínio totalmente qualificado, porta é o número da porta e REALM é o domínio Kerberos do SQL Server em letras maiúsculas.

Para obter mais informações sobre como usar serverSpn com Java Kerberos, consulte Using Kerberos integrated authentication to connect to SQL Server.

socketFactoryClass

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica o nome da classe para uma fábrica de soquetes personalizada a ser usada em vez da fábrica de soquetes padrão.

socketTimeout

• Tipo: int
• Padrão: 0

O número de milissegundos a aguardar antes que um tempo limite ocorra em um soquete lido ou aceito. O valor padrão é 0, que significa tempo limite infinito.

statementPoolingCacheSize

• Tipo: int
• Padrão: 0

(Versão 6.4+) Use esta propriedade para habilitar o cache de declarações preparadas no driver.

Essa propriedade define o tamanho do cache para o pool de instruções.

Use essa propriedade somente com a disableStatementPooling propriedade de conexão, que você deve definir como false. A configuração disableStatementPooling para true ou statementPoolingCacheSize para 0 desabilita o cache do identificador de instrução preparado.

Sslprotocol

• Tipo: String
• Padrão: TLS

(Versão 6.4+) Use essa propriedade para especificar o protocolo TLS a ser considerado durante a conexão segura.

Os valores possíveis são: TLS, TLSv1, TLSv1.1, e TLSv1.2.

Para obter mais informações sobre o protocolo SSL, confira SSLProtocol.

transparentNetworkIPResolution

• Tipo: Boolean [true | false]
• Padrão: true

(Versão 6.0+) Essa propriedade fornece detecção e conexão mais rápidas com o servidor ativo. Defina-o como true ou false. O valor padrão é true.

Antes de Microsoft JDBC Driver 6.0 para SQL Server, um aplicativo precisava definir o cadeia de conexão para incluir multiSubnetFailover=true para indicar que ele estava se conectando a um Grupo de Disponibilidade AlwaysOn. Sem definir a multiSubnetFailover palavra-chave de conexão true, um aplicativo pode sofrer um tempo limite ao se conectar a um Grupo de Disponibilidade Always On. A partir da versão 6.0, não é mais necessário que um aplicativo defina multiSubnetFailover para true.

Quando transparentNetworkIPResolution=true, a primeira tentativa de conexão usa 500 ms como o tempo limite. Todas as tentativas posteriores usam a mesma lógica de tempo limite usada pela multiSubnetFailover propriedade.

trustManagerClass

• Tipo: String
• Padrão: null

(Versão 6.4+) O nome de classe totalmente qualificado de uma implementação de javax.net.ssl.TrustManager personalizada.

trustManagerConstructorArg

• Tipo: String
• Padrão: null

(Versão 6.4+) Um argumento opcional a ser passado para o construtor do TrustManager. Se você especificar a trustManagerClass propriedade e solicitar uma conexão criptografada, o driver usará o TrustManager personalizado em vez do TrustManager baseado em repositório de chaves JVM do sistema padrão.

Trustservercertificate

• Tipo: Boolean [true | false]
• Padrão: false

Defina para true especificar que o driver não valida o certificado TLS/SSL do servidor.

• Se true, o certificado TLS/SSL do servidor será considerado confiável automaticamente quando a camada de comunicação for criptografada com TLS.

• Se false, o driver validará o certificado TLS/SSL do servidor. Em caso de falha na validação do certificado do servidor, o driver vai gerar um erro e fechar a conexão. O valor padrão é false. Verifique se o valor passado para serverName corresponde exatamente ao nome CN (Nome Comum) ou nome DNS no campo Subject Alternative Name no certificado do servidor, para que a conexão TLS/SSL tenha sucesso.

Para obter mais informações sobre suporte à criptografia, confira Noções básicas sobre suporte à criptografia.

Truststore

• Tipo: String
• Padrão: null

O caminho (incluindo o nome do arquivo) para o arquivo de certificado trustStore . O trustStore arquivo contém a lista de certificados que o cliente confia.

Quando você não especifica essa propriedade ou a define como nula, o driver usa as regras de pesquisa da fábrica do gerenciador de confiança para decidir qual repositório de certificados usar.

O SunX509 TrustManagerFactory padrão tenta encontrar o material confiável na seguinte ordem de pesquisa:

1. Um arquivo especificado pela propriedade do javax.net.ssl.trustStore sistema JVM.
2. Arquivo <java-home>/lib/security/jssecacerts.
3. Arquivo <java-home>/lib/security/cacerts.

Para obter mais informações sobre a Interface SUNX509 TrustManager, confira a documentação da Interface SUNX509 TrustManager no site da Sun Microsystems.

Truststorepassword

• Tipo: String
• Padrão: null

A senha usada para verificar a integridade dos trustStore dados.

Se você definir a trustStore propriedade, mas não definir a trustStorePassword propriedade, o driver não verificará a integridade do trustStore.

Quando você não especifica as propriedades trustStore e trustStorePassword, o driver usa as propriedades do sistema JVM, javax.net.ssl.trustStore e javax.net.ssl.trustStorePassword. Se você não especificar a propriedade do javax.net.ssl.trustStorePassword sistema, o driver não verificará a integridade do trustStore.

Se você não definir a trustStore propriedade, mas definir a trustStorePassword propriedade, o driver JDBC usará o arquivo especificado javax.net.ssl.trustStore como um repositório de confiança. O driver verifica a integridade do repositório de confiança usando o especificado trustStorePassword. Essa configuração é necessária quando o aplicativo cliente não quiser armazenar a senha na propriedade do sistema da JVM.

trustStoreType

• Tipo: String
• Padrão: JKS

Defina essa propriedade para especificar o tipo de repositório confiável a ser usado para o modo FIPS.

Os valores possíveis são PKCS12 ou tipo definido pelo provedor FIPS.

useBulkCopyForBatchInsert

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 9.2+) Quando você habilita essa propriedade de conexão, o driver usa de forma transparente a API de Cópia em Massa para operações de inserção em lote que usam java.sql.PreparedStatement. Esse recurso pode fornecer melhor desempenho.

Por padrão, esse recurso está desabilitado. Defina esta propriedade como true para habilitá-la.

Para obter mais informações sobre como usar essa propriedade, consulte Usando a API de cópia em massa para a operação de inserção em lote.

useDefaultGSSCredential

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.6+) Sinalizador para indicar se o driver deve criar o GSSCredential em nome do usuário para usar a API do GSS nativa para autenticação Kerberos.

useDefaultJaasConfig

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 12.6+) Quando o aplicativo existir junto com bibliotecas que configuram o JAAS no nível do sistema, defina essa propriedade para true permitir que o driver use essa mesma configuração para executar a autenticação Kerberos.

useFmtOnly

• Tipo: Boolean [true | false]
• Padrão: false

(Versão 7.4+) Fornece um modo alternativo de consultar metadados de parâmetro do servidor. Defina essa propriedade para true para especificar que o driver deve usar a lógica SET FMTONLY ao consultar metadados de parâmetro. Esse recurso está desativado por padrão. Além disso, não recomendamos usar essa propriedade, pois SET FMTONLY está marcado para substituição. useFmtOnly é disponibilizado para uso apenas como uma solução alternativa para problemas conhecidos e limitações em sp_describe_undeclared_parameters.

No momento, esse recurso dá suporte apenas a consultas SELECT/INSERT/UPDATE/DELETE únicas. A tentativa de usar esse recurso com consultas sem suporte/várias faz com que o driver tente analisar a consulta, mas provavelmente resulta em uma exceção.

Para obter mais informações sobre essa propriedade, consulte Recuperando ParameterMetaData via useFmtOnly.

userName, usuário

• Tipo: String [<=128 char]
• Padrão: null

O usuário do banco de dados, caso você se conecte usando um usuário SQL e uma senha.

Para a conexão Kerberos usando o nome principal e a senha, defina essa propriedade como o nome principal Kerberos.

(Versão 10.2+) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade userName especifica uma ID de cliente segura Microsoft Entra válida.

vectorTypeSupport

• Tipo: String [v2 | v1 | off]
• Padrão: v1

(Versão 13.2+) Defina off para especificar que o servidor envia tipos de vetor como dados de cadeia de caracteres no formato JSON e v1 para especificar que o servidor envia tipos de vetor de FLOAT32 como dados de vetor. O valor padrão é v1.

(Versão 13.4+) Defina como v2 para habilitar o suporte nativo do tipo vetor para os vetores FLOAT32 e FLOAT16. FLOAT16 vetores usam a serialização de meia precisão IEEE-754 no fio e são expostos como matrizes Float[] em Java.

Para obter mais informações, consulte Usar o tipo de dados de vetor com o driver JDBC.

Workstationid

• Tipo: String [<=128 char]
• Padrão: <empty string>

A ID da estação de trabalho. Use essa ID para identificar a estação de trabalho específica em várias ferramentas de criação de perfil e registro em log.

Se você não especificar um valor, o padrão será <empty string>.

xopenStates

• Tipo: Boolean [true | false]
• Padrão: false

Defina para true para especificar que o driver retorna códigos de estado compatíveis com XOPEN em exceções.

O padrão é retornar códigos de estado SQL 99.

Conteúdo relacionado

• Conectar ao SQL Server com o JDBC Driver
• Modo FIPS