Definir as propriedades de ligação

Baixar driver JDBC

Pode especificar as propriedades da cadeia de ligação de várias formas:

• Como propriedades em <name>=<value> na URL de ligação ao usar a classe DriverManager. Para obter a sintaxe da cadeia de conexão, consulte Criando 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 das propriedades são indiferentes a maiúsculas minúsculas. O driver resolve nomes duplicados de propriedades na seguinte ordem:

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

• Pode usar valores desconhecidos para nomes de propriedades. O driver JDBC não valida a sensibilidade a maiúsculas e minúsculas.

• Podes usar sinónimos. O driver resolve-os por ordem, tal como faz com nomes de propriedades duplicados.

• O Microsoft JDBC Driver para SQL Server assume os valores predefinidos do servidor para as propriedades da ligação, exceto ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. O Microsoft JDBC Driver para SQL Server define automaticamente ANSI_DEFAULTS para ON e IMPLICIT_TRANSACTIONS para OFF.

• Se definir a autenticação para ActiveDirectoryPassword [DEPRECATED], inclua a seguinte biblioteca na classpath: microsoft-authentication-library-for-java. Encontra-o no Maven Repository. A maneira mais simples de baixar a biblioteca e suas dependências é usando o Maven:

  1. Instala o Maven no teu sistema.
  2. Visite a página GitHub do driver.
  3. Descarregue o pom.xml ficheiro.
  4. Execute o seguinte comando Maven para descarregar a biblioteca e as suas dependências: mvn dependency:copy-dependencies.

Propriedades

As secções seguintes descrevem todas as propriedades de cadeia de ligação atualmente disponíveis 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. Não podes definir accessToken usando a URL da ligação.

accessTokenCallbackClass

• Tipo: String
• Padrão: null

(Versão 12.4+) O nome da classe de implementação de callback a usar com o callback do token de acesso.

Intenção de aplicação

• Tipo: String
• Padrão: ReadWrite

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

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

Para obter mais informações sobre recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

Nome da aplicação

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

O nome da aplicação, ou "Microsoft JDBC Driver for SQL Server" se não fornecer um nome.

Use este nome para identificar a aplicação específica em várias ferramentas de perfilagem e registo 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, ActiveDirectoryManagedIdentity (versão 12.2+), ActiveDirectoryMSI (versão 7.2+), ActiveDirectoryInteractive (versão 9.2+), ActiveDirectoryServicePrincipal (versão 9.2+), ActiveDirectoryPassword [DEPRECATED], SqlPassword, e o padrão NotSpecified.

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

Use ActiveDirectoryManagedIdentity (versão 12.2+) ou ActiveDirectoryMSI (versão 7.2+) para se ligar ao SQL a partir de um recurso Azure. Por exemplo, uma Azure Virtual Machine, App Service ou Function App usando autenticação de identidade gerida.

Os dois tipos de identidades geridas suportadas pelo driver ao utilizar ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI modo de autenticação são:

• Identidade Gerida pelo Sistema: Usada para adquirir accessToken por padrão.

• Identidade Gerida Atribuída pelo Utilizador: Usada para adquirir accessToken se o ID do Cliente de uma identidade gerida estiver especificado com a propriedade de ligação msiClientId.

Use ActiveDirectoryInteractive para se ligar a uma base de dados através de um fluxo interativo de autenticação.

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

Use ActiveDirectoryServicePrincipalCertificate (versão 12.4+) para se ligar a uma base de dados usando o ID do cliente e o certificado da identidade do principal de serviço. Especifique o ID do cliente na userName propriedade e o caminho para o certificado na clientCertificate propriedade.

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

Use ActiveDirectoryPassword [DEPRECATED] para ligar ao SQL usando um nome principal Microsoft Entra e palavra-passe.

O ActiveDirectoryPassword está obsoleto.

Para obter mais informações, consulte conectar-se utilizando o modo de autenticação "ActiveDirectoryPassword".

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

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

