gdDocumentation0.8.0

API reference

GDPostgresPool

Concurrency-safe pool opening PostgreSQL connections on demand up to a maximum, with a wait queue and connection statistics.

Methods

open

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

Configure the pool and create connections lazily on first use.

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.
sizeint0Number of physical connections in the pool.

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 through an available connection; scripts use await pool.query(...).

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 through an available connection.

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

Return rows sequentially while retaining the borrowed connection until Rows closes.

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 rows as column-ordered arrays.

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 row values in one 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 through one connection with one wait and completion signal.

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 rows from its queries.

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 column-ordered row 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 through one connection and return only the completion count.

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 = {  }, size: int = 0) -> await Variant, Err

Configure the pool and create connections lazily on first use.

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.
sizeint0Number of physical connections in the pool.

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 through an available connection; scripts use await pool.query(...).

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 through an available connection.

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

Return rows sequentially while retaining the borrowed connection until Rows closes.

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 rows as column-ordered arrays.

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 row values in one 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 through one connection with one wait and completion signal.

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 rows from its queries.

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 column-ordered row 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 through one connection and return only the completion count.

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.

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.

size

size() -> int

Return the number of physical connections currently owned by this pool.

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.

in_flight

in_flight() -> int

Return the number of active queries.

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.

stats

stats() -> Dictionary

Return connection-pool state and cumulative wait statistics.

Parameters

No parameters.

Return value

Dictionary

Errors

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