Alpha

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

Errors and Diagnostics

A statement that fails raises one of PEP 249's exceptions, which the module turborel holds. Each carries the SQLCODE and SQLSTATE the server gave, so a program decides by the SQLSTATE rather than by the exception's class alone. A statement that succeeds may still warn.

A failure

The exception's class follows its SQLSTATE's class: a data exception, of class 22, is a DataError; an integrity constraint violated, of class 23, an IntegrityError; a syntax error or a table not defined, a ProgrammingError; a connection failure, an OperationalError; Appendix B gives every class. Each is a turborel.Error, and each but InterfaceError a DatabaseError.

from turborel import ProgrammingError
from turborel.client import Trust, connect

conn = connect(("127.0.0.1", 7422), "ANN", Trust())
try:
    conn.query("SELECT NAME FROM NOWHERE")
except ProgrammingError as e:
    print(e.sqlcode, e.sqlstate)
    print(e.message)
    print(e.rule, e.position, e.transaction_active)
-103 2A000
table ANN.NOWHERE is not defined
X3.135-1986 §5.4 SR5 17 True
Member What
sqlcode, sqlstate, message the failure's SQLCODE, SQLSTATE and message
rule the rule of the standard, or of Turborel's design, that the failure cites, apart from the message
position where in the SQL text the failure lies: the characters before it
transaction_active whether the session's transaction is still active after it
diagnostics what more the server told of it, with diagnostics
failure the failure whole, as the server sent it

A failure the driver raises itself, such as a value it cannot send, has no rule, position or diagnostics.

Diagnostics

With the capability diagnostics, granted by default, a failure tells its severity and what it is about: a detail, a hint, its context, and the schema, table, column, data type and constraint it concerns, each where the failure has one.

from turborel import IntegrityError

conn.query("CREATE TABLE KEYS (ID INTEGER CONSTRAINT KEYS_ID PRIMARY KEY)")
conn.query("INSERT INTO KEYS VALUES (1)")
conn.query("COMMIT")
try:
    conn.query("INSERT INTO KEYS VALUES (1)")
except IntegrityError as e:
    told = e.diagnostics
    print(told.severity, told.table, told.constraint)
    print(told.detail)
conn.query("ROLLBACK")
ERROR KEYS KEYS_ID
the key (1) is held by another row

Failures that end the connection

A connection exception, of SQLSTATE class 08 but 08003, ends the connection, as do credentials refused as it is made, and any failure of its stream: a server gone, a read that waits past its timeout, a reply that is malformed. The connection is then lost, is_lost is true, and every later call raises the same failure again. A method that needs a capability the server did not grant fails with SQLSTATE 08006 before it sends anything, and the connection goes on. So does a statement whose reply holds a value the driver cannot take, such as a damaged JSON value: it fails with SQLSTATE TB916, the rest of its replies read past, and the next statement takes its own.

Warnings, notices and conditions

A statement that succeeds with a warning completes with an SQLSTATE of class 01, which warning gives. Each condition it raised, a warning or a note, comes one way: in its completion, with the capability conditions, which conditions then gives; else as a notice, with notices; else not at all. A failing statement's conditions come as notices. The server's own notices, such as 01T01 when a reset rolls a transaction back, always come as notices.

A connection keeps the last 64 notices for take_notices, or gives each to a handler as it comes:

heard = []
conn.set_notice_handler(heard.append)
conn.query("INSERT INTO KEYS VALUES (2)")
conn.reset()
print([(n.sqlstate, n.message) for n in heard])
[('01T01', '[DESIGN] Reset rolled back the transaction that was active')]

See also

Errors, the reference page; Appendix B: Errors.