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

NAME

TurborelException: the driver's error, of every failure

SYNOPSIS

package com.turborel.jdbc;

public class TurborelException extends SQLException {
    public TurborelException(int sqlcode, String sqlstate, String message);
    public TurborelException(int sqlcode, String sqlstate, String message, Details details);
    public int sqlcode();
    public @Nullable String rule();
    public OptionalLong position();
    public boolean transactionActive();
    public Map<String, String> diagnostics();

    public record Details(@Nullable String rule, @Nullable Long position, boolean active,
            Map<String, String> diagnostics) {}
}

DESCRIPTION

Every failure is a TurborelException (RULES.md D9): the server's own, as it reports it, or one the driver raises itself, with the SQLCODE and SQLSTATE of the table every Turborel driver shares, turborel-client's own where it has the case. getSQLState() gives its SQLSTATE; sqlcode(), as getErrorCode(), its SQLCODE; getMessage() what went wrong, beginning with the rule it cites if the driver raised it.

Of the server's failures, rule() gives the rule the failure cites, apart from its message; position() where in the statement it failed, counted in characters; transactionActive() whether a transaction is still active after it; and, granted diagnostics, diagnostics() what it is about, by the names SEVERITY (ERROR, FATAL, WARNING or NOTICE), DETAIL, HINT, CONTEXT, SCHEMA, TABLE, COLUMN, DATA_TYPE and CONSTRAINT, each if known. A failure the driver raises has none of them, and says no transaction is active.

A failure's rule, position and diagnostics are not serialized with it: a failure read back from its serialized form keeps its SQLCODE, SQLSTATE and message alone.

A statement's failure keeps the connection. A failure of the connection ends it: an Error of SQLSTATE class 08 but 08003, or of class 28 and SQLCODE -919, and each connection failure the driver raises.

ERRORS

The codes the driver raises itself, and those it gives the server's failures, are listed in Appendix B.

EXAMPLES

A duplicate key, granted diagnostics:

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

The User's Guide's chapter Errors and Diagnostics has more.

STANDARD

[PROTOCOL Error 'E'], [PROTOCOL Errors and notices]; [CLIENT Running statements], [CLIENT What the server tells]. The class is a java.sql.SQLException of JDBC 4.3.

SEE ALSO

Appendix B: Errors, Statements and Cursors