Protocol::Dqlite - Dqlite in Perl
use autodie; my $dqlite = Protocol::Dqlite->new(); my $socket = IO::Socket::INET->new('127.0.0.1:9001') or die; syswrite $s, Protocol::Dqlite::handshake(); # Register ourselves as a Dqlite client: syswrite $s, Protocol::Dqlite::request( Protocol::Dqlite::REQUEST_CLIENT, 0 ); # Await the server’s acknowledgement: while (sysread $s, my $buf, 512) { my ($msg) = $dqlite->feed($buf); next if !$msg; last if $msg isa Protocol::Dqlite::Response::WELCOME; # An unexpected response. Better bail out … # require Data::Dumper; die Data::Dumper::Dumper($msg); }
… and now you can exchange messages as you wish.
This module implements message parsing and creation for Dqlite clients. To use this module you’ll need to write the I/O logic yourself.
Strings designated as “blob”s are byte strings.
All other strings into & out of this module are character strings.
Decode & encode accordingly.
The following derive from the documentation of Dqlite’s wire protocol as well as protocol.h in Dqlite’s source code.
ROLE_VOTER, ROLE_STANDBY, ROLE_SPARE
ROLE_VOTER
ROLE_STANDBY
ROLE_SPARE
Numbers: TUPLE_INT64, TUPLE_FLOAT
TUPLE_INT64
TUPLE_FLOAT
Buffers: TUPLE_STRING, TUPLE_BLOB
TUPLE_STRING
TUPLE_BLOB
Time: TUPLE_UNIXTIME, TUPLE_ISO8601
TUPLE_UNIXTIME
TUPLE_ISO8601
Other: TUPLE_NULL, TUPLE_BOOLEAN
TUPLE_NULL
TUPLE_BOOLEAN
REQUEST_LEADER (0)
REQUEST_LEADER
REQUEST_CLIENT (1)
REQUEST_CLIENT
REQUEST_OPEN (3)
REQUEST_OPEN
REQUEST_PREPARE (4)
REQUEST_PREPARE
REQUEST_EXEC (5)
REQUEST_EXEC
REQUEST_QUERY (6)
REQUEST_QUERY
REQUEST_FINALIZE (7)
REQUEST_FINALIZE
REQUEST_EXEC_SQL (8)
REQUEST_EXEC_SQL
REQUEST_QUERY_SQL (9)
REQUEST_QUERY_SQL
REQUEST_INTERRUPT (10)
REQUEST_INTERRUPT
REQUEST_CONNECT (11)
REQUEST_CONNECT
REQUEST_ADD (12)
REQUEST_ADD
REQUEST_ASSIGN (13)
REQUEST_ASSIGN
REQUEST_REMOVE (14)
REQUEST_REMOVE
REQUEST_DUMP (15)
REQUEST_DUMP
REQUEST_CLUSTER (16)
REQUEST_CLUSTER
handshake - The string to send after establishing a connection to the server.
handshake
Returns a byte buffer of a Dqlite message. $TYPE is one of the REQUEST_* constants listed above.
REQUEST_*
@ARGUMENTS are as Dqlite’s wire protocol documentation indicates. Dqlite tuples are expressed as type/value pairs.
Example:
my $bytes = Protocol::Dqlite::request( Protocol::Dqlite::REQUEST_PREPARE, 12, "SELECT ?, ?", Protocol::Dqlite::TUPLE_INT64 => 12345, Protocol::Dqlite::TUPLE_BLOB => "\x00\x01\x02", );
Instantiates CLASS.
Give new input to OBJ. Returns any messages parsed out of $BYTES as Protocol::Dqlite::Response instances.
Protocol::Dqlite::Response
All of the below extend Protocol::Dqlite::Response. They expose various accessors as documented below:
Protocol::Dqlite::Response::FAILURE: code(), message()
Protocol::Dqlite::Response::FAILURE
code()
message()
Protocol::Dqlite::Response::SERVER: id(), address(), role()
Protocol::Dqlite::Response::SERVER
id()
address()
role()
Protocol::Dqlite::Response::WELCOME: (none)
Protocol::Dqlite::Response::WELCOME
Protocol::Dqlite::Response::SERVERS: count(), id(), address(), role(); the latter 3 require an index argument, which MUST be between 0 and (count() - 1), inclusive.
Protocol::Dqlite::Response::SERVERS
count()
Protocol::Dqlite::Response::DB: id()
Protocol::Dqlite::Response::DB
Protocol::Dqlite::Response::STMT: database_id(), statement_id(), params_count()
Protocol::Dqlite::Response::STMT
database_id()
statement_id()
params_count()
Protocol::Dqlite::Response::RESULT: last_row_id(), rows_count()
Protocol::Dqlite::Response::RESULT
last_row_id()
rows_count()
Protocol::Dqlite::Response::ROWS:
Protocol::Dqlite::Response::ROWS
is_final()
column_names() - returns a list, or a count in scalar context
column_names()
row_types(), row_data() - these need an index, max=(rows_count()-1)
row_types()
row_data()
Protocol::Dqlite::Response::EMPTY: (none)
Protocol::Dqlite::Response::EMPTY
Protocol::Dqlite::Response::FILES: names() (list/count) and content() (takes an index)
Protocol::Dqlite::Response::FILES
names()
content()
To install Protocol::Dqlite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Protocol::Dqlite
CPAN shell
perl -MCPAN -e shell install Protocol::Dqlite
For more information on module installation, please visit the detailed CPAN module installation guide.