Marmos
v juptune
v asn1
v lang
v ast
v Classes
v Enums
v ir
v parser
v Enums
v Structs
v core
v crypto
v keyexchange
v memory
v data
v alphabet
v buffer
v json
v builder
v parser
v Enums
v Structs
v serialise
v Structs
v Templates
v pem
v Enums
v Structs

Structs PostgresProtocol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
module juptune.postgres.protocol.connection;

struct PostgresProtocol
{
    /++ ALIASES ++/
    
    ///
    alias BindParameterHandlerGcT = Result function(const int paramIndex, PostgresProtocol psql, bool moreParamsLeftToBind);
    /// A callback provided by the user which gives them a chance to bind as many parameters as they desire to a prepared statement. 
    alias BindParameterHandlerT = Result function(const int paramIndex, PostgresProtocol psql, bool moreParamsLeftToBind);
    ///
    alias ColumnDescriptionHandlerGcT = Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription);
    /// A callback provided by the user which gives them a chance to inspect all PostgresColumnDescription for a query/table. The nextDescription callback can only be called up to columnCount amount of times. 
    alias ColumnDescriptionHandlerT = Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription);
    ///
    alias DataRowHandlerGcT = Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData);
    /// A callback provided by the user which gives them a chance to retrieve all data for a query. The nextData callback can only be called up to columnCount amount of times. 
    alias DataRowHandlerT = Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData);
    /// Delegate for handling a raw incoming Postgres message - currently not used by the public API. 
    alias MessageHandlerT = Result function(PostgresMessageType type, MemoryReader reader);
    /// A callback provided by PostgresProtocol which will fetch the next raw bytes of a column value from a protocol message. 
    alias NextColumnDataT = Result function(MemoryReader valueReader, bool isNull);
    /// A callback provided by PostgresProtocol which will fetch the next PostgresColumnDescription from a protocol message. 
    alias NextColumnDescriptionT = Result function(PostgresColumnDescription desc);
    ///
    alias __xdtor = __MARMOS_BUG__;
    ///
    alias __xpostblit = __MARMOS_BUG__;
    
    /++ FUNCTIONS ++/
    
    /// Sends a Bind, Describe, and Execute message (followed by a Sync message) simultaneously, which effectively binds parameters onto a prepared statement; describes what the return results are, and then executes the query which provides the actual return results. 
    Result bindDescribeExecute(const char[] statementName, PostgresColumnDescription.Format[] paramFormatCodes, PostgresColumnDescription.Format[] resultFormatCodes, Result function(const int paramIndex, PostgresProtocol psql, bool moreParamsLeftToBind) bindParameterOrNull, Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription) onRowDescriptionOrNull, Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData) onDataRowOrNull);
    /// ditto. 
    Result bindDescribeExecuteGc(const char[] statementName, PostgresColumnDescription.Format[] paramFormatCodes, PostgresColumnDescription.Format[] resultFormatCodes, Result function(const int paramIndex, PostgresProtocol psql, bool moreParamsLeftToBind) bindParameterOrNull, Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription) onRowDescriptionOrNull, Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData) onDataRowOrNull);
    /// ditto. 
    Result bindDescribeExecuteInfer(BindParameterT, ColumnHandlerT, DataHandlerT)(const char[] statementName, const PostgresColumnDescription.Format[] paramFormatCodes, const PostgresColumnDescription.Format[] resultFormatCodes, BindParameterT bindParameterOrNull, ColumnHandlerT onRowDescriptionOrNull, DataHandlerT onDataRowOrNull);
    /// Sends a Close message (followed by a Sync message) simultaneously, which tells the backend to close a prepared statement by its name. If no prepared statement for the given name exists, then nothing happens. 
    Result closeStatement(const char[] statementName);
    /// Public API (connecting) 
    Result connect(IpAddress address, PostgresConnectInfo connectInfo);
    /// Whether or not this instance is "safe" to use/ready to issues query-related messages. 
    bool isReadyToQuery();
    ///
    PostgresProtocol opAssign(PostgresProtocol p);
    /// The current set of parameters the client & server are operation under. 
    PostgresParameters params();
    /// Sends a Prepare message (followed by a Sync message), which generates a prepared query that can then be used with bindDescribeExecute . 
    Result prepare(const char[] statementName, const char[] query, PostgresDataTypeOid[] paramTypes);
    /// Public API (querying) 
    Result simpleQuery(const char[] query, Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription) onRowDescriptionOrNull, Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData) onDataRowOrNull);
    ///
    Result simpleQueryGc(const char[] query, Result function(ushort columnCount, Result function(PostgresColumnDescription desc) nextDescription) onRowDescriptionOrNull, Result function(ushort columnCount, Result function(MemoryReader valueReader, bool isNull) nextData) onDataRowOrNull);
    
}