Quando define a propriedade de autenticação para qualquer valor que não seja NotSpecified, o driver utiliza a criptografia Transport Layer Security (TLS), anteriormente conhecida como Secure Sockets Layer (SSL), por padrão.

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

Esquema de autenticação

• Tipo: String
• Padrão: NativeAuthentication

Indica que tipo de segurança integrada você deseja que 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 integradas de autenticação.

(A biblioteca de autenticação nativa carregada é nomeada sqljdbc_auth.dll quando se utilizam as versões 6.0 a 7.4.)

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

Para mais informações sobre o uso de authenticationScheme=JavaKerberos, consulte Usando autenticação integrada Kerberos para se ligar a SQL Server.

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

cópiaEmMassaParaInserçãoEmLotePermitirModificaçõesDeValoresCriptografados

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

(Versão 12.10+) Quando definir useBulkCopyForBatchInsert para true, defina esta opção para true permitir a cópia em massa de dados encriptados entre tabelas ou bases de dados, sem desencriptar 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 defines useBulkCopyForBatchInsert para true, esta propriedade especifica o tamanho do lote para operações de cópia em massa que o driver cria a partir das 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+) Quando usar useBulkCopyForBatchInsert=true, defina esta opção para true ativar restrições de verificação ao inserir dados. Defina esta opção para false para desativar 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+) Quando usar useBulkCopyForBatchInsert=true, defina esta opção para true para permitir o disparo dos gatilhos de inserção enquanto se inserem linhas na base de dados. Defina esta opção para false para desativar os 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+) Quando usar useBulkCopyForBatchInsert=true, defina esta opção para true preservar os valores de identidade de origem ao inserir dados. Defina a opção para false para atribuir valores de identidade pelo destino especificado.

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+) Quando usar useBulkCopyForBatchInsert=true, defina esta opção para true preservar os valores nulos na tabela de destino, independentemente das definições de valores padrão. Defina esta opção para false para permitir que os valores predefinidos de destino substituam os 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 definires useBulkCopyForBatchInsert para true, define esta opção para true obter um bloqueio de atualização em massa durante a operação de cópia em massa. Defina esta opção para false para usar bloqueios de linhas.

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, esta propriedade indica ao driver se deve armazenar em cache os metadados da coluna de destino ao nível da ligação. Se definido como true, certifique-se de que o destino não mude entre inserções em massa, pois o driver não tem como lidar com essa alteração.

calcBigDecimalPrecision

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

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

cancelQueryTimeout

• Tipo: int
• Padrão: -1

(Versão 6.4+) Use esta propriedade para cancelar uma definição queryTimeout na ligação. A execução da consulta deixa de responder e não gera uma exceção se a ligação TCP ao servidor for interrompida silenciosamente. Esta propriedade só se aplica se queryTimeout também estiver definida na ligação.

O condutor espera o total de cancelQueryTimeout + queryTimeout segundos para cortar a ligação e fechar o canal.

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

Certificado do cliente

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica a localização do certificado a usar para a autenticação do certificado do cliente. O driver JDBC suporta extensões de arquivo PFX, PEM, DER e CER.

Para obter detalhes, consulte a autenticação do certificado de cliente para cenários de loopback .

clientKey

• Tipo: String
• Padrão: null

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

Para obter detalhes, consulte a autenticação do certificado de cliente para cenários de loopback .

clientKeyPassword

• Tipo: String
• Padrão: null

(Versão 8.4+) Especifica a cadeia de palavra-passe opcional para aceder à clientKey chave privada do ficheiro.

Para obter detalhes, consulte a autenticação do certificado de cliente para cenários de loopback .

columnEncryptionSetting

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

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

Para 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 defines esta opção para OFF, o driver define a variável CONCAT_NULL_YIELDS_NULL da sessão da base de dados para OFF quando estabelece a ligação. O resultado é que concatenar um valor nulo com uma cadeia de caracteres produz a própria cadeia de caracteres (o valor nulo é tratado como uma cadeia de caracteres vazia).

