API referencestd/db

std/db/postgres/protocol

Public declarations, types, methods, and source contracts for std/db/postgres/protocol.

On this page

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 body bytes long.

pub fn put_header<W>(w: &mut W, tag: u8, body: usize) -> void!db.Error

startup

Function · Source

StartupMessage. Empty database and application_name are left out (the server then uses the user name as the database name). The client encoding is always UTF8, which every text value in std/db assumes.

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 sql into 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; position is 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. code on the result is sqlstate_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

nonce is 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. out must 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. out must 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 span set, 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. out must hold 32 bytes.

pub fn format_real(v: f64, out: &mut[u8]) -> usize

bind

Function · Source

Bind: binds params to the prepared statement statement as portal portal. kinds holds each parameter’s kind from its ParameterDescription (missing entries are sent as text), and result column i is requested in binary when bit i of binary_columns is 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

Search every guide, reference page, and API declaration.