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.

Appendix A: Types

This appendix maps every data type and value tag of the native protocol, 1 to 27, to the C++ type the driver gives and takes, with the bounds of each, such as the exact number's units and scale, a timestamp's displacement and an interval's qualifier.

The driver reads and writes every type and value below through turborel-c, with the bounds given; a reply that breaks one fails the connection, SQLCODE -919, SQLSTATE 08006, unless the value alone is damaged, which fails its statement, as the last section says. Values gives the members that read each value and make each parameter.

Data types

A column's or a parameter's type is a turborel::data_type, read by its kind(), a turborel::kind numbered by the tag, its length(), precision() and scale(), and to_string(), the type as SQL writes it.

Tag Type What it carries
1 CHARACTER length; units characters or octets
2 exact numeric precision and scale
3 approximate numeric precision, in bits
4 a plug-in's type its name, UTF-8; at most 2 parameters
5 CHARACTER VARYING as CHARACTER
6, 7 BINARY, BINARY VARYING length
8 to 12 DATE, TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE precision
13 INTERVAL start and end fields, 0 YEAR, 1 MONTH, 2 DAY, 3 HOUR, 4 MINUTE, 5 SECOND; leading and fractional precision
14 BOOLEAN nothing
15 DECFLOAT precision
16 array maximum cardinality, 1 to 65535; element type
17 row one or more fields, each a name and a type
18, 19 CLOB, BLOB length, up to 64 bits; units
22 multiset element type
23 structured type its schema and name; its proper supertypes
24 reference type the referenced type's names; its scope, if scoped
25 JSON nothing
26 XML primary modifier DOCUMENT, CONTENT or SEQUENCE; secondary UNTYPED, ANY or XMLSCHEMA, and of XMLSCHEMA the schema's names, its namespace and element if named; SEQUENCE is untyped
27 UUID nothing

Arrays, rows and multisets nest at most 16 deep, as Turborel's types do. A distinct type is told as its source type, and a plug-in's type the client does not know reads by its name, written UNREGISTERED, as Turborel's own client writes it.

A result's or prepared statement's column also tells whether it is NOT NULL, its not_null. Granted the capability declared-types, which a connection asks for, a column has the type it was declared with too: its declared_name, the Information Schema's DATA_TYPE, as INTEGER, and its type_written, as SQL writes it, so INTEGER is told from NUMERIC(10,0).

Values

A value is a turborel::value, read by its kind(); its readers each give one kind, and fail, SQLCODE -910, SQLSTATE TB910, of another. get<T>() reads it as T, and get<std::optional<T>>() gives an empty optional of the null value.

Tag Value Read as Sent as Bounds
0 null is_null(); an empty std::optional std::nullopt, nullptr, an empty std::optional
1 character string std::string_view, std::string std::string_view, const char* UTF-8
2 exact number turborel::decimal; std::int64_t of scale 0 where it fits turborel::decimal; an integer type, but bool and char units the whole of turborel::int128; scale the whole of std::uint32_t
3 approximate number double, its 64 bits kept double every bit kept: NaN, -0.0 and the infinities too
4 a plug-in's value its text, text(); its bytes, bytes() the value read, copied kept and sent back unchanged
6 binary string std::span<const std::byte> std::span<const std::byte>
8 date turborel::date, a std::chrono::year_month_day turborel::date 0001-01-01 to 9999-12-31
9 time turborel::time: UTC since midnight, std::chrono::microseconds; displacement, std::chrono::minutes; zoned; precision turborel::time within a day; displacement -12:59 to +14:00
11 timestamp turborel::timestamp: a std::chrono::sys_time of microseconds, displacement, zoned, precision turborel::timestamp 0001 to 9999; displacement as a time's
5, 7, 10, 12 the types' own tags read as 1, 6, 9 and 11, as turborel-protocol's reader takes them: a character string, a binary string, a time and a timestamp, a zone told inside; the driver sends only 1, 6, 9 and 11
13 interval turborel::interval: its qualifier and turborel::int128 units, months of a year-month interval, microseconds of a day-time one; std::chrono::months or std::chrono::microseconds where they fit turborel::interval fields 0 to 5
14 truth value bool bool unknown is null
15 DECFLOAT turborel::decfloat: coefficient turborel::int128, exponent std::int32_t turborel::decfloat canonical: at most 34 digits, no trailing zero, zero of exponent 0, adjusted exponent -6143 to 6144
16, 17 array, row size() and at(i), each a turborel::value nested at most 16 deep
20 large object whole lob(), a turborel::lob_info; its octets, text() or bytes() std::string_view, std::span<const std::byte> a character one's UTF-8
18, 19 a large object's stored form, which no server sends refused: the statement fails, SQLCODE -916, SQLSTATE TB916, the connection kept (RULES.md D8)
21 large object by locator lob(): character or binary, its octets and characters, read as Large Objects says a locator a turborel::lob_writer made
22 multiset size() and at(i) at most 65535 elements
23 structured value size() and at(i), its attributes
24 reference bytes()
25 JSON json(), JSON text; bytes(), the stored form of Turborel's RULES.md D89 turborel::json_text checked whole; nested at most 128 deep
26 XML text(), its serialization as CONTENT, UTF-8; turborel::xml_tree::of, its nodes turborel::xml_text
27 UUID turborel::uuid, 16 std::bytes turborel::uuid exactly 16

Every value reads as text too, by to_string(), as Turborel displays it: a string as itself, a number as Turborel writes it, a datetime as its literal's string, an array, row, multiset, structured value or reference as its literal, NULL of the null value.

A datetime's microseconds count from 0001-01-01 UTC, as Turborel keeps them. A datetime made out of 0001 to 9999 fails with SQLSTATE 22008, and a displacement out of range with 22009, each with SQLCODE -301.

A JSON value's text is written as Turborel writes it: no white space, members in the order written, an exact number's digits, its scale kept, 1.50 as 1.50, a DECFLOAT plain, an approximate number as its shortest numeral with an exponent, 1.5E0. A JSON text made into a parameter takes a number without an exponent as exact, one of more digits than an exact number holds as a DECFLOAT, and one with an exponent as approximate. Text no JSON value is fails, SQLCODE -301, SQLSTATE 22032; text nesting arrays and objects past 128 fails before it is sent, SQLCODE -900, SQLSTATE 0A000, as Turborel refuses it. A JSON value that holds a datetime, or an approximate number that is not finite, has no JSON text: json() fails, SQLSTATE 22032, and bytes() gives its stored form.

A value the driver cannot take

A reply whose frame is whole but holds a value the driver cannot take, such as a truth value's byte other than 0 or 1, a damaged JSON document or one of another version, or tag 18 or 19, fails its statement alone, SQLCODE -916, SQLSTATE TB916, or -900, SQLSTATE 0A000, of a value past a limit; the rest of the statement's replies are read past, and the connection goes on. Only a malformed frame, cut short, with bytes after its last field, or of a kind not known, loses the connection, SQLCODE -919, SQLSTATE 08006.