Para obter mais informações, consulte SET CONCAT_NULL_YIELDS_NULL.

connectRetryCount

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

(Versão 9.4+) O número de tentativas de reconexão se houver uma falha de conexão.

connectRetryInterval

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

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

databaseName, base de dados

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

O nome do banco de dados ao qual se conectar.

Se não especificares o nome da base de dados, a ligação usa a base de dados padrão.

datetimeParameterType

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

(Versão 12.2+) O tipo de dado SQL a usar para parâmetros de data e carimbo temporal em Java.

Quando se ligar ao SQL Server 2016 ou versões posteriores e interagir com valores antigos datetime, defina esta propriedade para datetime. Esta configuração mitiga problemas de conversão do lado do servidor entre valores datetime e datetime2.

Para obter mais informações, consulte Mudança de comportamento de conversão de datetime para datetime2 a partir de SQL Server 2016.

delayLoadingLobs

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

Flag para indicar se deve transmitir todos os objetos LOB recuperados do ResultSet. Definir esta propriedade para false carregar todo o objeto LOB na memória sem fazer streaming.

DesativarStatementPooling

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

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

Nome de domínio, domínio

• Tipo: String
• Padrão: null

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

ActivarPreparaçãoNaPrimeiraChamadaPrepareStatement

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

Defina como true para permitir a criação de um handle de prepared statement ao chamar sp_prepexec durante a primeira execução de um prepared statement.

Defina false para que a primeira execução de uma instrução preparada chame sp_executesql e não prepare uma instrução. Se uma segunda execução acontecer, ele chama sp_prepexec para configurar um identificador de instrução preparado.

enclaveAttestationProtocol

• Tipo: String
• Padrão: null

(Versão 8.2+) Esta propriedade opcional indica o protocolo de atestado a ser usado para Always Encrypted com enclaves seguros. Atualmente, os únicos valores suportados para este campo são HGS, AAS, e NONE (NONE só é suportado na versão 11.2+).

Para mais informações sobre o Always Encrypted com enclaves seguros, veja Utilização Sempre Encriptada com enclaves seguros com o driver JDBC.

enclaveAttestationUrl

• Tipo: String
• Padrão: null

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

Para mais informações sobre o Always Encrypted com enclaves seguros, veja Utilização Sempre Encriptada com enclaves seguros com o driver JDBC.

criptografar

• Tipo: String
• Padrão: null

Definido para true para especificar que o Database Engine SQL usa encriptação TLS para todos os dados enviados entre o cliente e o servidor, caso o servidor tenha um certificado instalado. O valor padrão é true na versão 10.2 e posteriores e false na versão 9.4 e anteriores.

Na versão 6.0 em diante, há uma nova configuração authentication de ligação que usa encriptação TLS por defeito.

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

Na versão 11.2.0 e posteriores, encrypt foi alterado de Boolean para string, permitindo suporte a TDS 8.0 quando a propriedade está definida para strict.

A mudança padrão na versão 10.2 é uma mudança disruptiva. Se estiver a atualizar da versão 9.4 ou anterior e o seu servidor não tiver um certificado TLS válido, defina trustServerCertificate ou true forneça um certificado válido.

failoverPartner

• Tipo: String
• Padrão: null

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

Se especificar um nome de Rede Virtual na propriedade de ligação Server, não pode usar espelhamento de base de dados.

Para obter mais informações sobre recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

FIPS

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

Defina esta propriedade para true para Java Virtual Machine (JVM) com FIPS.

fipsProvider

• Tipo: String
• Padrão: null

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

Para obter mais informações, consulte edição 460 do GitHub.

GSS credencial

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

(Versão 6.2+) Passe as credenciais de utilizador para a Delegação Restrita de Kerberos nesta propriedade.

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

HostNameInCertificate

• Tipo: String
• Padrão: null

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

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

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

