gdDocumentation0.8.0

API reference

GDPostgresClient

Client for one PostgreSQL connection. Regular methods suspend only their caller; *_async returns Signals for concurrent composition.

The pool creates no connection until the first query and grows with demand up to the maximum; later queries wait in arrival order. Each query holds one connection while it runs. Transactions and query_rows() hold theirs until they finish or close.

Cancellation and deadline expiry close the borrowed connection. They do not guarantee that the SQL stopped on the server.

The SQLSTATE stays in e.info.code. A unique violation is Err.ALREADY_EXISTS; other server errors are Err.ERROR.

Authentication follows the server's request with SCRAM-SHA-256 or MD5. A cleartext password needs allow_cleartext_password.

  • JSON and JSONB columns follow the GD.data.json_decode rules and keep 64-bit integers. An ambiguous value, such as one with duplicate names, returns the original JSON text.
  • numeric returns decimal text. real and double precision return floats.
  • bool[], smallint[], int[], bigint[], real[], double precision[], numeric[], and text[] keep element types, nulls, and nesting. numeric[] elements are decimal text. An array with explicit lower bounds returns the original text.

Connections request UTF8. If the server reports a change to another client encoding, the connection closes with an error; the SQL that made the change may already have run.

One statement takes up to 65535 bound values. One send is limited to about 1 GiB of SQL and parameter text, counted as UTF-8 bytes. query_many has no fixed item count.

Methods

open

open(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = {  }) -> Variant, Err

Return a signal whose completion carries a value and an Err.

Parameters

NameTypeDefaultDescription
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
portint5432Network port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query

query(sql: String, args: Array = []) -> Dictionary, Err

Send $1 and $2 values separately without interpolating them into SQL.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_row

query_row(sql: String, args: Array = [], max_bytes: int = 0) -> Dictionary, Err

Return only the first row and drain the rest to the protocol boundary.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.
max_bytesint0Maximum result size in bytes where a per-query bound is requested.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_rows

query_rows(sql: String, args: Array = []) -> GDDatabaseRows, Err

Retain the connection's result and return one row per Next call.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

GDDatabaseRows, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_values

query_values(sql: String, args: Array = []) -> Dictionary, Err

Return column-ordered row arrays for bulk retrieval.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_flat

query_flat(sql: String, args: Array = []) -> Dictionary, Err

Return all values in one row-major array.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_many

query_many(sql: String, rows: Array) -> Array, Err

Batch one statement with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_many

fetch_many(sql: String, rows: Array) -> Array, Err

Batch one statement and flatten all returned rows.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_values_many

fetch_values_many(sql: String, rows: Array) -> Array, Err

Flatten rows from repeated statements as column-ordered arrays.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_flat_many

fetch_flat_many(sql: String, rows: Array) -> Array, Err

Return all row values in one array.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

exec_many

exec_many(sql: String, rows: Array) -> int, Err

Batch updates and return only the completion count without individual results.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

int, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

open_async

open_async(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = {  }) -> await Variant, Err

Return a signal whose completion carries a value and an Err.

Parameters

NameTypeDefaultDescription
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
portint5432Network port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_async

query_async(sql: String, args: Array = []) -> await Dictionary, Err

Send $1 and $2 values separately without interpolating them into SQL.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_row_async

query_row_async(sql: String, args: Array = [], max_bytes: int = 0) -> await Dictionary, Err

Return only the first row and drain the rest to the protocol boundary.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.
max_bytesint0Maximum result size in bytes where a per-query bound is requested.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_rows_async

query_rows_async(sql: String, args: Array = []) -> await GDDatabaseRows, Err

Retain the connection's result and return one row per Next call.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

await GDDatabaseRows, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_values_async

query_values_async(sql: String, args: Array = []) -> await Dictionary, Err

Return column-ordered row arrays for bulk retrieval.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_flat_async

query_flat_async(sql: String, args: Array = []) -> await Dictionary, Err

Return all values in one row-major array.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
argsArray[]Arguments in call or parameter-binding order.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

query_many_async

query_many_async(sql: String, rows: Array) -> await Array, Err

Batch one statement with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_many_async

fetch_many_async(sql: String, rows: Array) -> await Array, Err

Batch one statement and flatten all returned rows.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_values_many_async

fetch_values_many_async(sql: String, rows: Array) -> await Array, Err

Flatten rows from repeated statements as column-ordered arrays.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

fetch_flat_many_async

fetch_flat_many_async(sql: String, rows: Array) -> await Array, Err

Return all row values in one array.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

exec_many_async

exec_many_async(sql: String, rows: Array) -> await int, Err

Batch updates and return only the completion count without individual results.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.
rowsArrayRequiredRows in input order. Batch database calls use one parameter set per row.

Return value

await int, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

is_open

is_open() -> bool

---------------- Connections ----------------

Parameters

No parameters.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

close

close() -> void

Close and release retained resources.

Parameters

No parameters.

Return value

void

No value is returned.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

check

check(sql: String) -> Variant, Err

Validate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

check_async

check_async(sql: String) -> await Variant, Err

Validate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL statement; bind external values through the separate parameter array.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

in_flight

in_flight() -> int

Count operations awaiting encoding or replies.

Parameters

No parameters.

Return value

int

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

cached_stmts

cached_stmts() -> int

Count cached statements.

Parameters

No parameters.

Return value

int

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.