magmalake postgres

postgres · API

postgres.params

postgres.params — the Params builder for PQexecParams / PQexecPrepared.

Collects $1-style query parameters, always in text format (this tin never sends binary-format parameters). Params keeps three parallel lists — values, null flags, and OIDs — that the FFI layer reads by index when it builds the char* const*/Oid*/int* arrays libpq wants.

Every typed builder method encodes through postgres.text and is chainable by consuming and returning self, so a call reads like::

var p = Params().text("gold").int64(7).timestamptz_micros(now)

.text() binds OID 0 — the server infers the parameter's type from query context, which is what you want for an untyped literal. Use .typed() as an escape hatch for a value/OID pair this module has no dedicated method for.

Structs

Params

struct Params

A builder for one query's parameter list.

Params() starts empty. Each builder method appends one parameter and returns self so calls chain; __len__, value(i), is_null(i), and oid(i) are the read side the FFI layer uses to fill libpq's parameter arrays.

Implements Copyable, Movable, Sized

__init__

def __init__(out self)

__len__

def __len__(self) -> Int

Number of parameters bound so far.

value

def value(self, i: Int) -> String

The text form of parameter i (0-based). Meaningless — and conventionally the empty string — when is_null(i) is True.

is_null

def is_null(self, i: Int) -> Bool

Whether parameter i is SQL NULL.

oid

def oid(self, i: Int) -> UInt32

The OID parameter i was bound with; 0 lets the server infer the type from query context.

text

def text(var self, v: String) -> Self

Bind v untyped (OID 0) — the server infers the type from context.

int16

def int16(var self, v: Int16) -> Self

int32

def int32(var self, v: Int32) -> Self

int64

def int64(var self, v: Int64) -> Self

float32

def float32(var self, v: Float32) -> Self

float64

def float64(var self, v: Float64) -> Self

bool

def bool(var self, v: Bool) -> Self

numeric

def numeric(var self, v: String) -> Self

Bind an already-formatted numeric literal. Kept a String — see postgres.text's module docstring for why.

bytea

def bytea(var self, v: Span[UInt8]) -> Self

date_days

def date_days(var self, v: Int32) -> Self

v is days since 1970-01-01, as returned by text.decode_date.

time_micros

def time_micros(var self, v: Int64) -> Self

v is microseconds since midnight, as returned by text.decode_time.

timestamp_micros

def timestamp_micros(var self, v: Int64) -> Self

v is microseconds since 1970-01-01 00:00:00 (naive, no zone), as returned by text.decode_timestamp.

timestamptz_micros

def timestamptz_micros(var self, v: Int64) -> Self

v is UTC microseconds since 1970-01-01 00:00:00, as returned by text.decode_timestamptz.

uuid

def uuid(var self, v: String) -> Self

json

def json(var self, v: String) -> Self

jsonb

def jsonb(var self, v: String) -> Self

null

def null(var self, oid: UInt32 = UInt32(0)) -> Self

Bind SQL NULL, optionally typed with oid (default 0, server infers).

typed

def typed(var self, value: String, oid: UInt32) -> Self

Escape hatch: bind an already-formatted text value with an explicit OID this module has no dedicated method for.