Connect Java to an existing TDS listener

← SQL Server wire examples

Use the SQL Server JDBC driver over TLS. TDS is the protocol used by SQL Server clients; the described listener is a preview feature.

Before you run it: Dated driver checks below apply to those tested forms, not every SQL Server feature or current production connection.

Load the invoice sample first and place the supported SQL Server JDBC driver on your Java classpath. JDBC is Java's database connection interface. Replace the environment placeholders with the existing listener details; the query does not create its table or rows.

Follow the exampleCopy Anchor Link

1. Confirm the existing listener is enabled.
2. Use the shown driver and connection settings.
3. Keep certificate validation on.
4. Run the small query.

Set connection variablesCopy Anchor Link

export OC_SQL_HOST=...        # the endpoint your console shows
export OC_DATABASE=...
export OC_DB_USER=...
export OC_DB_PASSWORD=...     # never inline this in the URL

Run the exampleCopy Anchor Link

import java.sql.*;

public class Connect {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:sqlserver://" + System.getenv("OC_SQL_HOST") + ":1433"
                   + ";databaseName="         + System.getenv("OC_DATABASE")
                   // TLS is mandatory. Without it there is no listener to reach.
                   + ";encrypt=true"
                   // Validate the chain. Only relax this against a test instance.
                   + ";trustServerCertificate=false"
                   + ";hostNameInCertificate=" + System.getenv("OC_SQL_HOST")
                   + ";loginTimeout=30";

        try (Connection conn = DriverManager.getConnection(
                url, System.getenv("OC_DB_USER"), System.getenv("OC_DB_PASSWORD"));
             Statement st = conn.createStatement();
             ResultSet rs = st.executeQuery(
                 "SELECT TOP 5 id, customer_ref, amount_cents"
               + "  FROM invoices ORDER BY amount_cents DESC")) {

            while (rs.next()) {
                System.out.printf("%d  %-12s %d%n",
                    rs.getInt("id"), rs.getString("customer_ref"), rs.getInt("amount_cents"));
            }
        }
    }
}

Check the resultCopy Anchor Link

The example checks connection setup and the documented driver forms.

4101  ACME-77       129900
4088  ACME-12        98450
4077  ORBIT-3        61000
4051  ACME-77        44900
4020  ORBIT-9        12750

Important detailsCopy Anchor Link

• encrypt=true is not a hardening option here, it is the only way in. A listener with no loadable certificate never binds, so a certificate problem shows up as a connection that finds nothing at all:

com.microsoft.sqlserver.jdbc.SQLServerException:
  The TCP/IP connection to the host ..., port 1433 has failed.

• If that is what you see, check the certificate before the firewall. Then check whether a listener was ever enabled — it is off by default on every instance.
• TOP 5 is translated to a LIMIT. The translated set lists what else is rewritten, and the refused set lists what is not.
• Keep the password out of the URL. The driver takes it as a separate argument, and a URL is the thing that ends up in a log.

Microsoft, SQL Server and T-SQL are trademarks of the Microsoft group of companies; mssql-jdbc is Microsoft's own driver. Named here only to describe protocol compatibility and to identify the versions it was measured against. OriginChainDB is not affiliated with, endorsed by, or sponsored by Microsoft, and does not distribute Microsoft software.

Recorded driver check: mssql-jdbc 13.4.0 and 12.10.1, 34 of 34 checks each, on 2026-09-07. This is a historical test record.

ContinueCopy Anchor Link

Continue to reuse a parameterized statement.