API referencestd/db

std/db/postgres

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

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"

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 into storage, 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 key is running (if any), over a new connection made with config. 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); open connects 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 sql on the server now (so syntax errors surface here) and returns a handle for run and rows. 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 in dropped_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]

Search every guide, reference page, and API declaration.