Alpha

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

Values

NAME

The value types: what the codec gives each of the protocol's values as, and takes to send one.

SYNOPSIS

namespace Turborel.Data.Types;

public readonly record struct TurborelDecimal(Int128 Units, uint Scale)
{
    public static TurborelDecimal FromDecimal(decimal value);
    public bool TryToDecimal(out decimal value);
}
public readonly record struct TurborelDecFloat
{
    public Int128 Coefficient { get; }
    public int Exponent { get; }
    public static bool TryCreate(Int128 coefficient, int exponent, out TurborelDecFloat value);
}
public readonly record struct TurborelDatetime(DatetimeMoment Moment, long UtcMicroseconds, short ZoneMinutes,
    bool Zoned, byte Precision);
public readonly record struct TurborelInterval(IntervalQualifier Qualifier, Int128 Units);
public sealed class TurborelJson
{
    public static TurborelJson Parse(string text);
    public string ToJsonText();
}
public sealed record TurborelXml(string Text)
{
    public IReadOnlyList<XNode> Nodes();
}
public sealed record TurborelArray(IReadOnlyList<object?> Elements);
public sealed record TurborelRow(IReadOnlyList<object?> Fields);
public sealed record TurborelMultiset(IReadOnlyList<object?> Elements);
public sealed record TurborelStructuredValue(string Schema, string Name, IReadOnlyList<object?> Attributes);
public sealed record TurborelReference(ReadOnlyMemory<byte> Bytes);
public sealed record TurborelPluginValue(string TypeName, string Text, ReadOnlyMemory<byte> Bytes);
public sealed record TurborelLargeObject;

public abstract record DataType;
public sealed record CharacterType(uint Length, CharacterUnits Units, bool Varying) : DataType;
public sealed record ExactType(uint Precision, uint Scale) : DataType;
// ... one record a data type, as Appendix A lists them

DESCRIPTION

Each value of the native protocol is read as a type of the driver's own, or a .NET type where one holds it whole: string, double, bool, byte[] and Guid; SQL's null is null. A parameter takes the same types. Appendix A lists each, with its bounds, and the data type, a record derived from DataType, that describes a column or a parameter of each.

An exact number is a TurborelDecimal, its units an Int128 and its scale a uint, as the protocol carries them, since .NET's decimal holds 96 bits; FromDecimal makes one of a decimal, and TryToDecimal gives one back where a decimal holds it. Its text is SQL's. A datetime is a TurborelDatetime: its instant, microseconds in UTC from 0001-01-01 00:00:00, a date's its midnight's and a time's from midnight UTC, within a day; and the zone's displacement in minutes.

A JSON value is a TurborelJson, the stored form the server keeps, checked whole as it is read; ToJsonText writes it as the server writes JSON text, and Parse makes one of JSON text as the server parses it. An XML value is a TurborelXml, its serialization as CONTENT; Nodes parses its nodes from it, whitespace kept, no document type declaration read, and one is sent as a parameter made of its text. A value the server cannot serialize, as an attribute standing alone, fails the fetch with SQLSTATE 2200W. A UUID is a Guid: ToByteArray(bigEndian: true) gives its 16 octets in their order, ToString its text, and a parameter is made of its octets by new Guid(octets, bigEndian: true) or of its text by Guid.Parse. A large object is a TurborelLargeObject, described in Large Objects.

EXAMPLES

using System.Xml.Linq;
using Turborel.Data.Authentication;
using Turborel.Data.Session;
using Turborel.Data.Transport;
using Turborel.Data.Types;

await using NativeConnection connection =
    await NativeConnection.ConnectAsync(new TcpTarget("localhost", 17435), "ann", new TrustMechanism());
await connection.QueryAsync("CREATE TABLE ORDERS (ID UUID, BODY XML(CONTENT), DETAIL JSON)");
PreparedStatement insert = await connection.PrepareAsync("INSERT INTO ORDERS VALUES (?, ?, ?)");
await connection.ExecuteAsync(insert, [
    Guid.Parse("919108f7-52d1-4320-9bac-f847db4148a8"),
    new TurborelXml("<order no=\"18\"><item>jam</item></order>"),
    TurborelJson.Parse("{\"rush\": true, \"weight\": 1.50}"),
]);
var rows = (RowsOutcome)await connection.QueryAsync("SELECT ID, BODY, DETAIL FROM ORDERS");
var id = (Guid)rows.Rows[0][0]!;
var body = (TurborelXml)rows.Rows[0][1]!;
var detail = (TurborelJson)rows.Rows[0][2]!;
Console.WriteLine($"{id} = {Convert.ToHexString(id.ToByteArray(bigEndian: true))}");
var order = (XElement)body.Nodes()[0];
Console.WriteLine($"{body.Text}: order {order.Attribute("no")?.Value} of {order.Element("item")?.Value}");
Console.WriteLine(detail.ToJsonText());
await connection.QueryAsync("ROLLBACK");
919108f7-52d1-4320-9bac-f847db4148a8 = 919108F752D143209BACF847DB4148A8
<order no="18"><item>jam</item></order>: order 18 of jam
{"rush":true,"weight":1.50}

ERRORS

SQLSTATE SQLCODE When
08006 -919 A frame read from the server is malformed, as a value cut short
TB916 -916 A value read from the server that the client cannot take, in a frame read whole: a length's units or a truth value other than 0 or 1, damaged JSON, a Complete's condition that cannot be read, value tags 18 and 19. Its request fails, the rest of its replies read past first, and the connection goes on
22000 -301 A value to send is of no type the protocol carries
22032 -301 Text is not JSON text, or a JSON value holds a datetime or an approximate number not finite, which have no text
22003 -301 JSON text holds a number no number of turborel's is
2200N -301 An XML value's text is not well-formed content
2200W -301 The server cannot serialize an XML value it would send
0A000 -900 A JSON value nests deeper than 128, or its stored form is longer than 256 MiB: to send, or read, its request failed as TB916's is

STANDARD

[PROTOCOL Data types] and [PROTOCOL Values] of The Native Protocol; [PROTOCOL JSON values] for the JSON value's stored form; [CLIENT XML values] and [CLIENT UUIDs] of The Client Library.

SEE ALSO

Appendix A: Types, Errors.