Use esta propriedade em combinação com a encrypt, a authentication e a trustServerCertificate propriedade. Esta propriedade afeta a validação do certificado se a ligação usar encriptação TLS e o trustServerCertificate for definido para false. Certifique-se de que o valor que passa para hostNameInCertificate corresponde ao Nome Comum (CN) ou ao nome DNS no Nome Alternativo do Assunto (SAN) no certificado do servidor para que uma ligação TLS tenha sucesso.

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

instanceName

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

O nome da instância do banco de dados ao qual se conectar. Quando não especificas esta propriedade, ligas-te à instância predefinida. Para o caso em que especifica tanto o instanceName e o port, veja as notas para port.

Se especificar um nome Rede Virtual na propriedade de ligação Server, não pode usar a propriedade de ligação instanceName.

Para obter mais informações sobre recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

Segurança integrada

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

Definido para true para indicar que as credenciais do Windows são usadas pelo SQL Server nos sistemas operativos Windows. Se true, o driver JDBC pesquisa na cache local de credenciais do computador as credenciais que foram fornecidas quando um utilizador iniciou sessão no computador ou na rede.

Definido para 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 Kerberos, consulte Usando a autenticação integrada Kerberos para se conectar ao SQL Server.

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

Se false, o nome de utilizador e a palavra-passe devem ser fornecidos.

preferência de endereço IP

• 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 continuará e tentará endereços IPv6, se houver.

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

Com o UsePlatformDefault, o driver percorre todos os endereços IP nas suas ordens iniciais a partir 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 nome de Configuração de Logon JAAS para estabelecer uma conexão Kerberos. Pode passar o nome da entrada de configuração através desta propriedade. Use esta propriedade ao criar um ficheiro de configuração Kerberos. Por padrão, o driver procura o nome SQLJDBCDriver.

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

keyStoreAuthentication

• Tipo: String
• Padrão: null

(Versão 6.0+) Esta propriedade identifica qual armazenamento de chaves usar com o Always Encrypted e define o mecanismo de autenticação a ser utilizado para aceder ao armazenamento de chaves. O driver suporta configurar a Java Key Store de forma fluida quando defines keyStoreAuthentication=JavaKeyStorePassword. Para usar esta propriedade, também deve definir as propriedades keyStoreLocation e keyStoreSecret para a Java Key Store.

A partir do Microsoft JDBC Driver 8.4, pode definir keyStoreAuthentication=KeyVaultManagedIdentity ou keyStoreAuthentication=KeyVaultClientSecret para autenticar a Azure Key Vault usando Identidades Geridas.

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

keyStoreLocalização

• Tipo: String
• Padrão: null

(Versão 6.0+) Quando keyStoreAuthentication=JavaKeyStorePassword, a propriedade keyStoreLocation identifica o caminho para o ficheiro Java keystore que armazena a Chave Mestra da Coluna para usar com dados Always Encrypted. O caminho deve incluir o nome do arquivo keystore.

Para 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 um ID de cliente de aplicação Microsoft Entra válido.

Para 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 palavra-passe a usar para o armazenamento de chaves e a chave. Quando usas o Java Key Store, o keystore e a palavra-passe da chave devem ser iguais.

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

ContagemDaÚltimaAtualização

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

Um true valor devolve apenas a última contagem de atualizações de uma instrução SQL que passa para o servidor. Use este valor apenas com instruções simples SELECT, INSERT, ou DELETE para ignorar outras contagens de atualizações que os gatilhos do servidor possam causar. Defina esta propriedade para false devolver todas as contagens de atualizações, incluindo aquelas que o servidor aciona return.

lockTimeout

• Tipo: int
• Padrão: -1

O número de milissegundos a aguardar antes que a base de dados indique um tempo limite de bloqueio. O comportamento padrão é aguardar indefinidamente. Se não especificar um valor para esta propriedade, esse valor é o padrão para todas as instruções na ligação.

Alternativamente, utilize Statement.setQueryTimeout() para definir o tempo limite da consulta para instruções específicas. O valor pode ser 0, o que especifica não esperar.

loginTimeout

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

