Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/db/postgres/protocol"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
db |
std/db |
codec.dodo, errors.dodo, scram.dodo, values.dodo |
float_decimal |
std/float_decimal |
values.dodo |
math |
std/math |
values.dodo |
mem |
core/mem |
values.dodo |
ptr |
core/ptr |
values.dodo |
text |
std/text |
values.dodo |
PROTOCOL_VERSION
Constant · Source
pub const PROTOCOL_VERSION: i32 = 196608
SSL_REQUEST_CODE
Constant · Source
pub const SSL_REQUEST_CODE: i32 = 80877103
CANCEL_REQUEST_CODE
Constant · Source
pub const CANCEL_REQUEST_CODE: i32 = 80877102
DEFAULT_PORT
Constant · Source
pub const DEFAULT_PORT: u16 = 5432
AUTHENTICATION
Constant · Source
Backend message tags.
pub const AUTHENTICATION: u8 = 82
BACKEND_KEY_DATA
Constant · Source
pub const BACKEND_KEY_DATA: u8 = 75
BIND_COMPLETE
Constant · Source
pub const BIND_COMPLETE: u8 = 50
CLOSE_COMPLETE
Constant · Source
pub const CLOSE_COMPLETE: u8 = 51
COMMAND_COMPLETE
Constant · Source
pub const COMMAND_COMPLETE: u8 = 67
COPY_IN_RESPONSE
Constant · Source
pub const COPY_IN_RESPONSE: u8 = 71
COPY_OUT_RESPONSE
Constant · Source
pub const COPY_OUT_RESPONSE: u8 = 72
COPY_BOTH_RESPONSE
Constant · Source
pub const COPY_BOTH_RESPONSE: u8 = 87
COPY_DATA
Constant · Source
pub const COPY_DATA: u8 = 100
COPY_DONE
Constant · Source
pub const COPY_DONE: u8 = 99
DATA_ROW
Constant · Source
pub const DATA_ROW: u8 = 68
EMPTY_QUERY_RESPONSE
Constant · Source
pub const EMPTY_QUERY_RESPONSE: u8 = 73
ERROR_RESPONSE
Constant · Source
pub const ERROR_RESPONSE: u8 = 69
NEGOTIATE_PROTOCOL_VERSION
Constant · Source
pub const NEGOTIATE_PROTOCOL_VERSION: u8 = 118
NO_DATA
Constant · Source
pub const NO_DATA: u8 = 110
NOTICE_RESPONSE
Constant · Source
pub const NOTICE_RESPONSE: u8 = 78
NOTIFICATION_RESPONSE
Constant · Source
pub const NOTIFICATION_RESPONSE: u8 = 65
PARAMETER_DESCRIPTION
Constant · Source
pub const PARAMETER_DESCRIPTION: u8 = 116
PARAMETER_STATUS
Constant · Source
pub const PARAMETER_STATUS: u8 = 83
PARSE_COMPLETE
Constant · Source
pub const PARSE_COMPLETE: u8 = 49
PORTAL_SUSPENDED
Constant · Source
pub const PORTAL_SUSPENDED: u8 = 115
READY_FOR_QUERY
Constant · Source
pub const READY_FOR_QUERY: u8 = 90
ROW_DESCRIPTION
Constant · Source
pub const ROW_DESCRIPTION: u8 = 84
AUTH_OK
Constant · Source
Authentication request codes (the first field of an ‘R’ message).
pub const AUTH_OK: i32 = 0
AUTH_CLEARTEXT_PASSWORD
Constant · Source
pub const AUTH_CLEARTEXT_PASSWORD: i32 = 3
AUTH_MD5_PASSWORD
Constant · Source
pub const AUTH_MD5_PASSWORD: i32 = 5
AUTH_SASL
Constant · Source
pub const AUTH_SASL: i32 = 10
AUTH_SASL_CONTINUE
Constant · Source
pub const AUTH_SASL_CONTINUE: i32 = 11
AUTH_SASL_FINAL
Constant · Source
pub const AUTH_SASL_FINAL: i32 = 12
STATUS_IDLE
Constant · Source
Transaction status reported by ReadyForQuery.
pub const STATUS_IDLE: u8 = 73
STATUS_TRANSACTION
Constant · Source
pub const STATUS_TRANSACTION: u8 = 84
STATUS_FAILED
Constant · Source
pub const STATUS_FAILED: u8 = 69
capacity
Function · Source
pub fn capacity() -> db.Error
violation
Function · Source
pub fn violation() -> db.Error
misuse
Function · Source
pub fn misuse() -> db.Error
Buffer
Struct · Source
A sink over a caller-owned byte slice. A message that does not fit fails with ErrorKind.Capacity and leaves the bytes written so far.
pub struct Buffer {
// Private implementation fields omitted.
}
Buffer.new
Function · Source
pub fn new(data: &mut[u8]) -> Buffer from(data)
Buffer.put
Function · Source
pub fn put(&mut self, bytes: &[u8]) -> void!db.Error
Buffer.bytes
Function · Source
pub fn bytes(&self) -> &[u8]
Buffer.used
Function · Source
pub fn used(&self) -> usize
Buffer.clear
Function · Source
pub fn clear(&mut self)
put_u8
Function · Source
pub fn put_u8<W>(w: &mut W, value: u8) -> void!db.Error
put_u16
Function · Source
pub fn put_u16<W>(w: &mut W, value: u16) -> void!db.Error
put_u32
Function · Source
pub fn put_u32<W>(w: &mut W, value: u32) -> void!db.Error
put_i32
Function · Source
pub fn put_i32<W>(w: &mut W, value: i32) -> void!db.Error
signed_bits
Function · Source
pub fn signed_bits(value: i32) -> u32
put_cstr
Function · Source
Writes a NUL-terminated string. Text containing NUL cannot be represented and fails with ErrorKind.Misuse.
pub fn put_cstr<W>(w: &mut W, text: &[u8]) -> void!db.Error
check_cstr
Function · Source
pub fn check_cstr(text: &[u8]) -> void!db.Error
put_header
Function · Source
Tag and length of a message whose body (everything after the length) is
bodybytes long.
pub fn put_header<W>(w: &mut W, tag: u8, body: usize) -> void!db.Error
startup
Function · Source
StartupMessage. Empty
databaseandapplication_nameare left out (the server then uses the user name as the database name). The client encoding is always UTF8, which every text value instd/dbassumes.
pub fn startup<W>(w: &mut W, user: &[u8], database: &[u8], application_name: &[u8]) -> void!db.Error
ssl_request
Function · Source
SSLRequest: the server answers with one byte, ‘S’ (start TLS) or ‘N’.
pub fn ssl_request<W>(w: &mut W) -> void!db.Error
cancel_request
Function · Source
CancelRequest, sent on a new connection with the target’s key data.
pub fn cancel_request<W>(w: &mut W, process_id: i32, secret_key: i32) -> void!db.Error
password
Function · Source
PasswordMessage carrying a cleartext or md5 password.
pub fn password<W>(w: &mut W, secret: &[u8]) -> void!db.Error
sasl_initial
Function · Source
SASLInitialResponse.
pub fn sasl_initial<W>(w: &mut W, mechanism: &[u8], data: &[u8]) -> void!db.Error
sasl_response
Function · Source
SASLResponse.
pub fn sasl_response<W>(w: &mut W, data: &[u8]) -> void!db.Error
query
Function · Source
Query: one or more statements in the simple query protocol.
pub fn query<W>(w: &mut W, sql: &[u8]) -> void!db.Error
parse
Function · Source
Parse with every parameter type left for the server to infer.
pub fn parse<W>(w: &mut W, name: &[u8], sql: &[u8]) -> void!db.Error
describe_statement
Function · Source
pub fn describe_statement<W>(w: &mut W, name: &[u8]) -> void!db.Error
describe_portal
Function · Source
pub fn describe_portal<W>(w: &mut W, name: &[u8]) -> void!db.Error
execute
Function · Source
Execute; max_rows 0 returns every row.
pub fn execute<W>(w: &mut W, portal: &[u8], max_rows: u32) -> void!db.Error
close_statement
Function · Source
pub fn close_statement<W>(w: &mut W, name: &[u8]) -> void!db.Error
sync
Function · Source
pub fn sync<W>(w: &mut W) -> void!db.Error
flush
Function · Source
pub fn flush<W>(w: &mut W) -> void!db.Error
terminate
Function · Source
pub fn terminate<W>(w: &mut W) -> void!db.Error
Frame
Struct · Source
A complete backend message at the start of some received bytes:
tag, and the body length (the message occupies 5 + body bytes).
pub struct Frame {
pub tag: u8
pub body: usize
}
frame
Function · Source
The next message in
input, or none when fewer than five bytes (tag and length) have arrived. The body itself may still be incomplete: compare 5 + body with the bytes available.
pub fn frame(input: &[u8]) -> Option<Frame>!db.Error
Span
Struct · Source
A byte range inside a message body.
pub struct Span {
pub start: usize
pub end: usize
}
Span.empty
Function · Source
pub fn empty() -> Span
Span.len
Function · Source
pub fn len(&self) -> usize
Reader
Struct · Source
Sequential reader over a message body. Every read past the end is a Protocol error.
pub struct Reader {
// Private implementation fields omitted.
}
Reader.new
Function · Source
pub fn new(data: &[u8]) -> Reader from(data)
Reader.position
Function · Source
pub fn position(&self) -> usize
Reader.remaining
Function · Source
pub fn remaining(&self) -> usize
Reader.u8
Function · Source
pub fn u8(&mut self) -> u8!db.Error
Reader.u16
Function · Source
pub fn u16(&mut self) -> u16!db.Error
Reader.u32
Function · Source
pub fn u32(&mut self) -> u32!db.Error
Reader.i32
Function · Source
pub fn i32(&mut self) -> i32!db.Error
Reader.cstr
Function · Source
A NUL-terminated string; the span excludes the terminator.
pub fn cstr(&mut self) -> Span!db.Error
Reader.take
Function · Source
pub fn take(&mut self, count: usize) -> Span!db.Error
unsigned_bits
Function · Source
pub fn unsigned_bits(value: u32) -> i32
span_bytes
Function · Source
pub fn span_bytes(body: &[u8], span: &Span) -> &[u8] from(body)
auth_code
Function · Source
The request code of an Authentication message.
pub fn auth_code(body: &[u8]) -> i32!db.Error
offers_mechanism
Function · Source
The SASL mechanisms an AuthenticationSASL message offers include
name.
pub fn offers_mechanism(body: &[u8], name: &[u8]) -> bool!db.Error
same
Function · Source
pub fn same(a: &[u8], b: &[u8]) -> bool
starts_with
Function · Source
pub fn starts_with(data: &[u8], prefix: &[u8]) -> bool
KeyData
Struct · Source
BackendKeyData (protocol 3.0: a 4-byte secret key).
pub struct KeyData {
pub process_id: i32
pub secret_key: i32
}
key_data
Function · Source
pub fn key_data(body: &[u8]) -> KeyData!db.Error
Setting
Struct · Source
ParameterStatus: name and value spans.
pub struct Setting {
pub name: Span
pub value: Span
}
setting
Function · Source
pub fn setting(body: &[u8]) -> Setting!db.Error
Notification
Struct · Source
NotificationResponse (LISTEN/NOTIFY).
pub struct Notification {
pub process_id: i32
pub channel: Span
pub payload: Span
}
notification
Function · Source
pub fn notification(body: &[u8]) -> Notification!db.Error
ready_status
Function · Source
ReadyForQuery: the transaction status byte.
pub fn ready_status(body: &[u8]) -> u8!db.Error
command_tag
Function · Source
The command tag of a CommandComplete message.
pub fn command_tag(body: &[u8]) -> Span!db.Error
affected_rows
Function · Source
Rows affected by a command, from its tag: the last number of “INSERT 0 5”, “UPDATE 3”, “DELETE 1”, “SELECT 7”, “MERGE 2”, “COPY 9”, “FETCH 4” or “MOVE 4”; 0 for other commands.
pub fn affected_rows(tag: &[u8]) -> u64
byte_position
Function · Source
Converts PostgreSQL’s 1-based character position in
sqlinto a 0-based byte offset, or -1 when it lies outside the text.
pub fn byte_position(sql: &[u8], position: i32) -> i32
Notice
Struct · Source
ErrorResponse and NoticeResponse fields. Absent fields are empty spans;
positionis the 1-based character position in the statement, or 0.
pub struct Notice {
pub severity: Span
pub code: Span
pub message: Span
pub detail: Span
pub hint: Span
pub constraint: Span
pub position: i32
}
notice
Function · Source
pub fn notice(body: &[u8]) -> Notice!db.Error
sqlstate_number
Function · Source
Packs a five-character SQLSTATE into the number stored in db.Error.code: each character is a base-36 digit (0-9, then A-Z), most significant first, so “23505” and “42P01” map to distinct positive numbers. Malformed codes give 0.
pub fn sqlstate_number(code: &[u8]) -> i32
sqlstate_text
Function · Source
The SQLSTATE text of a number made by
sqlstate_number.
pub fn sqlstate_text(number: i32, out: &mut[u8]) -> usize
error_for
Function · Source
The portable error for a server SQLSTATE.
codeon the result issqlstate_number(code).
pub fn error_for(code: &[u8]) -> db.Error
Hashes
Interface · Source
Password authentication without a fixed cryptography backend: the caller supplies the hash functions (the hosted client uses OpenSSL’s libcrypto), so this package stays portable.
pub interface Hashes {
fn sha256(&mut self, data: &[u8]) -> [32]u8!db.Error
fn hmac_sha256(&mut self, key: &[u8], data: &[u8]) -> [32]u8!db.Error
fn pbkdf2_sha256(&mut self, password: &[u8], salt: &[u8], iterations: u32) -> [32]u8!db.Error
// MD5 of first followed by second.
fn md5(&mut self, first: &[u8], second: &[u8]) -> [16]u8!db.Error
}
SCRAM_SHA_256
Constant · Source
pub const SCRAM_SHA_256: &str = "SCRAM-SHA-256"
Scram
Struct · Source
SCRAM-SHA-256 client (RFC 5802, RFC 7677) as PostgreSQL uses it: no channel binding (“n,,”), and the user name is left empty because the server takes it from the startup message.
scram := protocol.Scram.new(nonce)? n := scram.client_first(&mut out)? // SASLInitialResponse data n = scram.client_final(&mut hashes, password, server_first, &mut out)? scram.verify(server_final)? // AuthenticationSASLFinal
pub struct Scram {
// Private implementation fields omitted.
}
Scram.new
Function · Source
nonceis the client nonce: 18 to 32 printable ASCII characters other than ‘,’. Use fresh random bytes from a CSPRNG for every attempt, for example base64 of 18 random bytes.
pub fn new(nonce: &[u8]) -> Scram!db.Error
Scram.client_first
Function · Source
client-first-message: “n,,n=,r=<nonce>”.
pub fn client_first(&mut self, out: &mut[u8]) -> usize!db.Error
Scram.client_final
Function · Source
Reads the server-first-message and writes the client-final-message, whose proof shows knowledge of
password. The password is used as given (SASLprep leaves printable ASCII unchanged).
pub fn client_final<K: Hashes>(&mut self, hashes: &mut K, password: &[u8], server_first: &[u8], out: &mut[u8]) -> usize!db.Error
Scram.verify
Function · Source
Checks the server-final-message (“v=<signature>”), which proves the server knew the password too. “e=<error>” is an Auth error.
pub fn verify(&mut self, server_final: &[u8]) -> void!db.Error
md5_password
Function · Source
The md5 password response: “md5” followed by the hex MD5 of (hex MD5 of password + user) + salt, as AuthenticationMD5Password requests.
outmust hold 35 bytes.
pub fn md5_password<K: Hashes>(hashes: &mut K, user: &[u8], password: &[u8], salt: &[u8], out: &mut[u8]) -> usize!db.Error
base64_encode
Function · Source
Standard base64 with padding.
outmust hold 4 * ceil(data.len / 3) bytes.
pub fn base64_encode(data: &[u8], out: &mut[u8]) -> usize
base64_decode
Function · Source
Decodes standard padded base64 into
out; malformed input is a Protocol error and output that does not fit is a Capacity error.
pub fn base64_decode(text: &[u8], out: &mut[u8]) -> usize!db.Error
OID_BOOL
Constant · Source
Type OIDs of the built-in types this codec knows (pg_type.oid).
pub const OID_BOOL: u32 = 16
OID_BYTEA
Constant · Source
pub const OID_BYTEA: u32 = 17
OID_INT8
Constant · Source
pub const OID_INT8: u32 = 20
OID_INT2
Constant · Source
pub const OID_INT2: u32 = 21
OID_INT4
Constant · Source
pub const OID_INT4: u32 = 23
OID_TEXT
Constant · Source
pub const OID_TEXT: u32 = 25
OID_OID
Constant · Source
pub const OID_OID: u32 = 26
OID_FLOAT4
Constant · Source
pub const OID_FLOAT4: u32 = 700
OID_FLOAT8
Constant · Source
pub const OID_FLOAT8: u32 = 701
OID_VARCHAR
Constant · Source
pub const OID_VARCHAR: u32 = 1043
KIND_TEXT
Constant · Source
How a column or parameter is transferred. Every kind except KIND_TEXT uses PostgreSQL’s binary format; KIND_TEXT uses the text format, which the server produces and parses for every type (numeric, timestamps, uuid, json, arrays, …).
pub const KIND_TEXT: u8 = 0
KIND_BOOL
Constant · Source
pub const KIND_BOOL: u8 = 1
KIND_INT2
Constant · Source
pub const KIND_INT2: u8 = 2
KIND_INT4
Constant · Source
pub const KIND_INT4: u8 = 3
KIND_INT8
Constant · Source
pub const KIND_INT8: u8 = 4
KIND_OID
Constant · Source
pub const KIND_OID: u8 = 5
KIND_FLOAT4
Constant · Source
pub const KIND_FLOAT4: u8 = 6
KIND_FLOAT8
Constant · Source
pub const KIND_FLOAT8: u8 = 7
KIND_BYTEA
Constant · Source
pub const KIND_BYTEA: u8 = 8
kind_of
Function · Source
pub fn kind_of(oid: u32) -> u8
format_of
Function · Source
Format code (0 text, 1 binary) for a kind.
pub fn format_of(kind: u8) -> u16
parameter_kinds
Function · Source
ParameterDescription: the number of parameters, and each one’s kind written to
kinds(parameters beyond kinds.len are sent as text).
pub fn parameter_kinds(body: &[u8], kinds: &mut[u8]) -> usize!db.Error
Field
Struct · Source
One field of a RowDescription.
pub struct Field {
pub name: Span
pub type_oid: u32
pub format: u16
}
Fields
Struct · Source
Walks the fields of a RowDescription.
pub struct Fields {
// Private implementation fields omitted.
}
Fields.new
Function · Source
pub fn new(body: &[u8]) -> Fields!db.Error from(body)
Fields.count
Function · Source
pub fn count(&self) -> usize
Fields.next
Function · Source
pub fn next(&mut self) -> Option<Field>!db.Error
Columns
Struct · Source
Walks the column values of a DataRow. Each value is a span into the body, or none for NULL.
pub struct Columns {
// Private implementation fields omitted.
}
Columns.new
Function · Source
pub fn new(body: &[u8]) -> Columns!db.Error from(body)
Columns.count
Function · Source
pub fn count(&self) -> usize
Columns.next
Function · Source
The next value: ok(some(true)) with
spanset, ok(some(false)) for NULL, ok(none) after the last column.
pub fn next(&mut self, span: &mut Span) -> Option<bool>!db.Error
decode
Function · Source
Decodes one non-NULL value of the given kind and format (0 text, 1 binary). Text and Bytes borrow
data. Text-format values of known numeric kinds are converted, so a text result still reads as Int or Real.
pub fn decode(kind: u8, format: u16, data: &[u8]) -> db.Value!db.Error from(data)
format_int
Function · Source
Decimal text of an integer.
pub fn format_int(v: i64, out: &mut[u8]) -> usize
format_real
Function · Source
Text that PostgreSQL’s float and numeric input functions read back as exactly
v: the fewest significant digits (at most 17) that round-trip, in scientific notation, or NaN / Infinity / -Infinity.outmust hold 32 bytes.
pub fn format_real(v: f64, out: &mut[u8]) -> usize
bind
Function · Source
Bind: binds
paramsto the prepared statementstatementas portalportal.kindsholds each parameter’s kind from its ParameterDescription (missing entries are sent as text), and result column i is requested in binary when bit i ofbinary_columnsis set, in text otherwise. Parameters are converted for their target type: an Int for an int2 parameter must fit, a Real for an integer parameter must be integral, and values that do not fit are Type errors before anything is written.
pub fn bind<W>(w: &mut W, portal: &[u8], statement: &[u8], params: &[db.Value], kinds: &[u8], binary_columns: &[u8], columns: usize) -> void!db.Error