README

Name

Protocol::Postgres - a sans-io postgresql client

Synopsis

use v6.d;
use Protocol::Postgres;

my $socket = await IO::Socket::Async.connect($host, $port);
my $client = Protocol::Postgres::Client.new;
$socket.Supply(:bin).act({ $client.incoming-data($^data) });
$client.outbound-data.act({ $socket.write($^data) });

await $client.startup($user, $database, $password);

my $resultset = await $client.query('SELECT * FROM foo WHERE id = $1', [ 42 ]);
react {
	whenever $resultset.hash-rows -> (:$name, :$description, :$id) {
		say "$name is $description";
	}
}

Description

Protocol::Postgres is sans-io implementation of (the client side of) the postgresql protocol. It is typically used through the Protocol::Postgres::Client class.

Client

Protocol::Postgres::Client has the following methods

new(--> Protocol::Postgres::Client)

This creates a new postgres client. It supports one optional named argument:

TypeMap :$typemap = TypeMap::JSON
This is the typemap that is used to translate between Raku's and Postgres' typesystem. The default mapping supports common built-in types such as strings, numbers, bools, dates, datetimes, blobs, arrays and hashes. Other options include TypeMap::Native if you want arrays to map to postgres' native arrays and TypeMap::Minimal if one wants all values to map to strings.

outgoing-data(--> Supply)

This returns a Supply of Blobs to be written to the server.

incoming-data(Blob --> Nil)

This consumes bytes received from the server.

startup(database?, $password? --> Promise)

This starts the handshake to the server. $database may be left undefined, the server will use $user as database name. If a $password is defined, any of clearnext, md5 or SCRAM-SHA-256 based authentication is supported.

The resulting promise will finish when the connection is ready for queries.

query($query, @bind-values --> Promise)

This will issue a query with the given bind values, and return a promise to the result.

For fetching queries such as SELECT the result in the promise will be a ResultSet object, for manipulation (e.g. INSERT) and definition (e.g. CREATE) queries it will result a string describing the change (e.g. DELETE 3). For a COPY FROM query it will Supply with the data stream, and for COPY TO it will be a Supplier.

Both the input types and the output types will be typemapped between Raku types and Postgres types using the typemapper.

query-multiple($query --> Supply[ResultSet])

This will issue a complex query that may contain multiple statements, but can not use bind values. It will return a Supply to the results of each query.

prepare($query, :@input-types --> Promise[PreparedStatement])

This prepares the query, and returns a Promise to the PreparedStatement object. @input-types can be used to pass on hints about the types you're passing in during execute.

startTls(--> Blob)

This will return the marker that should be written to the server to start upgrading the connection to use TLS. If the server responds with a single S byte the proposal is accepted and the client is expected to initiate the TLS handshake. If the server responds with an N it is rejected, and the connection proceeds in cleartext.

terminate(--> Nil)

This sends a message to the server to terminate the connection

notifications(--> Supply[Notification])

This returns a supply with all notifications that the current connection is subscribed to. Channels can be subscribed using the LISTEN command, and messages can be sent using the NOTIFY command.

disconnected(--> Promise)

This returns a Promise that must be be kept or broken to signal the connection is lost.

process-id(--> Int)

This returns the process id of the backend of this connection. This is useful for debugging purposes and for notifications.

get-parameter(Str $name --> Str)

This returns various parameters, currently known parameters are: server_version, server_encoding, client_encoding, application_name, default_transaction_read_only, in_hot_standby, is_superuser, session_authorization, DateStyle, IntervalStyle, TimeZone, integer_datetimes, and standard_conforming_strings.

ResultSet

A Protocol::Postgres::ResultSet represents the results of a query, if any.

columns(--> List)

This returns the column names for this resultset.

rows(--> Supply[List])

This returns a Supply of rows. Each row is a list of values.

hash-rows(--> Supply[Hash])

This returns a Supply of rows. Each row is a hash with the column names as keys and the row values as values.

object-rows(::Class, Bool :$positional --> Supply[Class])

This returns a Supply of objects of class Class, each object is constructed form the row hash unless positional is true in which case it's constructed from the row list.

PreparedStatement

A Protocol::Postgres::PreparedStatement represents a prepated statement. Its reason of existence is to call execute on it.

execute(@arguments --> Promise[ResultSet])

This runs the prepared statement, much like the query method would have done.

close()

This closes the prepared statement.

columns()

This returns the columns of the result once executed.

Notification

Protocol::Postgres::Notification has the following methods:

sender(--> Int)

This is the process-id of the sender

channel(--> Str)

This is the name of the channel that the notification was sent on

message(--> Str)

This is the message of the notification

Author

Leon Timmermans [email protected]

Copyright and License

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.