O número de segundos que o controlador deve esperar antes de interromper uma conexão com falha. Um valor zero indica que o tempo limite é o tempo limite padrão do sistema. Este valor é ou 30 segundos (o padrão na versão 11.2 e posteriores) ou 15 segundos (o padrão na versão 10.2 e anteriores). Um valor não nulo é o número de segundos que o driver deve aguardar antes de atingir o tempo limite de uma conexão com falha.

Se especificar um Nome de Rede Virtual na propriedade de ligação Server, especifique um valor de tempo limite de três minutos ou mais para permitir tempo suficiente para que uma ligação em modo de contingência tenha sucesso.

Para obter mais informações sobre recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

maxResultBuffer

• Tipo: String
• Padrão: null

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

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

msiClientId

• Tipo: String
• Padrão: null

(Descontinuado) (Versão 7.2+) O ID do Cliente da Identidade Gerida (MSI) é usado para adquirir um accessToken para estabelecer uma ligação usando o modo de autenticação ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI.

multiSubnetFailover

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

Especifique sempre multiSubnetFailover=true para se ligar ao ouvinte do grupo de disponibilidade do SQL Server ou a uma Instância de Cluster de Failover do SQL Server. multiSubnetFailover=true Configura o driver para proporcionar uma deteção e ligação mais rápidas ao servidor ativo.

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

Para obter mais informações sobre recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

Pode aceder programaticamente à multiSubnetFailover propriedade de ligação usando getPropertyInfo, getMultiSubnetFailover e setMultiSubnetFailover.

pacoteTamanho

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

O tamanho do pacote de rede usado para se comunicar com o servidor, especificado em bytes. Um valor de -1 indica usar o tamanho de pacote padrão do servidor. Um valor de 0 indica usar o valor máximo de 32767. Se definir esta propriedade para um valor fora do intervalo aceitável, ocorre uma exceção.

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

palavra-passe

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

A palavra-passe da base de dados, se te ligares a um utilizador SQL e à palavra-passe.

Para a ligação Kerberos com nome principal e palavra-passe, defina esta propriedade para a palavra-passe Kerberos Principal.

(Versão 10.2+) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade password identifica a palavra-passe a usar para o principal Active Directory.

númeroDePorta, porta

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

A porta onde o servidor está escutando. Se especificar o número de porta na cadeia de ligação, não é feito qualquer pedido ao SQLbrowser. Quando especificas tanto a porta como instanceName, a ligação é feita à porta especificada. No entanto, o instanceName é validado e, caso não coincida com a porta, um erro é gerado.

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 condutor utiliza com instruções preparadas.

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

(Versão 13.4.0+) Defina para scopeTempTablesToConnection para restringir as tabelas temporárias criadas em instruções preparadas à conexão, usando substituição literal de parâmetros em vez de handles preparados do lado do servidor. Defina como none para impor a substituição literal de parâmetros na execução de SQL em lote, contornando os manipuladores de instruções preparadas do lado do servidor (sp_prepexec / sp_prepare).

Limitações e avisos legais para scopeTempTablesToConnection e none:

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

• Sem declarações preparadas do lado do servidor; O SQL é sempre executado em batch.
• Requer FORCED_PARAMETERIZATION para uma reutilização eficaz do plano.
• Os parâmetros são inlinados como literais em vez de tipos vinculados.
• A precisão numérica e a escala podem diferir da ligação de parâmetros do lado do servidor.
• Os valores de data e hora são formatados como cadeias de caracteres pelo condutor.
• Parâmetros de strings grandes aumentam o tamanho do texto SQL e o uso de memória.
• Os parâmetros BLOB e CLOB podem causar um uso elevado de memória ou condições de falta de memória.
• O SQL Server deduz os tipos de dados dos parâmetros durante a análise do SQL.
• Os planos de consulta podem variar devido a diferenças nos valores literais.
• Os erros são detetados em tempo de execução em vez de em tempo de ligação.
• O SQL que é executado inclui valores literais e está visível em rastros e registos de servidor.

queryTimeout

