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.
codeon 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:
gethands out one connection at a time through a borrow, andacquire/conn/releaselet code (such as a reactor that interleaves requests) hold several connections at once. Returning a connection callsreset; a driver may close a connection there rather than wait for it (the nextgetreopens 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
connand hand it back withrelease. 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