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_decoderules and keep 64-bit integers. An ambiguous value, such as one with duplicate names, returns the original JSON text. numericreturns decimal text.realanddouble precisionreturn floats.bool[],smallint[],int[],bigint[],real[],double precision[],numeric[], andtext[]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(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = { }) -> 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 = { }) -> 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, Erris_open() -> boolclose() -> voidcheck(sql: String) -> Variant, Errcheck_async(sql: String) -> await Variant, Errin_flight() -> intcached_stmts() -> int
open
open(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = { }) -> Variant, ErrReturn a signal whose completion carries a value and an Err.
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. |
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 $1 and $2 values separately without interpolating them into SQL.
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 and drain the rest to the protocol boundary.
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, ErrRetain the connection's result and return one row per Next call.
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 column-ordered row arrays for bulk retrieval.
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 values in one row-major 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 with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.
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 returned rows.
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 rows from repeated statements as column-ordered 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 and return only the completion count without individual results.
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 = { }) -> await Variant, ErrReturn a signal whose completion carries a value and an Err.
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. |
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 $1 and $2 values separately without interpolating them into SQL.
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 and drain the rest to the protocol boundary.
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, ErrRetain the connection's result and return one row per Next call.
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 column-ordered row arrays for bulk retrieval.
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 values in one row-major 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 with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.
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 returned rows.
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 rows from repeated statements as column-ordered 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 and return only the completion count without individual results.
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.
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() -> 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.
check
check(sql: String) -> Variant, ErrValidate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL 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, ErrValidate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL 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() -> intCount 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() -> intCount 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.