• Tipo: int
• Padrão: -1

O número de segundos a aguardar antes que um tempo limite ocorra numa consulta. O valor padrão é -1, o que significa tempo limite infinito. Definir esse valor como 0 também implica aguardar indefinidamente.

quotedIdentifier

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

(Versão 13.2+) Quando defines esta opção para OFF, o driver define a variável QUOTED_IDENTIFIER da sessão da base de dados para OFF quando estabelece a ligação. A base de dados trata as aspas duplas como delimitadores de cadeias de caracteres para literais de carácter, e você não pode colocar identificadores entre aspas duplas.

Para obter mais informações, consulte SET QUOTED_IDENTIFIER.

Domínio

• Tipo: String
• Padrão: null

(Versão 9.4+) O domínio para autenticação Kerberos. Defina este valor para substituir o domínio de autenticação Kerberos que o driver deteta automaticamente do domínio do servidor.

Replicação

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

(Versão 9.4+) Essa configuração informa ao servidor se a conexão é usada para replicação. Quando ativado, 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 definires esta propriedade para adaptive, o driver armazena a quantidade mínima de dados quando necessário. O modo padrão é adaptive.

Se definires esta propriedade para full, o driver lê todo o conjunto de resultados do servidor quando executa uma instrução.

selectMethod

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

Se definires esta propriedade para cursor, o driver cria um cursor de base de dados para cada consulta que cria na ligação para TYPE_FORWARD_ONLY e CONCUR_READ_ONLY cursores. Normalmente, só precisa desta propriedade se a sua aplicação gerar grandes conjuntos de resultados que não cabem inteiramente na memória do cliente. Se definires esta propriedade para cursor, o driver mantém apenas um número limitado de linhas de conjunto de resultados na memória do cliente.

Por defeito, o driver mantém todas as linhas do conjunto de resultados na memória do cliente. Este comportamento padrão proporciona o desempenho mais rápido quando a aplicação processa todas as linhas.

sendStringParametersAsUnicode

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

Se definires a sendStringParametersAsUnicode propriedade para true, o driver envia parâmetros de string para o servidor em formato Unicode.

Se definires a sendStringParametersAsUnicode propriedade para false, o driver envia parâmetros de string para o servidor em formatos não Unicode, como ASCII ou MBCS em vez de Unicode.

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

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

Quando a aplicação define a sendStringParametersAsUnicode propriedade para false e utiliza um método de caracteres não nacionais para aceder aos tipos de dados Unicode do lado do servidor (como nchar, nvarchar, e ntext), alguns dados podem perder-se se a colação da base de dados não suportar os caracteres nos String parâmetros passados pelo método de caracteres não nacionais.

Uma aplicação deve utilizar os métodos setNString, setNCharacterStream e setNClob de caracteres nacionais das classes SQLServerPreparedStatement e SQLServerCallableStatement para os tipos de dados NCHAR, NVARCHAR e LONGNVARCHAR JDBC.

A alteração desse valor pode afetar a classificação dos resultados do banco de dados. As diferenças de classificação são devidas a diferentes regras de classificação para caracteres Unicode versus não-Unicode.

sendTemporalDataTypesAsStringForBulkCopy

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

(Versão 8.4+) Quando define esta propriedade de ligação para false, o driver envia DATE, DATETIME, DATETIME2, DATETIMEOFFSET, SMALLDATETIME, e TIME tipos de dados como os seus respetivos tipos em vez de os enviar como String.

Quando definir esta propriedade de ligação para false, o driver aceita o formato literal da cadeia padrão de cada tipo de dado 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

Esta propriedade foi adicionada no SQL Server JDBC Driver 3.0.

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

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

O valor padrão desta propriedade é atualmente true e pode mudar numa versão futura.

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

serverCertificate, servidor

• Tipo: String
• Padrão: null

(Versão 11.2.0+) O caminho para o arquivo de certificado do servidor. O driver usa este certificado para validação quando defines encrypt para strict. O driver suporta ficheiros de certificado que utilizam o formato PEM.

