Configuração das propriedades de conexão
As propriedades da cadeia de conexão podem ser especificadas de várias formas:
Como as propriedades name=value na URL de conexão quando você conecta usando a classe DriverManager. Para obter a sintaxe da cadeia de conexão, confira Como criar a URL de conexão.
Como as propriedades name=value 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 propriedade não diferenciam maiúsculas de minúsculas, e os nomes de propriedade duplicados são resolvidos na seguinte ordem:
- Argumentos de API (como usuário e senha)
- Coleção de propriedades
- Última instância na cadeia de conexão
São permitidos valores desconhecidos para os nomes de propriedade e o driver JDBC não valida em relação à diferenciação de maiúsculas de minúsculas.
São permitidos sinônimos, resolvidos na ordem, assim como nomes de propriedade duplicados.
Propriedades
A tabela a seguir lista todas as propriedades da cadeia de conexão disponíveis no momento para o driver JDBC.
| Propriedade Type Padrão |
Descrição |
|---|---|
| accessToken String nulo |
(Versão 6.0+) Use essa propriedade para se conectar a um banco de dados usando um token de acesso. accessToken não pode ser definido usando a URL de conexão. |
| accessTokenCallbackClass Cadeia de caracteres null |
(Versão 12.4 e posteriores) O nome da classe de implementação de callback a ser usada com o callback de token de acesso. |
| applicationIntent String 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 o artigo Suporte ao driver JDBC para obter Alta Disponibilidade e recuperação de desastre. |
| applicationName String [<=128 char] nulo |
O nome do aplicativo ou "Microsoft JDBC Driver para SQL Server" se nenhum nome for fornecido. Usado para identificar o aplicativo específico em várias ferramentas de criação de perfil e de registro em log do SQL Server. |
| autenticação String 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, ActiveDirectoryPassword, ActiveDirectoryManagedIdentity (versão 12.2+), ActiveDirectoryMSI (versão 7.2+), ActiveDirectoryInteractive (versão 9.2+), ActiveDirectoryServicePrincipal (versão 9.2+), SqlPassword e o padrão NotSpecified. Use ActiveDirectoryIntegrated (versão 6.0 ou superior) para se conectar ao SQL usando a autenticação integrada do Windows. Use ActiveDirectoryPassword (versão 6.0+) para se conectar ao SQL usando um nome e uma senha da entidade de segurança do Microsoft Entra. Use ActiveDirectoryManagedIdentity (versão 12.2+) ou ActiveDirectoryMSI (versão 7.2+) para se conectar ao SQL de dentro de um Recurso do Azure. Por exemplo, uma Máquina Virtual do Azure, 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: 1. Identidade Gerenciada Atribuída pelo Sistema: usada para adquirir accessToken por padrão. 2. Identidade Gerenciada Atribuída pelo 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 interativa. Use ActiveDirectoryServicePrincipal (versão 9.2+) para se conectar a um banco de dados usando a ID e o segredo do cliente de uma identidade da entidade de serviço. Especifique a ID do cliente na propriedade userName e o segredo na propriedade password (10.2 ou superior). Use SqlPassword para se conectar ao SQL Server usando as propriedades userName/user and password. Use NotSpecified se nenhum desses métodos de autenticação forem necessários. Importante: caso uma autenticação seja definida como ActiveDirectoryIntegrated, estas duas bibliotecas precisarão ser instaladas: mssql-jdbc_auth-<version>-<arch>.dll (disponível no pacote do driver JDBC) e ADAL.DLL (Biblioteca de Autenticação da Microsoft para SQL Server). A Biblioteca de Autenticação da Microsoft pode ser instalada do Microsoft ODBC Driver for SQL Server ou do Driver do Microsoft OLE DB para SQL Server. O driver JDBC só dá suporte à versão 1.0.2028.318 e posterior para a ADAL.DLL. Observação: quando a propriedade de autenticação estiver definida como qualquer valor diferente de NotSpecified, o driver usará a criptografia TLS, anteriormente conhecida como SSL. Para obter informações sobre como configurar a autenticação do Microsoft Entra, consulte Usar a autenticação do Microsoft Entra |
| authenticationScheme String 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 NativeAuthentication padrão. O NativeAuthentication faz com que o driver mssql-jdbc_auth-<version>-<arch>.dll seja carregado no Windows,(por exemplo, mssql-jdbc_auth-8.2.2.x64.dll) sendo utilizado para obter informações de autenticação integrada. (A biblioteca de autenticação nativa carregada é denominada sqljdbc_auth.dll ao usar as versões 6.0 até 7.4 do driver.)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 de que modo usar o authenticationScheme=JavaKerberos, confira Como usar uma autenticação integrada do Kerberos para se conectar ao SQL Server. Ao usar o authenticationScheme=NTLM, será necessário especificar o domínio do Windows usando o domain ou a propriedade domainName, além de credenciais do Windows nas propriedades user ou userName e a propriedade password. Caso contrário, ocorrerá um erro (as propriedades de conexão devem ser especificadas). |
| cacheBulkCopyMetadata boolean ["true" | "false"] false |
(Versão 12.8+) Ao utilizar o useBulkCopyForBatchInsert=true, essa propriedade é usada para informar ao driver se ele deve armazenar em cache os metadados da coluna de destino no nível da conexão. Se definido como true, certifique-se de que o destino não seja alterado entre as inserções em massa, pois o driver não tem como lidar com essa alteração. |
| calcBigDecimalPrecision boolean ["true" | "false"] false |
(Versão 12.6+) Sinalizador para indicar se o driver deve calcular a precisão para entradas BigDecimal, em vez de usar o valor máximo permitido para precisão (38). |
| cancelQueryTimeout INT -1 |
(Versão 6.4 +) Essa propriedade pode ser usada para cancelar um queryTimeout definido na conexão. A execução da consulta será interrompida e não gerará 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 definido 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 String nulo |
(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 Cadeia de caracteres nulo |
(Versão 8.4+) Especifica o local da chave privada para certificados PEM, DER e CER especificados pelo atributo clientCertificate. Para maiores detalhes, consulte Autenticação de certificado do cliente para cenários de loopback. |
| clientKeyPassword Cadeia de caracteres nulo |
(Versão 8.4 ou superior) Especifica a cadeia de caracteres de senha opcional para acessar a chave privada do arquivo clientKey. Confira mais detalhes em Autenticação de certificado do cliente para cenários de loopback. |
| columnEncryptionSetting String ["Habilitado" | "Desabilitado"] Desabilitado |
(Versão 6.0 +) Define como "Habilitado" para usar o recurso AE (Always Encrypted). 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, confira Como usar o Always Encrypted com um driver JDBC. Observação: Always Encrypted está disponível com o SQL Server 2016 ou versões mais recentes e com o Banco de Dados SQL do Azure. |
| connectRetryCount INT [0 – 255] 1 |
(Versão 9.4 ou superior) O número de tentativas de reconexão quando há uma falha de conexão. |
| connectRetryInterval INT [1 – 60] 10 |
(Versão 9.4 ou superior) O número de segundos entre cada nova tentativa de conexão. |
| databaseName, Banco de Dados String [<=128 char] nulo |
O nome do banco de dados ao qual se conectar. Se não for indicada, será estabelecida uma conexão com o banco de dados padrão. |
| datetimeParameterType String ["datetime" | "datetime2" | "datetimeoffset"] datetime2 |
(Versão 12.2 e superior) O tipo de dados SQL a ser usado para parâmetros de data/carimbo de data do Java. Ao se conectar ao SQL Server 2016 ou superior e interagir com os valores herdados de "datetime", os clientes podem se beneficiar da definição da propriedade como "datetime". Essa configuração atenua os problemas de conversão do lado do servidor entre os valores "datetime" e "datetime2". Para obter mais informações, confira Como lidar com a alteração de comportamento de conversão do datetime para o datetime2 a partir do SQL Server 2016 |
| delayLoadingLobs booleano ["true" | "false"] true |
Sinalizador para indicar se todos os objetos LOB que estão sendo recuperados do ResultSet devem ser transmitidos ou não. Definir essa propriedade como "false" carregará todo o objeto LOB na memória sem streaming. |
| domainName, domínio String nulo |
(Versão 7.4 +) O domínio do Windows para autenticar ao usar a autenticação NTLM. |
| disableStatementPooling booleano ["true" | "false"] true |
O sinalizador indica se o pooling de instruções deve ser usado. |
| enablePrepareOnFirst... PreparedStatementCall booleano ["true" | "false"] false |
Defina como "true" para habilitar a criação do identificador de instrução preparado chamando sp_prepexec na primeira execução da instrução preparada. Defina como “false” para alterar a primeira execução de uma instrução preparada para chamar sp_executesql e não preparar uma instrução. Se ocorrer uma segunda execução, ele chamará sp_prepexec para configurar um identificador de instrução preparado. |
| enclaveAttestationUrl String nulo |
(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, confira o artigo Always Encrypted com enclaves seguros. |
| enclaveAttestationProtocol String nulo |
(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, AAS e NONE (NONE só tem suporte na versão 11.2+). Para obter mais informações sobre o Always Encrypted com enclaves seguros, confira o artigo Always Encrypted com enclaves seguros. |
| encrypt String nulo |
Defina essa opção como "true" para especificar que o SQL Server usa a criptografia TLS em 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 posterior e "false" na 9.4 e anterior. Na versão 6.0 e superior, há uma nova configuração de conexão 'autenticação' que usa a criptografia TLS por padrão. Para obter mais informações sobre essa propriedade, confira a propriedade 'authentication'. Na versão 11.2.0 e posterior, a criptografia foi alterada de booliano para cadeia de caracteres, permitindo o suporte ao TDS 8.0 quando a propriedade é definida como estrita. |
| failoverPartner String nulo |
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. Observação: o driver não é compatível com o número da porta da instância do servidor para a instância do parceiro de failover como parte da propriedade failoverPartner da cadeia de conexão. No entanto, o driver não oferece suporte à especificação das propriedades serverName, instanceName e portNumber da instância do servidor principal e da propriedade failoverPartner da instância do parceiro de failover na mesma cadeia de conexão. Caso especifique o Nome da Rede Virtual na propriedade de conexão Servidor, não será possível usar um espelhamento do banco de dados. Para obter mais informações sobre a recuperação de desastre, confira o artigo Suporte ao driver JDBC para obter Alta Disponibilidade e recuperação de desastre |
fipsbooleano ["true" | "false"] "false" |
Essa propriedade deverá ser definida como true para uma JVM (Máquina Virtual Java) habilitada para o padrão FIPS. |
| fipsProvider String nulo |
Provedor FIPS configurado na JVM. Por exemplo, BCFIPS ou SunPKCS11-NSS. Removido na versão 6.4.0. Para obter mais informações, confira problema 460 do GitHub. |
| gsscredential org.ietf.jgss.GSSCredential nulo |
(Versão 6.2+) As credenciais do usuário a serem usadas para a delegação restrita de Kerberos podem ser passadas nessa propriedade. Essa configuração deve ser usada com integratedSecurity como true e JavaKerberos como authenticationScheme. |
| hostNameInCertificate String nulo |
O nome do host a ser usado para validar o certificado TLS/SSL do SQL Server. A opção hostNameInCertificate pode ser usada para especificar o nome do host em situações em que o nome, ou nomes, usados no certificado não correspondem ao nome passado para a propriedade serverName. 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 é especificada ou é definida como nula, o Microsoft JDBC Driver para SQL Server usa o valor da propriedade serverName na URL de conexão como o nome de host para validar o certificado TLS/SSL do SQL Server. Observação: conforme descrito no parágrafo anterior, não é recomendável definir a opção hostNameInCertificate, a menos que você possa confirmar que o nome ou os nomes no certificado não correspondem aos passados na opção serverName. Observação: essa propriedade é usada em combinação com as propriedades encrypt/authentication e a propriedade trustServerCertificate. Essa propriedade afetará a validação do certificado caso a conexão use uma criptografia TLS e trustServerCertificate seja definido como "false". Verifique se o valor transmitido para hostNameInCertificate corresponde ao CN (Nome Comum) ou ao nome DNS no SAN (Nome Alternativo da Entidade) no certificado do servidor para que uma conexão TLS tenha êxito. Para obter mais informações sobre suporte à criptografia, confira Noções básicas sobre suporte à criptografia. |
| NOMEDAINSTÂNCIA String [<=128 char] nulo |
O nome da instância do banco de dados à qual se conectar. Quando ele não for especificado, a conexão será executada com a instância padrão. Para o caso em que instanceName e a porta forem especificadas, veja as observações para a porta. Caso especifique o Nome da Rede Virtual na propriedade de conexão Servidor, não será possível 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 boolean ["true" | "false"] false |
Defina como "true" para indicar que as credenciais do Windows são usadas pelo SQL Server em sistemas operacionais Windows. Se "true", o driver JDBC procurará no cache de credenciais do computador local por credenciais que foram fornecidas quando um usuário entrou no computador ou na rede. Defina como "true" (com authenticationscheme=JavaKerberos) para indicar que as credenciais do Kerberos são usadas pelo 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 do NTLM são usadas pelo SQL Server. Se "false", o nome de usuário e a senha precisarão ser fornecidos. |
| ipaddresspreference String [<=128 char] IPv4First |
A preferência de IP usada pelo aplicativo cliente. Com IPV4First, o driver percorrerá 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 percorrerá 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 percorrerá todos os endereços IP em seus pedidos iniciais da resolução DNS. |
| jaasConfigurationName String 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. O nome da entrada de configuração pode ser transmitido por meio dessa propriedade. Essa propriedade deve ser usada ao criar um arquivo de configuração Kerberos. Por padrão, o driver procura pelo nome SQLJDBCDriver.Se não for encontrada uma configuração externa, o driver será definido como useDefaultCcache = true para IBM JVMs e como useTicketCache = true para outras JVMs. |
| keyStoreAuthentication String nulo |
(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 dá suporte à configuração do repositório de chaves Java de modo direto quando você define "keyStoreAuthentication=JavaKeyStorePassword". Para usar essa propriedade, também será necessário definir as propriedades keyStoreLocation e keyStoreSecret para o Repositório de Chaves Java. Para obter mais informações sobre o Always Encrypted, confira Como usar o Always Encrypted com um driver JDBC. Começando com o Microsoft JDBC Driver 8.4, você pode definir "keyStoreAuthentication=KeyVaultManagedIdentity" ou "keyStoreAuthentication=KeyVaultClientSecret" para obter uma autenticação no Azure Key Vault usando Identidades Gerenciadas. Para obter mais informações sobre o Always Encrypted, confira Como usar o Always Encrypted com um driver JDBC. |
| keyStoreLocation String nulo |
(Versão 6.0 ou superior) Quando keyStoreAuthentication=JavaKeyStorePassword, a propriedade keyStoreLocation identifica o caminho para o arquivo do repositório de chaves Java que armazena a chave mestra de coluna a ser usada com os dados de Always Encrypted. O caminho deverá incluir o nome de arquivo do repositório de chaves. Para obter mais informações sobre o Always Encrypted, confira Como usar o Always Encrypted com um driver JDBC. |
| keyStorePrincipalId String nulo |
(Versão 8.4+) Quando keyStoreAuthentication=KeyVaultManagedIdentity, a propriedade keyStorePrincipalId especifica uma ID do cliente válida do aplicativo do Microsoft Entra. Para obter mais informações sobre o Always Encrypted, confira Como usar o Always Encrypted com um driver JDBC. |
| keyStoreSecret String nulo |
(Versão 6.0+) Quando keyStoreAuthentication=JavaKeyStorePassword, a propriedade keyStoreSecret identifica a senha a ser usada para acessar o repositório de chaves e a chave. Quando o Repositório de Chaves Java é usado, o repositório de chaves e a senha da chave devem ser iguais. Para obter mais informações sobre o Always Encrypted, confira Como usar o Always Encrypted com um driver JDBC. |
| lastUpdateCount booleano ["true" | "false"] true |
Um valor "true" retorna apenas a última contagem de atualização de uma instrução SQL que é passada para o servidor. Além disso, ele é usado apenas em instruções SELECT, INSERT ou DELETE únicas para ignorar outras contagens de atualização que os gatilhos do servidor podem causar. Definir essa propriedade como "false" fará com que todas as contagens de atualização sejam retornadas, incluindo as que forem retornadas por gatilhos de servidor. Observação: essa propriedade será aplicada somente quando for usada com métodos executeUpdate. Todos os outros métodos execute retornam todos os resultados e as contagens de atualização. Essa propriedade só afeta contagens de atualização retornadas por gatilhos de servidor. Ela não afeta conjuntos de resultados ou erros resultantes de parte da execução do gatilho. |
| lockTimeout INT -1 |
O número de milissegundos para aguardar antes do banco de dados informar um tempo limite de bloqueio. O comportamento padrão é aguardar indefinidamente. Se o usuário não tiver especificado um valor para esta propriedade, este valor será o padrão para todas as instruções na conexão. Como alternativa, Statement.setQueryTimeout() pode ser usado para definir o tempo limite da consulta para instruções específicas. O valor pode ser 0, que especifica a ausência de espera. |
| loginTimeout INT [0..65535] 30 (versão 11.2 e posterior) 15 (versão 10.2 e inferior) |
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 superior) ou 15 segundos (o padrão na versão 10.2 e inferior). 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 três minutos ou mais para dar tempo suficiente para a conexão de failover ter êxito. Para obter mais informações sobre a recuperação de desastre, confira o artigo Suporte ao driver JDBC para obter Alta Disponibilidade e recuperação de desastre. |
| maxResultBuffer String nulo |
(Versão 9.2+) maxResultBuffer poderá ser usado para definir a quantidade máxima de bytes a serem lidos durante a leitura de um conjunto de resultados. Caso isso não seja especificado, todo o conjunto de resultados será lido. O tamanho poderá ser especificado em dois estilos: 1. Como tamanho de bytes (por exemplo, 100, 150M, 300K, 400G)2. Como um percentual da memória heap máxima (por exemplo, 10p, 15pct, 20percent). |
| msiClientId String nulo |
(Preterido – Versão 7.2 ou superior) A ID do Cliente do MSI (Identidade Gerenciada) a ser usada para adquirir um accessToken a fim de estabelecer uma conexão com o modo de autenticação ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI. |
| multiSubnetFailover Boolean 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 mais rapidez na detecção do servidor ativo (atualmente) e na conexão a ele. 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 de forma programática a propriedade de conexão multiSubnetFailover com getPropertyInfo, getMultiSubnetFailover e setMultiSubnetFailover. Observação: do Microsoft JDBC Driver 6.0 para SQL Server em diante, não é mais necessário definir multiSubnetFailover como "true" para se conectar a um ouvinte do grupo de disponibilidade. Uma nova propriedade, transparentNetworkIPResolution, que é habilitada por padrão, fornece a detecção do servidor ativo (no momento) e a conexão com ele. |
| packetSize INT [-1 | 0 | 512..32767] 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 essa propriedade for definida como um valor fora do intervalo aceitável, ocorrerá uma exceção. Importante: o uso da propriedade packetSize quando a criptografia estiver habilitada (encrypt=true) não é recomendado. Do contrário, o driver pode acionar um erro na conexão. Para obter mais informações sobre essa propriedade, confira o método setPacketSize da classe SQLServerDataSource. |
| password String [<=128 char] nulo |
A senha do banco de dados, caso haja conexão com o usuário e a senha do SQL. Para a conexão Kerberos com o nome e a senha da entidade de segurança, essa propriedade é definida como a senha da Entidade de Segurança Kerberos. (Versão 10.2 ou superior) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade password identifica a senha a ser usada para a entidade de segurança do Active Directory. |
| portNumber, porta INT [0..65535] 1433 |
A porta em que o servidor está escutando. Se o número da porta for especificado na cadeia de conexão, nenhuma solicitação para SQLbrowser será feita. Quando a porta e instanceName forem especificadas, a conexão será estabelecida com a porta especificada. No entanto, o instanceName será validado e um erro será lançado caso não haja correspondência com a porta. Importante: Recomendamos que o número da porta sempre seja especificado, pois isso é mais seguro do que usar o SQLbrowser. |
| prepareMethod String sp_prepexec |
(Versão 11.2.0+) Especifica o método de preparação subjacente a ser usado pelo driver com instruções preparadas. Defina como preparar para usar sp_prepare como o método de preparação. Definir prepareMethod para 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 como prepexec para usar sp_prepexec como o 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âmetros iniciais que este pode considerar no plano de execução. |
| queryTimeout INT -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. |
| realm String nulo |
(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 booleano ["true" | "false"] 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 String ["full" | "adaptive"] adaptive |
Se essa propriedade for definida como "adaptive", o mínimo de dados possíveis será armazenado em buffer quando necessário. O modo padrão é "adaptável". Caso essa propriedade seja definida como "full", todo o conjunto de resultados será lido do servidor durante a execução de uma instrução. Nota: depois do driver JDBC da versão 1.2, o comportamento de buffer padrão será "adaptável". Se você quiser manter o comportamento padrão da versão 1.2 em seu aplicativo, defina a propriedade responseBufferring como "completa" nas propriedades de conexão ou use o método setResponseBuffering do objeto SQLServerStatement. |
| selectMethod String ["direct" | "cursor"] direct |
Se essa propriedade for definida como "cursor", um banco de dados será criado para cada consulta criada na conexão dos cursores TYPE_FORWARD_ONLY e CONCUR_READ_ONLY. Essa propriedade só costuma ser obrigatória caso o aplicativo gere conjuntos de resultados grandes que não possam estar inteiramente contidos na memória do cliente. Caso essa propriedade seja definida como "cursor", somente um número limitado de linhas do conjunto de resultados será mantido na memória do cliente. Usar o comportamento padrão significa que todas as linhas do conjunto de resultados serão mantidas na memória do cliente. Esse comportamento fornece o melhor desempenho quando o aplicativo processa todas as linhas. |
| sendStringParameters... AsUnicode booleano ["true" | "false"] true |
Se a propriedade sendStringParametersAsUnicode for definida como "true", os parâmetros String serão enviados para o servidor no formato Unicode. Se a propriedade sendStringParametersAsUnicode for definida como "false", os parâmetros da cadeia de caracteres serão enviados para o servidor no formato não Unicode, como ASCII/MBCS, em vez de Unicode. O valor padrão da propriedade sendStringParametersAsUnicode é "true". Observação: a propriedade sendStringParametersAsUnicode é verificada apenas para enviar um valor de parâmetro com os tipos JDBC CHAR, VARCHAR ou LONGVARCHAR. Os novos métodos de caracteres nacionais do JDBC 4.0 incluem métodos como setNString, setNCharacterStream e setNClob das classes SQLServerPreparedStatement e SQLServerCallableStatement. Esses métodos sempre enviam seus valores de parâmetro para o servidor em Unicode, independentemente da configuração dessa propriedade. Para obter o desempenho ideal com os tipos de dados CHAR, VARCHAR e LONGVARCHAR, um aplicativo deve definir a propriedade sendStringParametersAsUnicode como "false" e usar os métodos de caractere não nacional setString, setCharacterStream e setClob das classes SQLServerPreparedStatement e SQLServerCallableStatement. Ao definir a propriedade sendStringParametersAsUnicode como "false", o aplicativo usará um método de caracteres não nacionais para acessar tipos de dados Unicode no servidor (como nchar, nvarchar e ntext). Alguns dados poderão ser perdidos caso a ordenação do banco de dados não seja compatível com caracteres dos parâmetros da cadeia de caracteres aprovados pelo método de caracteres não nacionais. Um aplicativo deverá usar métodos de caracteres nacionais, como: setNString, setNCharacterStream e setNClob das classes SQLServerPreparedStatement e SQLServerCallableStatement para os tipos de dados NCHAR, NVARCHAR e LONGNVARCHAR do JDBC. 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. |
| sendTemporalDataTypes... AsStringForBulkCopy boolean ["true" | "false"] true |
(Versão 8.4 ou superior) Essa propriedade de conexão, quando definida como "false", envia os tipos de dados DATE, DATETIME, DATIMETIME2, DATETIMEOFFSET, SMALLDATETIME e TIME como os respectivos tipos, em vez de enviá-los como Cadeia de Caracteres. Com essa propriedade de conexão definida como "false", o driver aceitará o formato literal de cadeia de caracteres padrão de cada tipo de dados temporal, por exemplo: DATE: YYYY-MM-DDDATETIME: 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:ssTIME: hh:mm:ss[.nnnnnnn] |
| sendTimeAsDatetime booleano ["true" | "false"] 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 datetime do SQL Server. Defina como “false” para enviar valores java.sql.Time para o servidor como valores time do SQL Server. O valor padrão dessa propriedade é, no momento, “true” e pode ser alterado em uma versão futura. Para obter mais informações sobre como o Microsoft JDBC Driver para SQL Server configura valores java.sql.Time antes de enviá-los para o servidor, confira Configurar como os valores java.sql.Time são enviados para o servidor. |
| serverCertificate, Servidor String nulo |
(Versão 11.2.0+) O caminho para o arquivo de certificado do servidor. Usado para validação ao usar a criptografia definida como estrita. O driver dá suporte a arquivos de certificado usando o formato PEM. |
| serverName, Servidor String nulo |
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 o artigo Suporte ao driver JDBC para obter Alta Disponibilidade e recuperação de desastre. |
| serverNameAsACE booleano ["true" | "false"] false |
(Versão 6.0+) Definir como “true” para indicar que o driver deve traduzir o nome do servidor Unicode para a codificação compatível 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. |
| serverPreparedStatement... DiscardThreshold Integer 10 |
(Versão 6.2+) Essa propriedade pode ser usada para controlar quantas ações de descarte de instrução preparadas pendentes (sp_unprepare) podem estar pendentes por conexão antes que uma chamada para limpar os identificadores pendentes no servidor seja executada. Se essa propriedade for definida como <= 1, ações de cancelamento de preparação serão executadas imediatamente no fechamento da instrução preparada. Se a propriedade for definida como > 1, essas chamadas serão agrupadas em lote para evitar a sobrecarga de uma chamada muito frequente ao sp_unprepare. |
| serverSpn String nulo |
(Versão 4.2+) Essa propriedade opcional pode ser usada para especificar o SPN (Nome da Entidade de Serviço) para uma conexão Kerberos Java. Ela será usada com o authenticationScheme. Para especificar a SPN, ela pode estar na forma de: "MSSQLSvc/fqdn:porta@REALM" em que fqdn é o nome de domínio totalmente qualificado, porta é o número da porta e REALM é o realm de Kerberos do SQL Server em letras maiúsculas. Observação: o @REALM será opcional se o realm padrão do cliente (conforme especificado na configuração do Kerberos) for o mesmo que o realm do Kerberos para o SQL Server. Para obter mais informações sobre como usar o serverSpn com o Kerberos Java, confira Como usar uma autenticação integrada do Kerberos para se conectar ao SQL Server. |
| socketFactoryClass String nulo |
(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 INT 0 |
O número de milissegundos a aguardar antes que ocorra um tempo limite na leitura ou aceitação de um soquete. O valor padrão é 0, que significa tempo limite infinito. |
| statementPooling... CacheSize INT 0 |
(Versão 6.4 ou superior) Essa propriedade pode ser usada para habilitar o cache de identificador de instrução preparado no driver. Essa propriedade define o tamanho do cache para o pool de instruções. Essa propriedade somente poderá ser usada juntamente com a propriedade de conexão disableStatementPooling, que deverá ser definida como "false". Configurar disableStatementPooling como "true" ou statementPoolingCacheSize como 0 desabilita o cache de identificador de instrução preparado. |
| sslProtocol String TLS |
(Versão 6.4+) Essa propriedade pode ser usada 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. |
| transparentNetwork... IPResolution booleano ["true" | "false"] true |
(Versão 6.0+) Essa propriedade proporciona maior rapidez na detecção do servidor (atualmente) ativo e na conexão a ele. Os valores possíveis são "true" e "false", em que "true" é o valor padrão. Antes do Microsoft JDBC Driver 6.0 para SQL Server, um aplicativo precisava definir a cadeia de conexão a fim de incluir "multiSubnetFailover=true" para indicar que estava se conectando a um Grupo de Disponibilidade Always On. Sem definir a palavra-chave de conexão multiSubnetFailover como "true", um aplicativo pode enfrentar um tempo limite ao se conectar a um Grupo de disponibilidade Always On. Com a versão 6.0 e superior, um aplicativo não precisa mais definir multiSubnetFailover como true. Observação: quando transparentNetworkIPResolution=true, a primeira tentativa de conexão usa 500 ms como o tempo limite. Todas as tentativas posteriores usarão a mesma lógica de tempo limite da propriedade multiSubnetFailover. |
| trustManagerClass String nulo |
(Versão 6.4+) O nome de classe totalmente qualificado de uma implementação de javax.net.ssl.TrustManager personalizada. |
| trustManager... ConstructorArg String nulo |
(Versão 6.4+) Um argumento opcional a ser passado para o construtor do TrustManager. Se a propriedade trustManagerClass for especificada e uma conexão criptografada seja solicitada, um TrustManager personalizado será usado em vez do TrustManager baseado no repositório de chaves da JVM do sistema padrão. |
| trustServerCertificate booleano ["true" | "false"] false |
Defina como "true" para especificar que o driver não validará 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 é "falso". Verifique se o valor transmitido para serverName corresponde exatamente ao CN (Nome Comum) ou ao nome DNS no Nome Alternativo da Entidade no certificado do servidor para que uma conexão TLS/SSL tenha êxito. Para obter mais informações sobre suporte à criptografia, confira Noções básicas sobre suporte à criptografia. Observação: Essa propriedade é usada em combinação com as propriedades encrypt/authentication. Essa propriedade somente afetará a validação do certificado TLS/SSL do servidor caso a conexão use uma criptografia TLS. |
| trustStore String nulo |
O caminho (inclusive o nome de arquivo) para o arquivo trustStore do certificado. O arquivo trustStore contém a lista de certificados nos quais o cliente confia. Quando essa propriedade não for especificada ou for definida como nula, o driver contará com as regras de pesquisa de fábrica do gerenciador de confiança para determinar que repositório de certificados usar. O padrão SunX509 TrustManagerFactory tenta localizar o material confiável na seguinte ordem de pesquisa: Um arquivo especificado pela propriedade "javax.net.ssl.trustStore" do sistema da JVM. arquivo <java-home>/lib/security/jssecacerts.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. Observação: Essa propriedade somente afetará a pesquisa de certificados do trustStore caso a conexão use uma criptografia TLS e a propriedade trustServerCertificate seja definida como "false". |
| trustStorePassword String nulo |
A senha usada para verificar a integridade dos dados de trustStore. Caso a propriedade trustStore seja definida, porém a propriedade trustStorePassword não seja, a integridade de trustStore não será verificada. Quando as propriedades trustStore e trustStorePassword não forem especificadas, o driver usará as propriedades do sistema JVM, "javax.net.ssl.trustStore" e "javax.net.ssl.trustStorePassword". Caso a propriedade do sistema "javax.net.ssl.trustStorePassword" não seja especificada, a integridade de trustStore não será verificada. Se o usuário não configurar a propriedade trustStore, mas configurar a propriedade trustStorePassword, o driver JDBC usará o arquivo que o "javax.net.ssl.trustStore" especificar como um repositório confiável. Além disso, o driver verifica a integridade do repositório confiável usando o trustStorePassword especificado. Essa configuração é necessária quando o aplicativo cliente não quiser armazenar a senha na propriedade do sistema da JVM. Observação: a propriedade trustStorePassword somente afetará a pesquisa de certificados do trustStore caso a conexão use uma conexão TLS e a propriedade trustServerCertificate seja definida como "false". |
| trustStoreType String 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 o tipo definido pelo provedor FIPS. |
| useBulkCopyFor... BatchInsert booleano ["true" | "false"] false |
(Versão 9.2+) Essa propriedade de conexão pode ser habilitada para usar de modo transparente a API de Cópia em Massa ao fazer operações de inserção em lote usando java.sql.PreparedStatement. Esse recurso potencialmente fornece um desempenho maior quando habilitado. Por padrão, esse recurso está desabilitado. Defina essa propriedade como "true" para habilitar esse recurso. Observação importante: esse recurso dá suporte apenas a consultas INSERT totalmente parametrizadas. Se as consultas INSERT forem combinadas com outras consultas SQL ou contiverem dados em valores, a execução fará fallback para a operação de inserção em lote básica. Para obter mais informações sobre como usar essa propriedade, confira Como usar a API de cópia em massa para executar uma operação de inserção de lote |
| useDefaultGSSCredential boolean ["true" | "false"] 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 boolean ["true" | "false"] false |
(Versão 12.6+) Quando o aplicativo existe ao lado de bibliotecas que configuram o JAAS no nível do sistema, definir essa propriedade como true permite que o driver use essa mesma configuração para executar a autenticação Kerberos. |
| useFmtOnly booleano ["true" | "false"] false |
(Versão 7.4+) Fornece um modo alternativo de consultar metadados de parâmetro do servidor. Defina essa propriedade como “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 usar apenas como uma solução alternativa para problemas e limitações conhecidos em sp_describe_undeclared_parameters.No momento, esse recurso dá suporte apenas a consultas SELECT/INSERT/UPDATE/DELETE únicas. Tentar usar esse recurso com consultas múltiplas/sem suporte fará com que o driver tente analisar consultas. No entanto, o resultado mais provável será uma exceção.Para obter mais informações sobre essa propriedade, confira Como recuperar o ParameterMetaData por meio do useFmtOnly. |
| userName, usuário String [<=128 char] nulo |
O usuário do banco de dados, caso haja conexão com o usuário e a senha do SQL. Para a conexão Kerberos com o nome e a senha da entidade de segurança, essa propriedade é definida como o nome da Entidade de Segurança Kerberos. (Versão 10.2 ou superior) Quando authentication=ActiveDirectoryServicePrincipal, a propriedade userName especificará uma ID de cliente válida e segura do Azure Active Directory. |
| workstationID String [<=128 char] <empty string> |
A ID da estação de trabalho. Usado para identificar a estação de trabalho específica em várias ferramentas de criação de perfil e de registro em log. Se nenhum for especificado, o <empty string> será usado. |
| xopenStates booleano ["true" | "false"] false |
Defina como "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. |
Observação
O Microsoft JDBC Driver para SQL Server recebe os valores padrão do servidor para propriedades de conexão, exceto para ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. O Microsoft JDBC Driver para SQL Server define automaticamente ANSI_DEFAULTS com ON e IMPLICIT_TRANSACTIONS como OFF.
Importante
Caso uma autenticação seja definida como ActiveDirectoryPassword, a biblioteca a seguir precisará ser incluída neste classpath: microsoft-authentication-library-for-java. Ela pode ser encontrada no Repositório Maven. A maneira mais simples de baixar a biblioteca e suas dependências é usar o Maven:
- Instale o Maven em seu sistema
- Acesse a página do GitHub do driver
- Baixe o arquivo pom.xml
- Execute o seguinte comando do Maven para baixar a biblioteca e suas dependências:
mvn dependency:copy-dependencies