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.

Pipelines

NAME

Pipeline: a connection's requests sent without waiting for each reply, one outcome each, in order.

SYNOPSIS

namespace Turborel.Data.Session;

public sealed partial class NativeConnection
{
    public Pipeline Pipeline();
}
public sealed class Pipeline
{
    public const int Window = 65_536;
    public PipelineOnError OnError { get; set; }
    public int Count { get; }
    public Pipeline Query(string sql);
    public Pipeline Execute(PreparedStatement statement, IReadOnlyList<object?> values);
    public Task<IReadOnlyList<Piped>> RunAsync(CancellationToken cancellationToken = default);
}
public enum PipelineOnError { Continue, Skip }
public abstract record Piped;
public sealed record PipedDone(Outcome Outcome) : Piped;
public sealed record PipedFailed(TurborelException Failure) : Piped;
public sealed record PipedSkipped : Piped;

DESCRIPTION

Query queues a statement, run as QueryAsync runs it; Execute an execution of a prepared statement, as ExecuteAsync runs it, all of a query's rows. RunAsync writes the requests a window of at most Window bytes at a time, a request longer than that alone in its own, and reads each window's replies before the next is written, so client and server never each wait for the other to read. Each request has its outcome, in the order queued: PipedDone, or PipedFailed, a failure of its request alone, the requests after it run. Under Autocommit each request is its own transaction.

Under PipelineOnError.Skip the batch stops at its first failure, the requests before it kept: a savepoint, SAVEPOINT TURBOREL_PIPELINE_n, is set before each request but the first; the requests after a failed one are rolled back to the savepoint set after it, and those of a window not yet written never sent; each is PipedSkipped. The first savepoint is then released, and under autocommit, of a batch that began no transaction, the batch is committed, no request of it having ended it. What a rollback undoes is undone; a session's settings are not.

ERRORS

SQLSTATE SQLCODE When
(the server's) A request's failure, its own outcome
08006 -919 The connection lost: RunAsync gives no outcome
(the server's) A skipping batch's savepoints that cannot be rolled back or released, or its commit

EXAMPLES

See Pipelines and Pools.

STANDARD

[PROTOCOL Requests] of The Native Protocol; [CLIENT Pipelines] of Settings, Pipelines and Pools.

SEE ALSO

Statements and Cursors, Pools.