API reference
GDPostgresPool
Concurrency-safe pool opening PostgreSQL connections on demand up to a maximum, with a wait queue and connection statistics.
Methods
open(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = { }, size: int = 0) -> Variant, Errquery(sql: String, args: Array = []) -> Dictionary, Errquery_row(sql: String, args: Array = [], max_bytes: int = 0) -> Dictionary, Errquery_rows(sql: String, args: Array = []) -> GDDatabaseRows, Errquery_values(sql: String, args: Array = []) -> Dictionary, Errquery_flat(sql: String, args: Array = []) -> Dictionary, Errquery_many(sql: String, rows: Array) -> Array, Errfetch_many(sql: String, rows: Array) -> Array, Errfetch_values_many(sql: String, rows: Array) -> Array, Errfetch_flat_many(sql: String, rows: Array) -> Array, Errexec_many(sql: String, rows: Array) -> int, Erropen_async(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = { }, size: int = 0) -> await Variant, Errquery_async(sql: String, args: Array = []) -> await Dictionary, Errquery_row_async(sql: String, args: Array = [], max_bytes: int = 0) -> await Dictionary, Errquery_rows_async(sql: String, args: Array = []) -> await GDDatabaseRows, Errquery_values_async(sql: String, args: Array = []) -> await Dictionary, Errquery_flat_async(sql: String, args: Array = []) -> await Dictionary, Errquery_many_async(sql: String, rows: Array) -> await Array, Errfetch_many_async(sql: String, rows: Array) -> await Array, Errfetch_values_many_async(sql: String, rows: Array) -> await Array, Errfetch_flat_many_async(sql: String, rows: Array) -> await Array, Errexec_many_async(sql: String, rows: Array) -> await int, Errclose() -> voidsize() -> intin_flight() -> intstats() -> Dictionary
open
open(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = { }, size: int = 0) -> Variant, ErrConfigure the pool and create connections lazily on first use.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
port | int | 5432 | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
size | int | 0 | Number 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, ErrSend through an available connection; scripts use await pool.query(...).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn only the first row through an available connection.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | Arguments in call or parameter-binding order. |
max_bytes | int | 0 | Maximum 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, ErrReturn rows sequentially while retaining the borrowed connection until Rows closes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn rows as column-ordered arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn all row values in one array.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrBatch one statement through one connection with one wait and completion signal.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrBatch one statement and flatten all rows from its queries.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrFlatten column-ordered row arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrReturn all row values in one array.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrBatch updates through one connection and return only the completion count.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrConfigure the pool and create connections lazily on first use.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
port | int | 5432 | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | Named options for this operation. Omitted entries use their documented defaults. |
size | int | 0 | Number 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, ErrSend through an available connection; scripts use await pool.query(...).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn only the first row through an available connection.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | Arguments in call or parameter-binding order. |
max_bytes | int | 0 | Maximum 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, ErrReturn rows sequentially while retaining the borrowed connection until Rows closes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn rows as column-ordered arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrReturn all row values in one array.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
args | Array | [] | 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, ErrBatch one statement through one connection with one wait and completion signal.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrBatch one statement and flatten all rows from its queries.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrFlatten column-ordered row arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrReturn all row values in one array.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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, ErrBatch updates through one connection and return only the completion count.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL statement; bind external values through the separate parameter array. |
rows | Array | Required | Rows 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() -> voidClose 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() -> intReturn 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() -> intReturn 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() -> DictionaryReturn 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.