Documentation

A lowish-level client providing functionality for connecting and communicating to a server using the Postgres protocol.

The idea of this particular struct is to be a very raw, straightforward-yet-clunky way of accessing the actual Postgres protocol with as little overhead as possible, and that other higher-level abstractions can be built on top of it for more comfortable use cases.

Memory

Unlike a lot of other protocol implementations within Juptune, this struct will dynamically manage its own memory rather than using preallocated user-provided buffers.

This is because the easiest way (by far) to deal with Postgres protocol messages is to read them entirely into memory first before processing them, rather than trying to piece a bunch of network reads together using a single smaller buffer.

Due to the natural variability of payload sizes when using a database like Postgres, it's inevitable that said buffer would either need to be very large to handle the occasional large payload, or dynamic so that it can handle general workloads without wasting as much memory all the time.

This is of course a tradeoff, however it is exceedingly more likely that Postgres itself will be the bottleneck rather than the ultimately minimal performance costs of constantly (in the worst case) resizing an internal buffer.

Usage

Internally a state machine is used to ensure correct usage of this struct.

First call .connectto connect and authenticate to a Postgres instance.

For simple querying (where you don't need any external parameters being passed in), use .simpleQuery.

For advanced/prepared querying, first call .prepareto prepare the query; then call bindDescribeExecuteto actually execute the query, and optionally call .closeso that the server can release resources associated with the prepared statement.

Limitations

Currently only SCRAM-SHA-256 is supported as the authentication method.

Unix sockets as a transport medium are not supported.

Not all parts of the protocol are implemented, e.g. replication streaming, COPY support, query cancellation.

Aliases

Name Description
BindParameterHandlerGcT
BindParameterHandlerT

A callback provided by the user which gives them a chance to bind as many parameters as they desire to a prepared statement.

ColumnDescriptionHandlerGcT
ColumnDescriptionHandlerT

A callback provided by the user which gives them a chance to inspect all PostgresColumnDescriptionfor a query/table. The nextDescriptioncallback can only be called up to columnCountamount of times.

DataRowHandlerGcT
DataRowHandlerT

A callback provided by the user which gives them a chance to retrieve all data for a query. The nextDatacallback can only be called up to columnCountamount of times.

MessageHandlerT

Delegate for handling a raw incoming Postgres message - currently not used by the public API.

NextColumnDataT

A callback provided by PostgresProtocolwhich will fetch the next raw bytes of a column value from a protocol message.

NextColumnDescriptionT

A callback provided by PostgresProtocolwhich will fetch the next PostgresColumnDescriptionfrom a protocol message.

__xdtor
__xpostblit

Functions

Name Description
bindDescribeExecute

Sends a Bind, Describe, and Execute message (followed by a Sync message) simultaneously, which effectively binds parameters onto a prepared statement; describes what the return results are, and then executes the query which provides the actual return results.

bindDescribeExecuteGc

ditto.

bindDescribeExecuteInfer

ditto.

closeStatement

Sends a Close message (followed by a Sync message) simultaneously, which tells the backend to close a prepared statement by its name. If no prepared statement for the given name exists, then nothing happens.

connect

Public API (connecting)

isReadyToQuery

Whether or not this instance is "safe" to use/ready to issues query-related messages.

opAssign
params

The current set of parameters the client & server are operation under.

prepare

Sends a Prepare message (followed by a Sync message), which generates a prepared query that can then be used with bindDescribeExecute.

simpleQuery

Public API (querying)

simpleQueryGc