Values
NAME
The value classes: what each value of the protocol is read into, and written from.
SYNOPSIS
Turborel::Datetime.new(moment:, utc:, zone:, zoned:, precision:)
Turborel::Interval.new(start:, finish:, leading:, fraction:, units:)
Turborel::Decimal.new(units:, scale:)
Turborel::DecFloat.new(coefficient:, exponent:)
Turborel::Lob.new(kind:, data:, locator:, octets:, characters:)
Turborel::Row.new(values:)
Turborel::Multiset.new(values:)
Turborel::Structured.new(schema:, name:, attributes:)
Turborel::Reference.new(octets:)
Turborel::Json.new(value:)
Turborel::Xml.new(text:)
Turborel::Uuid.new(octets:)
Turborel::Extension.new(name:, text:, bytes:)
Turborel::DataType.new(kind:, params:)
Turborel::Column.new(name:, type:, not_null:, declared: nil) # type_written, type_name
Turborel::Declared.new(name:, written:)
Turborel::Parameter.new(varying:, type:)
DESCRIPTION
A value of the protocol is read as a Ruby value where Ruby has one:
nil, a String, an Integer or a BigDecimal, a Float, true or
false, or an Array. Every other is read as one of the classes above,
each an immutable Data whose fields are those the protocol writes, so a
value read and written back is the value read. Appendix
A maps each tag to its class and gives the
bounds of each field.
A value given as a parameter, or as a field of a row copied in, is
written from the same classes. An exact number comes as an Integer
where its scale is 0 and as a BigDecimal otherwise, exactly in both
cases. Within a JSON value a decimal is read as a Turborel::Decimal,
its units and scale as written, so 1.50 stays 1.50; one is written
at its own scale wherever it is given.
What the server describes of a result's columns and a statement's
parameters is a Column and a Parameter, each with its DataType.
A column's declared type, a Declared, is told where the server
grants declared-types, which a connection asks for unless told: its
name, as the Information Schema's DATA_TYPE gives it, and the type
written as SQL writes it, so an INTEGER column, whose values are an
exact number's of precision 10, is told apart from a NUMERIC(10,0) one.
type_written and type_name give it, or, where it was not told, the
type its tag says, as NUMERIC(10,0) and NUMERIC.
A program receives values and passes them so through the low-level client, as Statements and Cursors tells, through the plain API, as Turborel::Connection tells, and through the ActiveRecord adapter, which casts them to ActiveRecord's types, as The ActiveRecord Adapter tells.
ERRORS
| SQLSTATE | SQLCODE | When |
|---|---|---|
| 22000 | -301 | A value of a class the driver does not send, or a datetime's moment, an interval's field or a large object's kind that is none of the protocol's |
| 0A000 | -900 | Values nested deeper than 16, 128 within a JSON value, or a JSON value's stored form longer than 256 MiB |
| 22003 | -301 | A number out of the range of its field: an Integer or BigDecimal whose units do not fit an i128, a NaN or infinite BigDecimal, a displacement that does not fit an i16, a DECFLOAT not in its one form, a UUID not of 16 octets |
| 22021 | -301 | A string that cannot be written as UTF-8 |
| 08006 | -919 | A value received that is malformed: a tag no value has, a body cut short, a DECFLOAT value not in its one form |
| TB916 | -916 | A value received that cannot be taken: a truth byte other than 0 or 1, damaged JSON, a value of tag 18 or 19; its request fails, the connection kept |
| 0A000 | -900 | A JSON value received nested past 128 or longer than 256 MiB, its request failing so |
EXAMPLES
stamp = Turborel::Datetime.new(moment: :timestamp, utc: 0, zone: 60, zoned: true, precision: 6)
stamp.zone # => 60
STANDARD
[PROTOCOL Values], [PROTOCOL Data types] and [PROTOCOL Composite fields] of The Native Protocol; the JSON value's binary tree, Turborel's RULES.md D89.