API referencestd/db

std/db

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

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"

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
io std/io db.dodo
ptr core/ptr db.dodo

ErrorKind

Enum · Source

Portable error class. code on Error keeps the driver’s native code (an SQLite extended result code, a Postgres SQLSTATE number, …).

pub enum ErrorKind {
    // The store could not be reached or opened.
    Connect,
    // Credentials or permissions were rejected.
    Auth,
    // A constraint rejected the change; see Error.constraint.
    Constraint,
    // The transaction conflicted with another one and may be retried.
    Serialization,
    // Another connection holds a lock; the operation may be retried later.
    Busy,
    // An operation exceeded its time limit.
    Timeout,
    // Malformed SQL or an unknown name in a statement.
    Syntax,
    // The statement is valid but refers to a schema object that is missing.
    Schema,
    // A value had the wrong type or was out of range for the operation.
    Type,
    // A parameter or column index was out of range.
    Range,
    // A wire-protocol violation from the peer.
    Protocol,
    // A fixed-size workspace, buffer, or limit was exhausted.
    Capacity,
    // The underlying file, socket, or device failed.
    Io,
    // Stored data is malformed.
    Corrupt,
    // The store is read-only.
    ReadOnly,
    // The API was used out of order (for example, commit without begin).
    Misuse,
    // The driver does not implement the requested feature.
    Unsupported,
    // An operation was cancelled.
    Interrupted,
    // A driver-internal invariant failed.
    Internal,
}

Constraint

Enum · Source

Which constraint rejected a change, for ErrorKind.Constraint.

pub enum Constraint {
    None,
    Unique,
    PrimaryKey,
    NotNull,
    ForeignKey,
    Check,
    Other,
}

Error

Struct · Source

pub struct Error {
    pub kind: ErrorKind
    pub constraint: Constraint
    // Driver-native code. Zero when the driver has none.
    pub code: i32
    // Byte offset into the statement text the error refers to, or -1.
    pub position: i32
}

Error.new

Function · Source

pub fn new(kind: ErrorKind, code: i32) -> Error

Error.constraint

Function · Source

pub fn constraint(constraint: Constraint, code: i32) -> Error

Error.at

Function · Source

pub fn at(kind: ErrorKind, code: i32, position: i32) -> Error

Error.is_transient

Function · Source

True for failures that may succeed when the operation is retried.

pub fn is_transient(&self) -> bool

Error.format

Function · Source

Only fixed names and numeric metadata; drivers expose their message text separately (for example sqlite.Connection.message).

pub fn format<F>(&self, output: &mut F) -> void!io.Error

kind_name

Function · Source

pub fn kind_name(kind: &ErrorKind) -> &str from(static)

constraint_name

Function · Source

pub fn constraint_name(constraint: &Constraint) -> &str from(static)

Value

Enum · Source

A borrowed database value. Text and Bytes borrow the driver’s workspace or the caller’s data, so producing or binding a value never allocates.

pub enum Value {
    Null,
    Int(i64),
    Real(f64),
    Text(&str),
    Bytes(&[u8]),
}

ValueType

Enum · Source

Value classes, for drivers and generic code that need to branch on a type without borrowing a payload.

pub enum ValueType {
    Null,
    Int,
    Real,
    Text,
    Bytes,
}

value_type

Function · Source

pub fn value_type(value: &Value) -> ValueType

IsolationLevel

Enum · Source

Transaction isolation requested by sql.Conn.begin. Drivers map each level to the closest level they support; a driver never silently weakens the requested guarantee below what it documents.

pub enum IsolationLevel {
    Default,
    ReadUncommitted,
    ReadCommitted,
    RepeatableRead,
    Serializable,
}

Pool

Struct · Source

A fixed set of connections that are opened when first needed, reused, checked, and reset between users. The caller owns the connections (each with its own workspace) and lends them to the pool, so nothing is allocated:

conns := [postgres.Connection.new(config.clone(), first_workspace)?, postgres.Connection.new(config.clone(), second_workspace)?] pool := db.Pool.new(&mut conns)? lease := pool.get()? lease.conn().execute(“update counters set n = n + 1”, &none_)? dropping the lease resets the connection and returns it

A connection type C works with the pool when it has these methods (every network driver in std/db provides them):

fn is_open(&self) -> bool fn open(&mut self) -> void!db.Error // connect or reconnect fn ping(&mut self) -> void!db.Error // one cheap round trip fn reset(&mut self) -> void!db.Error // end leftover transactions fn close(&mut self) -> void!db.Error

The pool serves one execution lane: get hands out one connection at a time through a borrow, and acquire/conn/release let code (such as a reactor that interleaves requests) hold several connections at once. Returning a connection calls reset; a driver may close a connection there rather than wait for it (the next get reopens it).

pub struct Pool<C> {
    // Private implementation fields omitted.
}

Pool.new

Function · Source

Up to 64 connections. They may start closed; each opens on first use.

pub fn new(slots: &mut[C]) -> Pool<C>!Error from(slots)

Pool.check_on_get

Function · Source

When enabled, an open connection is pinged before it is handed out and reopened if the ping fails, so a connection the server dropped while idle is replaced. Costs one round trip per get.

pub fn check_on_get(&mut self, enabled: bool)

Pool.len

Function · Source

pub fn len(&self) -> usize

Pool.idle

Function · Source

Connections not currently lent out.

pub fn idle(&self) -> usize

Pool.get

Function · Source

Lends one connection until the lease is dropped. Fails with ErrorKind.Capacity when every connection is lent out, or with the driver’s error when a connection cannot be opened.

pub fn get(&mut self) -> Lease<C>!Error from(self)

Pool.acquire

Function · Source

Like get, but returns a handle that does not borrow the pool; reach the connection with conn and hand it back with release. A ticket that is dropped without release keeps its connection lent out.

pub fn acquire(&mut self) -> Ticket!Error

Pool.conn

Function · Source

The connection of a ticket from this pool. A ticket from another pool is a programming error and traps.

pub fn conn(&mut self, ticket: &Ticket) -> &mut C from(self)

Pool.release

Function · Source

pub fn release(&mut self, ticket: Ticket)

Pool.close_idle

Function · Source

Closes every connection that is not lent out.

pub fn close_idle(&mut self)

Lease

Struct · Source

A connection lent by Pool.get; dropping it returns the connection.

pub struct Lease<C> {
    // Private implementation fields omitted.
}

Lease.conn

Function · Source

pub fn conn(&mut self) -> &mut C from(self)

Ticket

Struct · Source

A connection lent by Pool.acquire, identified by its pool and slot.

pub struct Ticket {
    // Private implementation fields omitted.
}

Ticket.slot

Function · Source

pub fn slot(&self) -> usize

Search every guide, reference page, and API declaration.