The general form of the connection URL is:
jdbc:sqlserver://[serverName[/instanceName][:portNumber]][;property=value[;property=value]]
where:
- jdbc:sqlserver:// (required) is called the subprotocol and is a constant.
- serverName (optional) is the address of the server to connect to. It can be a DNS or IP address, or the local computer address localhost or 127.0.0.1. If the server name is not specified in the connection URL, it must be specified in the property set.
- instanceName (optional) is the instance on serverName to connect to. If not specified, it will connect to the default instance.
- portNumber (optional) is the port on serverName to connect to. The default value is 1433. If you use the default port, you do not need to specify the port and its preceding ":" in the URL.
.gif)
Notice:For best connection performance, portNumber should be set when connecting to the specified instance. This will avoid a round trip to the server to determine the port number. If both portNumber and instanceName are used, portNumber will take precedence and instanceName will be ignored. - property (optional) is one or more option connection properties. For more information, see JDBC Connection to SQL Server Database - Setting Connection Properties . Any attribute in this list can be specified. Attributes can only be separated by semicolons (";"), and duplicates are not allowed.
.gif) warn: |
| For security reasons, you should avoid creating connection URLs based on user input. Only the server name and driver should be specified in the URL. For username and password values, use the connection properties set. For more information about security in JDBC applications, see Securing JDBC Driver Applications . |
The connection instance uses the username and password to connect to the default database on the local computer:
jdbc:sqlserver://localhost;user=MyUserName;password=*****;
| Notice: |
| Although the above example uses a username and password in the connection string, if the application is running on a Windows operating system, integrated security should be used as it is more secure. For more information, see the JDBC connection to a SQL Server database - Creating a connection URL section later in this topic. |
Connect to the default database on the local computer using integrated authentication:
jdbc:sqlserver://localhost;integratedSecurity=true;
Connect to the specified database on the remote server:
jdbc:sqlserver://localhost;databaseName=AdventureWorks;integratedSecurity=true;
Connect to the default port on the remote server:
jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks;integratedSecurity=true;
Connect by specifying a custom application name:
jdbc:sqlserver://localhost;databaseName=AdventureWorks;integratedSecurity =true;applicationName=MyApp;
Specify multiple instances of SQL Server SQL Server 2000 and SQL Server 2005 allow multiple database instances to be installed on each server. Each instance is identified by a dedicated name. To connect to a specified instance of SQL Server, either use the port number of the specified instance (preferred), or specify the instance name as a JDBC URL property or datasource property. If no instance name attribute or port number attribute is specified, a connection to the default instance is created. As shown in the following example:
To use port numbers:
jdbc:sqlserver://localhost:1433;integratedSecurity=true;<more properties as required>;
To use the JDBC URL properties:
jdbc:sqlserver://localhost;instanceName=instance1;integratedSecurity=true;< more properties as required>;
Escape values in connection URLs Some parts of connection URL values must be escaped because they contain special characters such as spaces, semicolons, and quotation marks. The JDBC driver will support escaping these characters if they are enclosed in curly braces. For example, {;} will escape semicolons.
Escaped values can contain special characters (specifically "=", ";", "[]", and spaces), but not curly braces. Values that must be escaped and contain curly braces should be added to the attribute set.
| Notice: |
| Whitespace within curly braces is a literal character and cannot be deleted. |
Connecting with Integrated Authentication The JDBC driver supports "Type 2" integrated authentication on Windows operating systems through the integratedSecurity connection string property. To use integrated authentication, copy the sqljdbc_auth.dll file to the JDBC driver installation directory under the Windows system path on your computer.
The sqljdbc_auth.dll file is installed in the following location:
< installation directory >/sqljdbc_< version >/< language >/auth/
| Notice: |
| If you are running a 32-bit Java Virtual Machine (JVM), use the sqljdbc_auth.dll file in the x86 folder, even if the operating system is an x64 version. If you are running a 64-bit JVM on an x64 processor, use the sqljdbc_auth.dll file in the x64 folder. If you are running a 64-bit JVM on an IA-64 processor, use the sqljdbc_auth.dll file in the IA64 folder. |
The directory for sqljdbc_auth.dll can also be specified by setting the java.libary.path system property, for example, if the JDBC driver is installed in the default directory, you can use the following virtual machine (VM) parameters to specify the DLL when the Java application starts Location:
-Djava.library.path=C:/Microsoft SQL Server 2005 JDBC Driver/sqljdbc_<version>/enu/auth/x86
Connecting via IPv6 address The JDBC driver supports using a connection string property with a connection property set and serverName the IPv6 address. The connection string does not support the use of an initial serverName value in an IPv6 address, such as jdbc: sqlserver :// serverName . Using the name of serverName instead of the raw IPv6 address will work in all cases in the connection. The following examples provide details.
use serverName property
jdbc:sqlserver://;serverName=3ffe:8311:eeee:f70f:0:5eae:10.203.31.9//instance1;integratedSecurity=true;
use property set
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://;integratedSecurity=true;", pro);