Alpha

These pages are built from turborel-cpp’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 is thrown as a turborel::error, a std::runtime_error that holds the whole failure: its SQLCODE and SQLSTATE, its message, the rule it cites, where in the statement it was found, whether the transaction is still active, and, granted diagnostics, more about it. A statement's warnings come too, as conditions or notices, and its completion tells what it did. This chapter shows each; Errors gives the types, and Appendix B: Errors every code the driver gives.

A failure

what() reads as Turborel's own client writes a failure; sqlcode(), sqlstate() and message() give its parts, and details() the whole turborel::failure. With diagnostics, which a connection asks for, its diagnostics say its severity, and the schema, table, column, data type and constraint it is about, where known:

Made beforehand, as the owner:

CREATE TABLE STAFF (ID INTEGER CONSTRAINT STAFF_KEY PRIMARY KEY, NAME VARCHAR(20));
INSERT INTO STAFF VALUES (1, 'Ada');
#include <turborel/turborel.hpp>

#include <iostream>

int main() {
  turborel::mechanism trust = turborel::mechanism::trust();
  turborel::connection conn = turborel::connection::connect(turborel::target::tcp("127.0.0.1", 17439), "ann", trust);
  try {
    static_cast<void>(conn.query("SELECT NAME FROM STAF"));
  } catch (const turborel::error& e) {
    std::cout << e.what() << '\n';
    std::cout << e.sqlcode() << ' ' << e.sqlstate() << ", rule " << e.details().rule.value_or("none")
              << ", at " << e.details().position.value_or(0) << '\n';
  }
  try {
    static_cast<void>(conn.query("INSERT INTO STAFF VALUES (1, 'Grace')"));
  } catch (const turborel::error& e) {
    const turborel::diagnostics told = e.details().diagnostics.value_or(turborel::diagnostics{});
    std::cout << e.sqlstate() << ' ' << told.severity.value_or("?") << ", table " << told.table.value_or("?")
              << ", constraint " << told.constraint.value_or("?") << ", active " << std::boolalpha
              << e.details().active << '\n';
  }
}
SQLCODE -103 (SQLSTATE 2A000): table ANN.STAF is not defined [X3.135-1986 §5.4 SR5] (at character 17)
-103 2A000, rule X3.135-1986 §5.4 SR5, at 17
23000 ERROR, table STAFF, constraint STAFF_KEY, active true

A failure of the session's own, as a server lost, a reply that cannot be read or a wait that runs out, loses the connection, SQLCODE -919, SQLSTATE 08006; every call on it after fails. A statement's failure leaves the connection as it was, its transaction active or rolled back as details().active says. Memory not had is thrown as std::bad_alloc, as C++ throws it.

What a statement tells

A statement's completion tells, granted the capabilities a connection asks for, the rows it changed or a query returned, rows_affected(); the identity values an INSERT generated, generated(); the server's time for it, server_time(); and the log position of the commit it made, commit_position(), of a database kept on disk. Its warnings come one way: with conditions, in its completion, conditions(), the completion's own SQLSTATE warning(); else as notices, to a handler of on_notice, or the last 64 kept, notices():

Made beforehand, as the owner:

CREATE TABLE ORDERS (ID INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY, ITEM VARCHAR(5));
CREATE PROCEDURE WARNS () MODIFIES SQL DATA SIGNAL SQLSTATE '01ABC';
#include <turborel/turborel.hpp>

#include <iostream>

int main() {
  turborel::mechanism trust = turborel::mechanism::trust();
  turborel::connection conn = turborel::connection::connect(turborel::target::tcp("127.0.0.1", 17439), "ann", trust);
  static_cast<void>(conn.query("INSERT INTO ORDERS (ITEM) VALUES ('tea'), ('jam')"));
  std::cout << conn.rows_affected().value_or(0) << " rows, ids";
  for (const std::string_view id : conn.generated()) {
    std::cout << ' ' << id;
  }
  std::cout << '\n' << "timed " << std::boolalpha << conn.server_time().has_value() << '\n';
  const turborel::statement insert = conn.prepare("INSERT INTO ORDERS (ITEM) VALUES (?)");
  static_cast<void>(conn.execute(insert, turborel::params::of("marmalade")));
  std::cout << "warning " << conn.warning().value_or("none") << ": " << conn.conditions().at(0).message << '\n';
  static_cast<void>(conn.query("CALL WARNS()"));
  for (const turborel::failure& condition : conn.conditions()) {
    std::cout << "condition " << condition.sqlstate << '\n';
  }
  turborel::connect_options no_conditions;
  no_conditions.ask_none().ask(turborel::capability::notices).ask(turborel::capability::diagnostics);
  turborel::connection noticed =
      turborel::connection::connect(turborel::target::tcp("127.0.0.1", 17439), "ann", trust, no_conditions);
  noticed.on_notice([](const turborel::failure& notice) {
    std::cout << "notice " << notice.sqlstate << ' '
              << notice.diagnostics.value_or(turborel::diagnostics{}).severity.value_or("?") << '\n';
  });
  static_cast<void>(noticed.query("CALL WARNS()"));
  static_cast<void>(conn.query("ROLLBACK"));
}
2 rows, ids 1 2
timed true
warning 01004: the statement completed with warning: string data, right truncation
condition 01ABC
notice 01ABC WARNING

The server's own notices, as Reset's 01T01, always come as notices.