Nomedo do servidor, servidor

• Tipo: String
• Padrão: null

O computador que executa 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 recuperação de desastres, consulte suporte do driver JDBC para Alta Disponibilidade, recuperação de desastres.

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 ligação. Se esta definição for false, o driver usa o nome do servidor fornecido para se ligar.

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

serPreparedStatementDiscardThreshold

• Tipo: int
• Padrão: 10

(Versão 6.2+) Use esta propriedade para controlar quantas ações pendentes de descarte de declarações preparadas (sp_unprepare) podem estar pendentes por ligação antes do driver limpar os manipuladores pendentes no servidor.

Se definir esta propriedade para <= 1, o condutor executa imediatamente as ações de despreparação no encerramento da declaração preparada. Se definir a propriedade para > 1, o driver agrupa estas invocações para evitar a sobrecarga de chamadas a sp_unprepare muito frequentemente.

serverSpn

• Tipo: String
• Padrão: null

(Versão 4.2+) Use esta propriedade opcional para especificar o Nome Principal do Serviço (SPN) para uma ligação Java Kerberos. Use-o com authenticationScheme.

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

Para mais informações sobre o uso de serverSpn com Java Kerberos, consulte Usando autenticação integrada Kerberos para ligar ao 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 usar em vez da fábrica de soquetes padrão.

socketTimeout

• Tipo: int
• Padrão: 0

O número de milissegundos a esperar antes de ocorrer um timeout numa leitura ou aceitação de soquete. O valor padrão é 0, o que significa tempo limite infinito.

statementPoolingCacheSize

• Tipo: int
• Padrão: 0

(Versão 6.4+) Use esta propriedade para ativar a cache de instruções preparadas no controlador do driver.

Esta propriedade define o tamanho do cache para agrupamento de instruções.

Use esta propriedade apenas com a disableStatementPooling propriedade de ligação, que deve definir para false. Definir disableStatementPooling como true ou statementPoolingCacheSize como 0 desativa a cache da manipulação de instruções preparadas.

sslProtocol

• Tipo: String
• Padrão: TLS

(Versão 6.4+) Use esta propriedade para especificar o protocolo TLS a considerar durante a ligação segura.

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

Para obter mais informações sobre o protocolo Secure Sockets Layer, consulte SSLProtocol.

transparentNetworkIPResolution

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

(Versão 6.0+) Esta propriedade proporciona uma deteção e ligação mais rápidas ao servidor ativo. Defina para true ou false. O valor predefinido é true.

Antes do Microsoft JDBC Driver 6.0 para SQL Server, uma aplicação tinha de definir a cadeia de conexão para incluir multiSubnetFailover=true para indicar que estava a ligar-se a um Grupo de Disponibilidade Always On. Sem definir a multiSubnetFailover palavra-chave de ligação para true, uma aplicação pode sofrer um timeout ao ligar-se a um Grupo de Disponibilidade Sempre Ativa. A partir da versão 6.0, já não é necessário que uma aplicação defina multiSubnetFailover como true.

Quando transparentNetworkIPResolution=true, a primeira tentativa de ligação usa 500 ms como timeout. Quaisquer tentativas posteriores usam a mesma lógica de timeout usada pela multiSubnetFailover propriedade.

trustManagerClass

• Tipo: String
• Padrão: null

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

trustManagerConstructorArg

• Tipo: String
• Padrão: null

(Versão 6.4+) Um argumento opcional para passar para o construtor do TrustManager. Se especificar a propriedade trustManagerClass e solicitar uma ligação encriptada, o driver utiliza o TrustManager personalizado em vez do TrustManager padrão baseado no keystore da JVM do sistema.

trustServerCertificate

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

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

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

• Se false, o driver valida o certificado TLS/SSL do servidor. Se a validação do certificado do servidor falhar, o driver gerará um erro e fechará a conexão. O valor predefinido é false. Certifique-se de que o valor passado serverName corresponde exatamente ao Nome Comum (CN) ou nome DNS no Nome Alternativo do Sujeito no certificado do servidor para que uma ligação TLS/SSL tenha sucesso.

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

