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.

Appendix A: Types

This appendix maps every data type and value tag of the native protocol, 1 to 27, to the Java type the driver's codec gives and takes, with the bounds of each. The codec's classes are in the package com.turborel.jdbc.internal.codec, which the module does not export: what a program sees through JDBC, getObject and the java.sql.Types of each column, is told in ResultSet and Metadata. A number the protocol writes as a u32 is held in a Java long, 0 to 4294967295, and a u64 in a long's bits, read as unsigned.

Data types

As a column's or a parameter's type, read by TypeCodec ([PROTOCOL Data types]). A distinct type comes as its source type.

Tag Type Java
1, 5 CHARACTER, CHARACTER VARYING DataType.CharacterType: varying, length, units (CharUnits)
2 exact numeric DataType.ExactType: precision, scale
3 approximate numeric DataType.ApproximateType: precision
4 a plug-in's type DataType.PluginType: name, parameters
6, 7 BINARY, BINARY VARYING DataType.BinaryType: varying, length
8 to 12 DATE, TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE DataType.DatetimeType: kind (DatetimeKind), precision
13 INTERVAL DataType.IntervalType: a Qualifier of start and end fields (IntervalField, 0 YEAR to 5 SECOND), leading and fractional precision
14 BOOLEAN DataType.BooleanType
15 DECFLOAT DataType.DecfloatType: precision
16 array DataType.ArrayType: maximum cardinality, 1 to 65535, and element type
17 row DataType.RowType: one field or more, each a name and a type
18, 19 CHARACTER LARGE OBJECT, BINARY LARGE OBJECT DataType.LobType: kind (LobKind), length, units
22 multiset DataType.MultisetType: element type
23 structured type DataType.StructuredType: its name and its proper supertypes', each a TypeName
24 reference type DataType.ReferenceType: the referenced type, and its scope if scoped
25 JSON DataType.JsonType
26 XML DataType.XmlType: primary and secondary modifiers, and of XMLSCHEMA the schema, namespace and element
27 UUID DataType.UuidType

Granted declared-types, a column of a Prepared or a Description also carries the type it was declared with, Column.declared(), a Declared of its name and its type as SQL writes it ([PROTOCOL Declared types]): SMALLINT, INTEGER, BIGINT, DECIMAL and NUMERIC are all tag 2, and REAL, DOUBLE PRECISION and FLOAT all tag 3. Column.typeWritten() gives the declared type, else the type the tag says, as TypeText writes it.

Types nest at most 16 deep; a deeper type fails the connection.

Values

As a row, an Execute or a CopyData carries them, read by ValueCodec and written by each value ([PROTOCOL Values]).

Tag Value Java Bounds
0 null Value.NULL unknown, of a truth value too
1 character string Value.Text, a String of either character type; UTF-8, a string that is not Unicode refused
2 exact number Value.Exact: units BigInteger, scale long; toBigDecimal() units -2^127 to 2^127 - 1, scale 0 to 4294967295, every one kept; a BigDecimal holds a scale to 2147483647
3 approximate number Value.Approximate, a double its bits kept, NaN's and -0.0's too
4 a plug-in's value OctetValue.Plugin: type name, text, bytes kept as it came, and sent back unchanged
6 binary string OctetValue.Binary of either binary type
8, 9, 11 date, time, timestamp Value.Datetime: moment, zoned, precision, displacement in minutes, the instant in microseconds of UTC displacement -12:59 to +14:00 written; a displacement past the low half of its u32 refused as read
13 interval Value.Interval: Qualifier, units BigInteger months of a year-month interval, microseconds of a day-time one
14 truth value Value.Truth, a boolean
15 decimal floating point Value.Decfloat: coefficient BigInteger, exponent int; toBigDecimal() Turborel's canonical form: at most 34 digits, no trailing zero, adjusted exponent -6143 to 6144
16, 17, 22 array, row, multiset Value.Array, Value.Row, Value.Multiset, each a list of values nested at most 16 deep; a multiset of at most 65535 elements
20 large object, whole Lob.Whole: kind, octets a CLOB's octets UTF-8
21 large object, by locator Lob.Locator: kind, locator, octets, characters read by Lob requests, from M4
23 structured value Value.Structured: its type's TypeName, its attributes
24 reference OctetValue.Reference
25 JSON OctetValue.Json, its stored form; item() a JsonItem checked whole as it is read (Turborel's RULES.md D89)
26 XML Value.Xml, its serialization as CONTENT
27 UUID Value.Uuid, a java.util.UUID 16 octets, most significant first (Turborel's RULES.md D184)

The page lists 1, 6, 9 and 11 as the value tags of the character, binary, time and timestamp types. As turborel-protocol's reader takes them, a value of tag 5, 7, 10 or 12, its type's tag, is read as one of tag 1, 6, 9 or 11: CHARACTER VARYING as CHARACTER, BINARY VARYING as BINARY, and TIME and TIMESTAMP WITH TIME ZONE as TIME and TIMESTAMP, whose bodies say they are zoned. A value of tag 18 or 19, a large object's type, fails its request alone (SQLCODE -916, the connection kept), where turborel-protocol reads it (RULES.md D8); a large object comes as tag 20 or 21. A truth byte other than 0 or 1, or a JSON value damaged, fails its request so too (Appendix B).

JSON items

A JSON value's stored form is Turborel's binary tree; JsonBinary reads it and JsonBinaryWriter writes it, and JsonText gives its JSON text as Turborel writes it ([PROTOCOL Values]).

Node Item Java
0 the SQL/JSON null JsonItem.NULL
1, 2 false, true JsonItem.ScalarItem of a Value.Truth
3, 4, 5 integer, decimal, wide decimal JsonItem.ScalarItem of a Value.Exact, written in the narrowest node that holds it
6 decimal floating point JsonItem.ScalarItem of a Value.Decfloat
7 approximate JsonItem.ScalarItem of a Value.Approximate
8 string JsonItem.ScalarItem of a Value.Text
9 datetime JsonItem.ScalarItem of a Value.Datetime; it has no JSON text (SQLSTATE 22032)
10 array JsonItem.ArrayItem
11 object JsonItem.ObjectItem, its members in the order written

Arrays and objects nest at most 128 deep. A damaged document is refused, never read in part.