Como criar uma URL de conexão
O formato geral da URL de conexão é
jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]
Em que:
jdbc:sqlserver:// (Obrigatório) - É conhecido como subprotocolo e é constante.
serverName (Opcional) - É o endereço do servidor ao qual se conectar. Esse endereço pode ser um endereço DNS ou IP, ou pode ser
localhostou127.0.0.1para o computador local. Se não for especificado na URL de conexão, o nome do servidor deverá ser especificado na coleção de propriedades.instanceName (Opcional) - É a instância à qual se conectar no
serverName. Se não for especificada, será feita uma conexão com a instância padrão.portNumber (Opcional) - É a porta à qual se conectar no
serverName. O padrão é1433. Se você estiver usando a porta padrão, não precisará especificar a porta nem o:anterior na URL.Observação
Para obter o desempenho ideal da conexão, você deve definir o
portNumberquando se conectar a uma instância nomeada. Isso evitará uma viagem de ida e volta ao servidor para determinar o número da porta. SeportNumbereinstanceNameforem ambos usados,portNumberterá precedência einstanceNameserá ignorado.property (Opcional) - É uma ou mais propriedades de conexão de opções. Para obter mais informações, veja Configuração das propriedades de conexão. Qualquer propriedade da lista pode ser especificada. Propriedades só podem ser delimitadas usando o ponto e vírgula (
;) e não podem ser duplicadas.
Cuidado
Para fins de segurança, recomenda-se evitar construir as URLs de conexão com base na entrada do usuário. Convém especificar apenas o nome do servidor e o driver na URL. Para os valores de nome de usuário e senha, use as coleções de propriedades de conexão. Confira mais informações sobre segurança nos aplicativos JDBC em Proteger os aplicativos do driver JDBC.
Propriedades da conexão
Para obter uma lista detalhada das propriedades que podem ser definidas na cadeia de conexão, confira Como definir as propriedades de conexão.
Exemplos de conexão
Conectar ao banco de dados padrão no computador local usando um nome de usuário e senha:
jdbc:sqlserver://localhost;encrypt=true;user=MyUserName;password=<password>;
Observação
Embora o exemplo anterior use um nome de usuário e uma senha na cadeia de conexão, você deve usar a segurança integrada, pois ela é mais segura. Para obter mais informações, consulte a seção Conexão com autenticação integrada, mais adiante neste artigo.
A seguinte cadeia de conexão mostra um exemplo de como se conectar a um banco de dados do SQL Server usando a autenticação integrada e o Kerberos em um aplicativo que esteja em execução em qualquer sistema operacional compatível com o Microsoft JDBC Driver para SQL Server:
jdbc:sqlserver://;servername=server_name;encrypt=true;integratedSecurity=true;authenticationScheme=JavaKerberos
Conectar ao banco de dados padrão no computador local usando a autenticação integrada:
jdbc:sqlserver://localhost;encrypt=true;integratedSecurity=true;Conectar a um banco de dados nomeado em um servidor remoto:
jdbc:sqlserver://localhost;encrypt=true;databaseName=AdventureWorks;integratedSecurity=true;Conectar na porta padrão ao servidor remoto:
jdbc:sqlserver://localhost:1433;encrypt=true;databaseName=AdventureWorks;integratedSecurity=true;Conectar especificando um nome de aplicativo personalizado:
jdbc:sqlserver://localhost;encrypt=true;databaseName=AdventureWorks;integratedSecurity=true;applicationName=MyApp;
Instâncias nomeadas e várias instâncias do SQL Server
O SQL Server permite a instalação de várias instâncias de banco de dados por servidor. Cada instância é identificável por um nome específico. Para se conectar a uma instância nomeada do SQL Server, você pode especificar o número da porta da instância nomeada (preferencial). Você também pode especificar o nome da instância como uma propriedade de URL do JDBC ou uma propriedade da datasource. Se nenhuma propriedade de nome de instância ou número de porta for especificada, será criada uma conexão com a instância padrão. Veja os exemplos a seguir:
Use o seguinte formato para especificar o número da porta:
jdbc:sqlserver://localhost:1433;encrypt=true;integratedSecurity=true;<more properties as required>;Use o seguinte formato para lidar com uma propriedade URL do JDBC:
jdbc:sqlserver://localhost;encrypt=true;instanceName=instance1;integratedSecurity=true;<more properties as required>;
Valores de escape na URL de conexão
Caso os valores da URL de conexão incluam caracteres especiais, como espaços, ponto e vírgula e aspas, talvez seja necessário executar um escape de determinadas partes dos valores. O driver JDBC é compatível com o escape desses caracteres, colocando-os entre chaves. Por exemplo, {;} escapa um ponto-e-vírgula.
Antes da versão 8.4, os valores de escape podiam conter caracteres especiais (especialmente =, ; [] e espaço), mas não podiam conter chaves. Convém adicionar os valores que devem ser escapados e contêm chaves a uma coleção de propriedades.
Na versão 8.4 e superior, os valores de escape podem conter caracteres especiais, incluindo chaves. No entanto, as chaves de fechamento devem ter escape. Por exemplo, com uma senha de pass";{}word, uma cadeia de conexão precisaria escapar da senha da seguinte maneira:
jdbc:sqlserver://localhost;encrypt=true;username=MyUsername;password={pass";{}}word};
Observação
O espaço em branco dentro das chaves é literal e não é cortado.
Conectando com a autenticação integrada no Windows
O driver JDBC é compatível com o uso da autenticação integrada Tipo 2 em sistemas operacionais Windows com a propriedade de cadeia de conexão integratedSecurity. Para usar a autenticação integrada, copie o arquivo mssql-jdbc_auth-<version>-<arch>.dll para um diretório no caminho do sistema Windows no computador em que o driver JDBC está instalado.
Os arquivos mssql-jdbc_auth-<version>-<arch>.dll são instalados no seguinte local:
<installation directory>\sqljdbc_<version>\<language>\auth\
Para qualquer sistema operacional com suporte pelo driver Microsoft JDBC para SQL Server, consulte Usando a autenticação integrada Kerberos para se conectar ao SQL Server para obter uma descrição de um recurso adicionado no Microsoft JDBC Driver 4.0 para SQL Server que permite que um aplicativo se conecte a um banco de dados usando autenticação integrada com o Kerberos Tipo 4.
Observação
Se estiver executando uma JVM (Máquina Virtual Java) de 32 bits, use o arquivo mssql-jdbc_auth-<version>-<arch>.dll na pasta x86, mesmo que o sistema operacional seja a versão x64. Se estiver executando uma JVM de 64 bits em um processador x64, use o arquivo mssql-jdbc_auth-<version>-<arch>.dll na pasta x64.
Como alternativa, defina a propriedade do sistema java.libary.path para especificar o diretório de mssql-jdbc_auth-<version>-<arch>.dll. Por exemplo, se o driver JDBC for instalado no diretório padrão, você poderá especificar o local da DLL usando o seguinte argumento de máquina virtual (VM) quando o aplicativo Java for iniciado:
-Djava.library.path=C:\Microsoft JDBC Driver 6.4 for SQL Server\sqljdbc_<version>\enu\auth\x86
Conectando a endereços IPv6
O driver JDBC oferece suporte ao uso de endereços IPv6 com a coleção de propriedades de conexão e com a propriedade cadeia de conexão serverName. O valor de serverName inicial, como jdbc:sqlserver://serverName, não tem suporte para endereços IPv6 em cadeias de conexão. Usar um nome para serverName em vez de um endereço IPv6 bruto funciona em todos os casos na conexão. Os exemplos a seguir fornecem mais informações.
Para usar a propriedade serverName:
jdbc:sqlserver://;serverName=3ffe:8311:eeee:f70f:0:5eae:10.203.31.9\\instance1;encrypt=true;integratedSecurity=true;Para usar a coleção de propriedades:
Properties pro = new Properties();pro.setProperty("serverName", "serverName=3ffe:8311:eeee:f70f:0:5eae:10.203.31.9\\instance1");Connection con = DriverManager.getConnection("jdbc:sqlserver://;encrypt=true;integratedSecurity=true;", pro);