std.postgres

A PostgreSQL client:

import std.postgres

let db = postgres.connect("postgres://app:secret@127.0.0.1:5432/notes")?
db.execute("insert into notes (text) values ($1)", [postgres.text("milk")])?
for row in db.query("select id, text from notes", [])?.rows {
    print(row.int("id")? + ": " + row.text("text")?)
}
// Or straight into a struct whose fields are the columns:
let notes: List[Note] = db.query_as("select id, text from notes", [])?

Parameters are $1, $2, ... in the SQL and Values in the list, so values never become part of the SQL text. Logins use SCRAM-SHA-256, MD5 or a plain password, whatever the server asks for. Connections are not encrypted: use it on the same machine, a private network or a tunnel.

Types

struct Client

pub struct Client {
    // and private fields
}

A connection to a database.

Methods

pub fn query(self, sql: string, params: List[Value]) -> Result[Rows, string]

Runs a query and returns its rows.

pub fn execute(self, sql: string, params: List[Value]) -> Result[i64, string]

Runs a statement and returns how many rows it changed.

pub fn query_as[T: Data](self, sql: string, params: List[Value]) -> Result[List[T], string]

Runs a query and reads each row into a T whose fields are the columns, as json.from_json reads an object.

pub fn transaction[T](self, work: fn(Client) -> Result[T, string]) -> Result[T, string]

Runs work in a transaction: committed if it returns Ok, rolled back if it returns Err.

pub fn close(self)

Ends the connection.

struct Rows

pub struct Rows {
    pub columns: List[string],
    pub rows: List[Row],
    pub affected: i64,
}

The result of a query.

columns: The names of the columns.
affected: How many rows the statement inserted, changed, deleted or returned.

struct Row

pub struct Row {
    pub columns: List[string],
    pub values: List[Option[string]],
    // and private fields
}

One row of a result. Values arrive as text; the methods read them as other types.

values: None for SQL NULL.

Methods

pub fn get(self, column: string) -> Option[string]

A column's value as text; None for NULL or an unknown column.

pub fn is_null(self, column: string) -> bool

Whether a column is NULL.

pub fn text(self, column: string) -> Result[string, string]

pub fn int(self, column: string) -> Result[i64, string]

pub fn float(self, column: string) -> Result[f64, string]

pub fn bool(self, column: string) -> Result[bool, string]

pub fn to_json(self) -> json.Json

The row as a JSON object: numbers, bools, json columns and NULL as themselves, everything else as strings.

enum Value

pub enum Value {
    Null,
    Int(i64),
    Float(f64),
    Text(string),
    Bool(bool),
    Json(json.Json),
}

A parameter of a query.

Json: For json and jsonb columns.

Functions

fn null

pub fn null() -> Value

fn int

pub fn int(n: i64) -> Value

fn float

pub fn float(x: f64) -> Value

fn text

pub fn text(s: string) -> Value

fn bool

pub fn bool(b: bool) -> Value

fn json_value

pub fn json_value[T: Data](value: T) -> Value

A value as JSON text, for json and jsonb columns.

fn connect

pub fn connect(url: string) -> Result[Client, string]

Connects with a URL: postgres://user:password@host:port/database. The port is 5432 unless given, and the database the user's name.

fn connect_to

pub fn connect_to(host: string, port: i64, user: string, password: string, database: string) -> Result[Client, string]

Connects to host and port as user, to database.