You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/connect/jdbc/building-the-connection-url.md
+16-15Lines changed: 16 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,23 @@
1
1
---
2
-
title: Building the connection URL
3
-
description: Article about formatting the connection string used by the Microsoft JDBC Driver for SQL Server. Samples of connection strings are included in the examples section.
2
+
title: Building the connection URL with the Microsoft JDBC Driver for SQL Server
3
+
description: Learn about formatting the connection string used by the Microsoft JDBC Driver for SQL Server. Samples of connection strings are included in the examples section.
-**jdbc:sqlserver://** (Required) - Is known as the subprotocol and is constant.
22
23
@@ -26,12 +27,12 @@ where:
26
27
27
28
-**portNumber** (Optional) - Is the port to connect to on `serverName`. The default is `1433`. If you're using the default port, you don't have to specify the port, nor the preceding `:` in the URL.
28
29
29
-
> [!NOTE]
30
-
> For optimal connection performance, you should set the `portNumber` when you connect to a named instance. This will avoid a round trip to the server to determine the port number. If both a `portNumber` and `instanceName` are used, the `portNumber` will take precedence and the `instanceName` will be ignored.
30
+
> [!NOTE]
31
+
> For optimal connection performance, you should set the `portNumber` when you connect to a named instance. This will avoid a round trip to the server to determine the port number. If both a `portNumber` and `instanceName` are used, the `portNumber` will take precedence and the `instanceName` will be ignored.
31
32
32
33
-**property** (Optional) - Is one or more option connection properties. For more information, see [Setting the connection properties](setting-the-connection-properties.md). Any property from the list can be specified. Properties can only be delimited by using the semicolon (`;`), and they can't be duplicated.
33
34
34
-
> [!CAUTION]
35
+
> [!CAUTION]
35
36
> For security purposes, you should avoid building the connection URLs based on user input. You should only specify the server name and driver in the URL. For user name and password values, use the connection property collections. For more information about security in your JDBC applications, see [Securing JDBC driver applications](securing-jdbc-driver-applications.md).
36
37
37
38
## Connection properties
@@ -44,10 +45,10 @@ Connect to the default database on the local computer by using a user name and p
> Although the previous example uses a username and password in the connection string, you should use integrated security as it's more secure. For more information, see the [Connecting with integrated authentication](#Connectingintegrated) section later in this article.
49
50
50
-
The following connection string shows an example of how to connect to a [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] database using integrated authentication and Kerberos from an application running on any operating system supported by the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)]:
51
+
The following connection string shows an example of how to connect to a [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] database using integrated authentication and Kerberos from an application running on any operating system supported by the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)]:
[!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] allows for the installation of multiple database instances per server. Each instance is identifiable by a specific name. To connect to a named instance of [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], you can either specify the port number of the named instance (preferred). You can also specify the instance name as a JDBC URL property or a **datasource** property. If no instance name or port number property is specified, a connection to the default instance is created. See the following examples:
75
+
[!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] allows for the installation of multiple database instances per server. Each instance is identifiable by a specific name. To connect to a named instance of [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], you can either specify the port number of the named instance (preferred). You can also specify the instance name as a JDBC URL property or a **datasource** property. If no instance name or port number property is specified, a connection to the default instance is created. See the following examples:
75
76
76
77
- To specify a port number, use the following format:
77
78
@@ -91,7 +92,7 @@ In version 8.4 and above, escaped values can contain special characters, includi
For any operating system supported by the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)], see [Using Kerberos integrated authentication to connect to SQL Server](using-kerberos-integrated-authentication-to-connect-to-sql-server.md) for a description of a feature added in [!INCLUDE[jdbc-40](../../includes/jdbc-40-md.md)] that allows an application to connect to a database using integrated authentication with Type 4 Kerberos.
106
+
For any operating system supported by the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)], see [Using Kerberos integrated authentication to connect to SQL Server](using-kerberos-integrated-authentication-to-connect-to-sql-server.md) for a description of a feature added in [!INCLUDE[jdbc-40](../../includes/jdbc-40-md.md)] that allows an application to connect to a database using integrated authentication with Type 4 Kerberos.
106
107
107
-
> [!NOTE]
108
+
> [!NOTE]
108
109
> If you are running a 32-bit Java Virtual Machine (JVM), use the `mssql-jdbc_auth-<version>-<arch>.dll` file in the x86 folder, even if the operating system is the x64 version. If you are running a 64-bit JVM on a x64 processor, use the `mssql-jdbc_auth-<version>-<arch>.dll` file in the x64 folder.
109
110
110
111
Alternatively you can set the java.library.path system property to specify the directory of the `mssql-jdbc_auth-<version>-<arch>.dll`. For example, if the JDBC driver is installed in the default directory, you can specify the location of the DLL by using the following virtual machine (VM) argument when the Java application is started:
@@ -127,6 +128,6 @@ The JDBC driver supports the use of IPv6 addresses with the connection propertie
127
128
128
129
`Connection con = DriverManager.getConnection("jdbc:sqlserver://;encrypt=true;integratedSecurity=true;", pro);`
129
130
130
-
## See also
131
+
## Related content
131
132
132
133
-[Connecting to SQL Server with the JDBC driver](connecting-to-sql-server-with-the-jdbc-driver.md)
The examples in this article describe how to use connection string properties that allow applications to use Transport Layer Security (TLS) encryption in a Java application. For more information about these new connection string properties such as **encrypt**, **trustServerCertificate**, **trustStore**, **trustStorePassword**, and **hostNameInCertificate**, see [Setting the connection properties](setting-the-connection-properties.md).
17
17
18
18
## Configuring the connection
19
19
20
-
When the **encrypt** property is set to **true** and the **trustServerCertificate** property is set to **true**, the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)] won't validate the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] TLS certificate. This setting is common for allowing connections in test environments, such as where the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] instance has only a self-signed certificate.
20
+
When the **encrypt** property is set to **true** and the **trustServerCertificate** property is set to **true**, the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)] won't validate the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] TLS certificate. This setting is common for allowing connections in test environments, such as where the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] instance has only a self-signed certificate.
21
21
22
22
The following code example demonstrates how to set the **trustServerCertificate** property in a connection string:
23
23
@@ -28,7 +28,7 @@ String connectionUrl =
28
28
"encrypt=true;trustServerCertificate=true";
29
29
```
30
30
31
-
When the **encrypt** property is set to **true** and the **trustServerCertificate** property is set to **false**, the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)] will validate the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] TLS certificate. Validating the server certificate is a part of the TLS handshake and ensures that the server is the correct server to connect to. To validate the server certificate, the trust material must be supplied at connection time either by using **trustStore** and **trustStorePassword** connection properties explicitly, or by using the underlying Java Virtual Machine (JVM)'s default trust store implicitly.
31
+
When the **encrypt** property is set to **true** and the **trustServerCertificate** property is set to **false**, the [!INCLUDE[jdbcNoVersion](../../includes/jdbcnoversion_md.md)] will validate the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] TLS certificate. Validating the server certificate is a part of the TLS handshake and ensures that the server is the correct server to connect to. To validate the server certificate, the trust material must be supplied at connection time either by using **trustStore** and **trustStorePassword** connection properties explicitly, or by using the underlying Java Virtual Machine (JVM)'s default trust store implicitly.
32
32
33
33
The **trustStore** property specifies the path (including filename) to the certificate trustStore file, which contains the list of certificates that the client trusts. The **trustStorePassword** property specifies the password used to check the integrity of the trustStore data. For more information on using the JVM's default trust store, see the [Configuring the client for encryption](configuring-the-client-for-ssl-encryption.md).
34
34
@@ -55,12 +55,12 @@ String connectionUrl =
55
55
"hostNameInCertificate=hostName";
56
56
```
57
57
58
-
> [!NOTE]
58
+
> [!NOTE]
59
59
> Alternatively, you can set the value of connection properties by using the appropriate **setter** methods provided by the [SQLServerDataSource](reference/sqlserverdatasource-class.md) class.
60
60
61
-
If the **encrypt** property is **true** and the **trustServerCertificate** property is **false** and if the server name in the connection string doesn't match the server name in the TLS certificate, the following error will be issued: `The driver couldn't establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "java.security.cert.CertificateException: Failed to validate the server name in a certificate during Secure Sockets Layer (SSL) initialization."`. With version 7.2 and up, the driver supports wildcard pattern matching in the left-most label of the server name in the TLS certificate.
61
+
If the **encrypt** property is **true**, the **trustServerCertificate** property is **false**, and if the server name in the connection string doesn't match the server name in the TLS certificate, the following error will be issued: `The driver couldn't establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "java.security.cert.CertificateException: Failed to validate the server name in a certificate during Secure Sockets Layer (SSL) initialization."`. With version 7.2 and up, the driver supports wildcard pattern matching in the left-most label of the server name in the TLS certificate.
In our continued commitment to interoperability, Microsoft provides a Java Database Connectivity (JDBC) driver for use with SQL Server, Azure SQL Database, and Azure SQL Managed Instance. The driver is available at no extra charge and provides Java database connectivity from any Java application, application server, or Java-enabled applet. This driver is a Type 4 JDBC driver that provides database connectivity through the standard JDBC application program interfaces (APIs).
16
17
17
18
The Microsoft JDBC Driver for SQL Server has been tested against major application servers such as IBM WebSphere and SAP NetWeaver.
18
19
19
20
## Getting started
20
21
21
-
*[Step 1: Configure development environment for Java development](step-1-configure-development-environment-for-java-development.md)
22
-
*[Step 2: Create a database on SQL Server or Azure SQL Database for Java development](step-2-create-a-sql-database-for-java-development.md)
23
-
*[Step 3: Proof of concept connecting to SQL using Java](step-3-proof-of-concept-connecting-to-sql-using-java.md)
22
+
-[Step 1: Configure development environment for Java development](step-1-configure-development-environment-for-java-development.md)
23
+
-[Step 2: Create a database for Java development](step-2-create-a-sql-database-for-java-development.md)
24
+
-[Step 3: Proof of concept connecting to SQL using Java](step-3-proof-of-concept-connecting-to-sql-using-java.md)
[Download Microsoft JDBC Driver for SQL Server](download-microsoft-jdbc-driver-for-sql-server.md) - has additional information about Maven projects, and more.
0 commit comments