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"
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 |
|---|---|---|
crypto |
std/crypto |
connection.dodo |
db |
std/db |
config.dodo, connection.dodo, rows.dodo |
digest |
std/crypto/openssl |
connection.dodo |
hash |
std/hash |
connection.dodo |
io |
std/io |
connection.dodo |
math |
std/math |
rows.dodo |
mem |
core/mem |
connection.dodo, rows.dodo |
native |
std/net/native |
connection.dodo |
net |
std/net |
connection.dodo |
openssl |
std/tls/openssl |
connection.dodo |
operations |
std/net/operations |
connection.dodo |
option |
core/option |
connection.dodo |
protocol |
std/db/postgres/protocol |
config.dodo, connection.dodo, rows.dodo |
random |
std/crypto/random |
connection.dodo |
slice |
core/slice |
connection.dodo |
sql |
std/db/sql |
connection.dodo |
stream |
std/tls/stream |
connection.dodo |
text |
std/text |
connection.dodo |
tls |
std/tls |
connection.dodo |
SslMode
Enum · Source
When to use TLS, with libpq’s meaning for each
sslmode.
pub enum SslMode {
// Never use TLS.
Disable,
// Use TLS when the server supports it, without checking its certificate;
// fall back to an unencrypted connection otherwise (libpq's default).
Prefer,
// Require TLS, without checking the certificate: protects against
// eavesdropping, not against an active attacker.
Require,
// Require TLS and a certificate that chains to a trusted root.
VerifyCa,
// Require TLS, a trusted certificate, and a certificate name that matches
// the host. Use this whenever the network is not trusted.
VerifyFull,
}
Config
Struct · Source
Connection settings. Byte fields borrow the URL or the caller’s storage.
pub struct Config {
// Host name or IP address (IPv6 without brackets). Unix-domain sockets
// are not supported.
pub host: &[u8]
pub port: u16
pub user: &[u8]
// Empty when the server does not ask for a password.
pub password: &[u8]
// Empty selects the database named like the user.
pub database: &[u8]
// Shown in pg_stat_activity. Empty leaves it unset.
pub application_name: &[u8]
pub ssl_mode: SslMode
// PEM roots for VerifyCa and VerifyFull; empty uses the system roots.
// With Require, roots make the client check the chain (as libpq does
// when a root certificate is configured).
pub trust_pem: &[u8]
// Resolution, connection, TLS handshake and authentication together;
// 0 waits forever.
pub connect_timeout_ms: u64
// Each later wait for the server; 0 waits as long as a query takes.
// A statement whose response times out keeps running on the server and
// the next request first skips its response; `cancel` stops it.
pub timeout_ms: u64
// Keep prepared statements on the server, keyed by SQL text, so
// repeated statements cost one round trip and use the binary format.
// Disable for poolers that do not support named prepared statements
// (PgBouncer before 1.21 in transaction mode); every statement then
// costs two round trips.
pub statement_cache: bool
}
Config.new
Function · Source
pub fn new(host: &[u8], user: &[u8]) -> Config from(host, user)
Config.parse
Function · Source
Parses a libpq connection URL:
postgres://user:password@host:port/database?sslmode=require
postgresql://works too. Percent-escapes in the user, password, host, database and parameter values are decoded intostorage, which needs at most url.len bytes (none when the URL has no escapes). The host defaults to “localhost” and the port to 5432. Recognized parameters: sslmode (disable, allow, prefer, require, verify-ca, verify-full), application_name, connect_timeout (seconds), host, port, user, password and dbname. Other parameters are ignored, so URLs written for other tools still work.
pub fn parse(url: &[u8], storage: &mut[u8]) -> Config!db.Error from(url, storage)
Config.clone
Function · Source
A copy borrowing the same bytes, for example one per pool slot.
pub fn clone(&self) -> Config from(self)
WORKSPACE_BYTES
Constant · Source
Suggested workspace: rows (DataRow messages) up to about 200 KiB.
pub const WORKSPACE_BYTES: usize = 262144
MIN_WORKSPACE_BYTES
Constant · Source
pub const MIN_WORKSPACE_BYTES: usize = 65536
STATEMENT_SLOTS
Constant · Source
Server-side prepared statements kept per connection.
pub const STATEMENT_SLOTS: usize = 32
MAX_COLUMNS
Constant · Source
Columns per result.
pub const MAX_COLUMNS: usize = 256
CancelKey
Struct · Source
The key that lets another connection cancel this one’s running statement.
pub struct CancelKey {
pub process_id: i32
pub secret_key: i32
}
cancel
Function · Source
Asks the server to cancel the statement that the connection identified by
keyis running (if any), over a new connection made withconfig. The cancelled statement fails with ErrorKind.Interrupted (SQLSTATE 57014). Like libpq, this does not wait for the cancellation to take effect.
pub fn cancel(config: &Config, key: &CancelKey) -> void!db.Error
Connection
Struct · Source
pub struct Connection {
// Private implementation fields omitted.
}
Connection.new
Function · Source
A disconnected connection over
workspace(at least MIN_WORKSPACE_BYTES);openconnects it. Pools hold connections in this state until they are first needed.
pub fn new(config: Config, workspace: &mut[u8]) -> Connection!db.Error from(config, workspace)
Connection.connect
Function · Source
Connects to the server described by
config.
pub fn connect(config: Config, workspace: &mut[u8]) -> Connection!db.Error from(config, workspace)
Connection.open
Function · Source
(Re)connects: closes any current session, then resolves, connects, negotiates TLS as Config.ssl_mode asks, and authenticates with SCRAM-SHA-256, md5 or a cleartext password as the server requests.
pub fn open(&mut self) -> void!db.Error
Connection.close
Function · Source
Closes the session, telling the server first. The connection can be reopened with
open.
pub fn close(&mut self) -> void!db.Error
Connection.is_open
Function · Source
Connected, and not broken by a network failure or protocol error.
pub fn is_open(&self) -> bool
Connection.in_transaction
Function · Source
Inside a transaction block (BEGIN … COMMIT/ROLLBACK), including one that failed and now only accepts ROLLBACK.
pub fn in_transaction(&self) -> bool
Connection.server_version
Function · Source
Server version as major * 10000 + minor (170002 for 17.2), 0 if unknown.
pub fn server_version(&self) -> u32
Connection.cancel_key
Function · Source
pub fn cancel_key(&self) -> CancelKey
Connection.message
Function · Source
The server’s (or client’s) message for the last failure.
pub fn message(&self) -> &str
Connection.detail
Function · Source
pub fn detail(&self) -> &str
Connection.hint
Function · Source
pub fn hint(&self) -> &str
Connection.sqlstate
Function · Source
The SQLSTATE of the last server error (“23505”), empty for client-side failures. db.Error.code holds the same code packed by
protocol.sqlstate_number.
pub fn sqlstate(&self) -> &str
Connection.changes
Function · Source
Rows affected by the last completed statement.
pub fn changes(&self) -> u64
Connection.execute
Function · Source
Runs a single statement with parameters ($1, $2, …) and returns the number of rows it inserted, updated, deleted or returned.
pub fn execute(&mut self, sql: &str, params: &[db.Value]) -> u64!db.Error
Connection.query
Function · Source
Runs a single statement and passes every result row to
sink. A sink error stops delivery and is returned after the response is read.
pub fn query(&mut self, sql: &str, params: &[db.Value], sink: &mut dyn sql.RowSink) -> void!db.Error
Connection.select
Function · Source
Runs a single statement and returns a cursor over its rows.
pub fn select(&mut self, sql: &str, params: &[db.Value]) -> Rows!db.Error from(self, sql)
Connection.prepare
Function · Source
Prepares
sqlon the server now (so syntax errors surface here) and returns a handle forrunandrows. Statements stay cached by text; one evicted from the cache is prepared again transparently.
pub fn prepare(&mut self, sql: &str) -> Statement!db.Error from(sql)
Connection.run
Function · Source
pub fn run(&mut self, stmt: &Statement, params: &[db.Value]) -> u64!db.Error
Connection.rows
Function · Source
pub fn rows(&mut self, stmt: &Statement, params: &[db.Value]) -> Rows!db.Error from(self, stmt)
Connection.exec
Function · Source
Runs one or more statements separated by semicolons with the simple query protocol (no parameters), discarding any rows. With several statements outside a transaction block, the server runs them as one transaction.
pub fn exec(&mut self, sql: &str) -> void!db.Error
Connection.begin
Function · Source
pub fn begin(&mut self, level: db.IsolationLevel) -> void!db.Error
Connection.commit
Function · Source
Commits the transaction. A transaction that already failed is rolled back by the server instead; that is reported as ErrorKind.Misuse.
pub fn commit(&mut self) -> void!db.Error
Connection.rollback
Function · Source
pub fn rollback(&mut self) -> void!db.Error
Connection.ping
Function · Source
Pool support: a cheap round trip that checks the session is alive.
pub fn ping(&mut self) -> void!db.Error
Connection.reset
Function · Source
Pool support: makes the session ready for its next user. An open transaction is rolled back and queued notifications are dropped; a connection still receiving an abandoned statement’s response is closed instead of waiting for it (open reconnects). Other session state (SET, LISTEN, temporary tables) stays.
pub fn reset(&mut self) -> void!db.Error
Connection.notification
Function · Source
The next LISTEN/NOTIFY notification: one that arrived during earlier requests, or else one that arrives within
timeout_ms(0 only checks what has arrived). none when there is none. Notifications that do not fit the queue are counted indropped_notifications.
pub fn notification(&mut self, timeout_ms: u64) -> Option<Notification>!db.Error from(self)
Connection.dropped_notifications
Function · Source
pub fn dropped_notifications(&self) -> u64
connect
Function · Source
Connects using a postgres:// URL (see Config.parse). Escaped URL parts are decoded into the start of the workspace.
pub fn connect(url: &[u8], workspace: &mut[u8]) -> Connection!db.Error from(url, workspace)
Statement
Struct · Source
A statement handle from
Connection.prepare. It holds the SQL text; the server-side statement lives in the connection’s cache.
pub struct Statement {
// Private implementation fields omitted.
}
Statement.sql
Function · Source
pub fn sql(&self) -> &str
Notification
Struct · Source
A LISTEN/NOTIFY notification. Its text borrows the connection until the next call.
pub struct Notification {
pub process_id: i32
pub channel: &str
pub payload: &str
}
Rows
Struct · Source
A cursor over the rows of a running statement. Rows borrow the connection; dropping the cursor early leaves the remaining rows to be skipped by the connection’s next request.
pub struct Rows {
// Private implementation fields omitted.
}
Rows.next
Function · Source
Advances to the next row; none at the end. A statement that fails after some rows reports its error here, after those rows.
pub fn next(&mut self) -> Option<Row>!db.Error
Rows.len
Function · Source
Number of result columns.
pub fn len(&self) -> usize
Row
Struct · Source
One result row. Text and byte values borrow the receive buffer and stay valid until the cursor advances.
Values arrive as follows: bool, int2, int4, int8 and oid as Int (bool is 0 or 1); float4 and float8 as Real; bytea as Bytes; every other type (text, varchar, numeric, date, timestamp, uuid, json, arrays, …) as Text in PostgreSQL’s text format; NULL as Null.
pub struct Row {
// Private implementation fields omitted.
}
Row.len
Function · Source
pub fn len(&self) -> usize
Row.name
Function · Source
pub fn name(&self, index: usize) -> &str
Row.get
Function · Source
pub fn get(&self, index: usize) -> db.Value!db.Error
Row.is_null
Function · Source
pub fn is_null(&self, index: usize) -> bool
Row.value_type
Function · Source
The value’s class; Null for NULL and for columns out of range.
pub fn value_type(&self, index: usize) -> db.ValueType
Row.int
Function · Source
Integers as they are, reals truncated toward zero when in range; 0 for anything else.
pub fn int(&self, index: usize) -> i64
Row.real
Function · Source
Reals as they are, integers converted; 0.0 for anything else.
pub fn real(&self, index: usize) -> f64
Row.text
Function · Source
Text values (every type without a binary decoding); “” otherwise.
pub fn text(&self, index: usize) -> &str
Row.bytes
Function · Source
bytea values, or the UTF-8 bytes of text values; empty otherwise.
pub fn bytes(&self, index: usize) -> &[u8]