Alpha

These pages are built from turborel-java’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Errors and Diagnostics

Every failure reaches a program as the driver's error, com.turborel.jdbc.TurborelException, a java.sql.SQLException: the server's own, as it reports it, or one the driver raises itself, with the SQLCODE and SQLSTATE Turborel gives the same failure. This chapter tells what a failure carries, which end the connection, and how warnings come. The examples use the low-level client and the table of Running Queries.

What a failure carries

getSQLState() gives its SQLSTATE, the code the SQL standard defines, and sqlcode(), as getErrorCode(), its SQLCODE, the older number. getMessage() says what went wrong in plain words. Of the server's failures, rule() gives the rule it cites, position() where in the statement it failed, transactionActive() whether a transaction is still active after it, and, granted diagnostics, diagnostics() what it is about: its severity, detail, hint, context, schema, table, column, data type and constraint, each if known.

try {
    conn.statements().query("INSERT INTO STAFF (ID, NAME) VALUES (1, 'Ada')");
} catch (TurborelException e) {
    System.out.println(e.sqlcode() + " " + e.getSQLState() + ": " + e.getMessage());
    System.out.println("rule " + e.rule());
    System.out.println("transaction still active: " + e.transactionActive());
    System.out.println(e.diagnostics());
}
System.out.println("connection lost: " + conn.isLost());
-201 23000: PRIMARY KEY ANN.STAFF_PRIMARY1 (ID) of ANN.STAFF would be violated: a row of these values is there
rule X3.135-1986 §6.4 GR2
transaction still active: true
{SCHEMA=ANN, CONSTRAINT=STAFF_PRIMARY1, TABLE=STAFF, SEVERITY=ERROR, DETAIL=the key (1) is held by another row}
connection lost: false

Failures that end the connection

A statement's failure leaves the connection as it was. A failure of the connection itself ends it: an Error the server sends of SQLSTATE class 08 but 08003, or of class 28 and SQLCODE -919, credentials refused, as at a login or a change of user; and every failure the driver raises of the connection, SQLCODE -919 and SQLSTATE 08006: a reply malformed or too long, the stream failing, a wait that runs out. A reply whose frame is whole but holds a value the driver cannot take, as a truth byte of 2 or a JSON value damaged, fails its statement alone, SQLCODE -916 or -900, once the rest of the statement's replies are read past, and the connection goes on. A connection lost takes no more: isLost says so, and each later request fails with the failure that lost it. The codes the driver raises itself are listed in Appendix B.

Warnings

A statement that completes with a warning, of SQLSTATE class 01, is not a failure: the connection's warning() gives its SQLSTATE. Its conditions, the warnings it raised, are told one way. Granted conditions, they come in its completion, and the connection's told().conditions() gives them, takeConditions() taking them so each is told once.

conn.statements().query("CREATE TABLE BONUS (AMOUNT INTEGER)");
conn.statements().query("INSERT INTO BONUS VALUES (NULL), (100)");
conn.statements().query("SELECT SUM(AMOUNT) FROM BONUS");
System.out.println("warning " + conn.warning());
for (TurborelException condition : conn.told().takeConditions()) {
    System.out.println(condition.getSQLState() + ": " + condition.getMessage());
}
warning 01003
01003: the statement completed with warning: null value eliminated in set function

Otherwise, granted notices, each comes as a notice before the statement's outcome, given to the handler setNoticeHandler set, or, with none, kept, the last 64, for takeNotices. A statement that fails has no completion, so its conditions come as notices. The server's own notices, as 01T01 of a transaction a reset rolled back, always come as notices.

Offer offer = new Offer(List.of(Capability.NOTICES), List.of(), Offer.none().compressFrom());
Target target = new Target.Tcp(new InetSocketAddress("127.0.0.1", 17434));
try (Connection conn = Connect.to(target, "ann", new Trust(), Timeouts.DEFAULT, offer)) {
    conn.setNoticeHandler(notice -> System.out.println("notice " + notice.sqlstate() + ": " + notice.message()));
    conn.statements().query("CREATE TABLE TIPS (AMOUNT INTEGER)");
    conn.statements().query("INSERT INTO TIPS VALUES (NULL), (5)");
    conn.statements().query("SELECT SUM(AMOUNT) FROM TIPS");
notice 01003: the statement completed with warning: null value eliminated in set function

The error is told in full in the API Reference, Errors.