trustStore

• Tipo: String
• Padrão: null

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

Quando não especifica esta propriedade ou não a define como nula, o driver usa as regras de pesquisa do trust manager factory para decidir qual a loja de certificados a usar.

O SunX509 TrustManagerFactory predefinido tenta encontrar o material de confiança na seguinte ordem de pesquisa:

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

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

trustStorePassword

• Tipo: String
• Padrão: null

A palavra-passe usada para verificar a integridade dos trustStore dados.

Se definir a propriedade trustStore mas não definir a propriedade trustStorePassword, o driver não verifica a integridade do trustStore.

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

Se não definires a propriedade trustStore mas definires a trustStorePassword, o driver JDBC utiliza o ficheiro que javax.net.ssl.trustStore especifica como um repositório de confiança. O driver verifica a integridade do armazenamento de confiança usando o elemento especificado trustStorePassword. Essa configuração é necessária quando o aplicativo cliente não deseja armazenar a senha na propriedade do sistema JVM.

trustStoreType

• Tipo: String
• Padrão: JKS

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

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

useBulkCopyForBatchInsert

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

(Versão 9.2+) Quando ativa esta propriedade de ligação, o driver utiliza de forma transparente a API Bulk Copy para operações de inserção em lote que utilizam java.sql.PreparedStatement. Esta funcionalidade pode proporcionar melhor desempenho.

Este recurso está desativado por padrão. Defina esta propriedade para true para o ativar.

Para mais informações sobre como usar esta característica, consulte Utilização da API de cópia em massa para 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 o GSS-API nativo para autenticação Kerberos.

useDefaultJaasConfig

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

(Versão 12.6+) Quando a aplicação existe juntamente com bibliotecas que configuram o JAAS ao nível do sistema, defina esta propriedade para true permitir que o driver use essa mesma configuração para realizar autenticação Kerberos.

useFmtOnly

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

(Versão 7.4+) Fornece uma maneira alternativa de consultar metadados de parâmetro do servidor. Defina esta propriedade para true especificar que o driver deve usar a lógica SET FMTONLY ao consultar Metadados de parâmetros. Esse recurso está desativado por padrão e não é recomendado usar essa propriedade, pois SET FMTONLY está marcada para preterição. useFmtOnly está disponível apenas como solução alternativa para problemas e limitações conhecidas em sp_describe_undeclared_parameters.

Atualmente, esse recurso suporta apenas consultas SELECT/INSERT/UPDATE/DELETE únicas. Tentar usar esta funcionalidade com consultas múltiplas ou não suportadas faz com que o driver tente analisar a consulta, mas muito provavelmente resulta numa exceção.

Para mais informações sobre esta propriedade, veja Recuperar ParameterMetaData via useFmtOnly.

Nome do utilizador, utilizador

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

O utilizador da base de dados, se se ligar usando um utilizador SQL e palavra-passe.

Para a ligação Kerberos usando o nome principal e a palavra-passe, defina esta propriedade para o nome principal Kerberos.

(Versão 10.2+) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade userName especifica um ID de cliente seguro da Microsoft Entra válido.

vectorTypeSupport

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

(Versão 13.2+) Defina para off especificar que o servidor envia tipos de vetores como dados de cadeia em formato JSON e v1 para especificar que o servidor envia tipos vetoriais de FLOAT32 como dados vetoriais. O valor predefinido é v1.

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

Para mais informações, consulte Usar o tipo de dado vetorial com o driver JDBC.

WorkstationID

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

O ID da estação de trabalho. Use este ID para identificar a estação de trabalho específica em várias ferramentas de perfilagem e registo.

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

xopenStates

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

Para especificar que o driver devolve códigos de estado compatíveis com XOPEN em exceções, defina para true.

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

Conteúdo relacionado

• Conectando-se ao SQL Server com o driver JDBC
• modo FIPS