Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public final class SqlServer

  1. Object
  2. ServerSession
  3. SqlServer

A SQL Server client speaking TDS 7.4, the Tabular Data Stream, written from Microsoft’s published MS-TDS specification. SQL Server 2017 and later, and Azure SQL.

SqlServer db = SqlServer.connect("db.internal", 1433, "app", "user", "secret",
        "require", null, 10000, 0);
List rows = db.query("SELECT id, name FROM users WHERE id = @p1", new Object[] {7L});

Statements

A statement with parameters is an RPC call to sp_executesql, with the parameters named @p1, @p2 and so on and typed from the Java values. One without is a plain batch. Values never travel inside the statement text.

Encryption

The TLS handshake is carried inside PRELOGIN packets, which is how every SQL Server before TDS 8.0 negotiates it. The client asks for the whole session to be encrypted, never the login alone, for every sslmode but disable. A login sends the password scrambled, not hashed, so a server without TLS is refused unless sslmode=disable says the plaintext is deliberate.

sslmode=strict is TDS 8.0: TLS first, before any TDS byte, with PRELOGIN and the login inside it, the certificate verified for the host and ALPN tds/8.0 offered. It is what a server or Azure SQL set to strict encryption requires. SQL Server on Linux serves it from 2025; 2022 on Linux refuses every strict connection (error 17821) whatever its certificate.

Sign-in

A SQL login by name and password, or a Windows account over NTLMv2 when the user is written DOMAIN\\user. Kerberos and Microsoft Entra ID are not implemented.

Values

Integers and bits arrive as Long, floats as Double, binary as byte[], and everything else as a String in the form the other engines use: decimals and money as digits, dates and times as yyyy-MM-dd HH:mm:ss.fff.

Fields

public static final ServerSession.Connector CONNECTOROpens SqlServer sessions; naming this constant is what puts the engine in an application.

Methods

public Dialect dialect()The SQL this session’s server speaks.
public boolean ownsTransactionControl()True when beginning, committing and rolling back are protocol requests or session state of this client’s own, rather than statements a caller could equally run.
public static SqlServer connect(String host, int port, String database, String user, String password, String sslMode, String caFile, int timeoutMillis, int socketTimeoutMillis) throws IOExceptionOpens a session.
public int execute(String sql, Object[] params) throws IOExceptionRuns a statement that returns no rows and answers with the number of rows it affected.
public List query(String sql, Object[] params) throws IOExceptionRuns a statement and answers with its rows, each a Map of column name to value in projection order.
public long lastInsertId()The key the last INSERT on this session generated, or 0 when it generated none.
public void begin() throws IOExceptionOpens a transaction.
public void beginReadOnly() throws IOExceptionOpens a transaction.
public void begin(boolean readOnly, TransactionIsolation isolation) throws IOExceptionOpens a transaction at an isolation level.
public void commit() throws IOExceptionCommits the open transaction.
public void rollback() throws IOExceptionRolls the open transaction back.
public void savepoint(String verb, String name) throws IOExceptionSavepoints, under the verbs the other engines use.
public void close()Closes the connection.
public boolean isClosed()True once the session is closed or its connection was lost.

Inherited nested types

Inherited methods

Field details

CONNECTOR

public static final ServerSession.Connector CONNECTOR
Opens SqlServer sessions; naming this constant is what puts the engine in an application. See ServerSession.Connector.

Method details

dialect

public Dialect dialect()
The SQL this session’s server speaks.

ownsTransactionControl

public boolean ownsTransactionControl()
True when beginning, committing and rolling back are protocol requests or session state of this client’s own, rather than statements a caller could equally run.

connect

public static SqlServer connect(String host, int port, String database, String user, String password, String sslMode, String caFile, int timeoutMillis, int socketTimeoutMillis) throws IOException

Opens a session.

sslMode is what the other engines take: require (and verify-full) demand TLS to a certificate that verifies for host, verify-ca a chain to caFile without the name, prefer uses TLS and fails when the server has none, since a login cannot be protected without it, and disable is plaintext, deliberately. strict is SQL Server’s own: TDS 8.0, TLS before the first packet, verified as require is.

A user written DOMAIN\\user signs in as that Windows account over NTLMv2; any other is a SQL login.

An Azure SQL gateway that answers the login with a redirect is followed, once.

execute

public int execute(String sql, Object[] params) throws IOException
Runs a statement that returns no rows and answers with the number of rows it affected.

Returns

the number of rows it changed

query

public List query(String sql, Object[] params) throws IOException
Runs a statement and answers with its rows, each a Map of column name to value in projection order. A statement that produces several result sets answers with the first.

lastInsertId

public long lastInsertId()
The key the last INSERT on this session generated, or 0 when it generated none.

begin

public void begin() throws IOException
Opens a transaction.

beginReadOnly

public void beginReadOnly() throws IOException
Opens a transaction. SQL Server has no read-only transaction, so this is begin.

begin

public void begin(boolean readOnly, TransactionIsolation isolation) throws IOException
Opens a transaction at an isolation level. The level is a session setting on SQL Server, so it is put back to READ COMMITTED when the transaction ends.

commit

public void commit() throws IOException
Commits the open transaction.

rollback

public void rollback() throws IOException
Rolls the open transaction back. A transaction the server already ended, as it does for the victim of a deadlock, is not an error here.

savepoint

public void savepoint(String verb, String name) throws IOException
Savepoints, under the verbs the other engines use. SQL Server spells them SAVE TRANSACTION and ROLLBACK TRANSACTION, and has nothing to release: a savepoint lasts until its transaction ends.

close

public void close()
Closes the connection. An open transaction is rolled back by the server.

isClosed

public boolean isClosed()
True once the session is closed or its connection was lost.