API reference
GDDatabaseClient
Client providing shared SQLite and PostgreSQL queries, streaming Rows, first-row lookup, and connection statistics.
Methods
open(opts: Dictionary) -> Variant, Erropen_async(opts: Dictionary) -> await Variant, Errquery(sql: String, args: Array = []) -> Dictionary, Errquery_async(sql: String, args: Array = []) -> await Dictionary, Errquery_row(sql: String, args: Array = []) -> Dictionary, Errquery_row_async(sql: String, args: Array = []) -> await Dictionary, Errquery_rows(sql: String, args: Array = []) -> GDDatabaseRows, Errquery_rows_async(sql: String, args: Array = []) -> await GDDatabaseRows, Errtransaction(action: Callable) -> Variant, Errtransaction_async(action: Callable) -> await Variant, Errserialize(action: Callable) -> Variant, Errserialize_async(action: Callable) -> await Variant, Errmigrate(statements: Array) -> int, Errmigrate_async(statements: Array) -> await int, Errstats() -> Dictionaryclose() -> voidis_open() -> bool
open
open(opts: Dictionary) -> Variant, ErrReturn open's completion signal without waiting, for composition.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | Required | 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.
max_rows and max_bytes accept 0..2147483647. Second values are finite, 0..9223372036.854776; 0 has no deadline. Ports are 1..65535.
open_async
open_async(opts: Dictionary) -> await Variant, ErrReturn open's completion signal without waiting, for composition.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
opts | Dictionary | Required | 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.
max_rows and max_bytes accept 0..2147483647. Second values are finite, 0..9223372036.854776; 0 has no deadline. Ports are 1..65535.
query
query(sql: String, args: Array = []) -> Dictionary, ErrExecute a SQL statement with bound parameter values. The shared interface supports SQLite and PostgreSQL; use portable numbered placeholders such as $1 instead of interpolating values into SQL.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | Portable SQL using numbered placeholders such as $1 for both supported drivers. |
args | Array | [] | Parameter values in placeholder order. |
Return value
Dictionary, Err
A dictionary containing the query result. Use query_row for one row or query_rows to iterate without buffering all rows.
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.
Connection, binding and database execution errors return Err.
See also
query_async
query_async(sql: String, args: Array = []) -> await Dictionary, ErrExecute a SQL statement with bound parameter values. The shared interface supports SQLite and PostgreSQL; use portable numbered placeholders such as $1 instead of interpolating values into SQL.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | Portable SQL using numbered placeholders such as $1 for both supported drivers. |
args | Array | [] | Parameter values in placeholder order. |
Return value
await Dictionary, Err
A dictionary containing the query result. Use query_row for one row or query_rows to iterate without buffering all rows.
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.
Connection, binding and database execution errors return Err.
See also
query_row
query_row(sql: String, args: Array = []) -> Dictionary, ErrRun a parameterized query and return its first row. Choose this when one row is expected, and explicitly handle the no-row outcome rather than treating it as an empty successful record.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | Query selecting the desired row. |
args | Array | [] | Bound parameter values. |
Return value
Dictionary, Err
The first row as a dictionary.
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.
No matching row and execution failures are represented by Err.
See also
query_row_async
query_row_async(sql: String, args: Array = []) -> await Dictionary, ErrRun a parameterized query and return its first row. Choose this when one row is expected, and explicitly handle the no-row outcome rather than treating it as an empty successful record.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | Query selecting the desired row. |
args | Array | [] | Bound parameter values. |
Return value
await Dictionary, Err
The first row as a dictionary.
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.
No matching row and execution failures are represented by Err.
See also
query_rows
query_rows(sql: String, args: Array = []) -> GDDatabaseRows, ErrOpen a sequential row result for processing large query results incrementally. Close it when finished or when stopping early.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL query. |
args | Array | [] | Bound parameter values. |
Return value
GDDatabaseRows, Err
A rows object. Call next(), then scan() or values(); after iteration inspect 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.
Opening can fail immediately; errors discovered during iteration are retained by rows.err().
See also
query_rows_async
query_rows_async(sql: String, args: Array = []) -> await GDDatabaseRows, ErrOpen a sequential row result for processing large query results incrementally. Close it when finished or when stopping early.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
sql | String | Required | SQL query. |
args | Array | [] | Bound parameter values. |
Return value
await GDDatabaseRows, Err
A rows object. Call next(), then scan() or values(); after iteration inspect 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.
Opening can fail immediately; errors discovered during iteration are retained by rows.err().
See also
transaction
transaction(action: Callable) -> Variant, ErrRun a callback using a dedicated transaction connection. Return success to commit, or return a failure to roll back. Perform related queries through the callback transaction object.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
action | Callable | Required | Callable receiving the transaction object. |
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.
Callback and commit failures propagate through Err.
With SQLite, a shared query() from another worker waits for the transaction to end, and one from the same callback fails at once. A PostgreSQL pool runs ordinary queries and other transactions on separate connections. A single PostgreSQL connection rejects shared queries and nested transactions while a transaction is active.
See also
transaction_async
transaction_async(action: Callable) -> await Variant, ErrRun a callback using a dedicated transaction connection. Return success to commit, or return a failure to roll back. Perform related queries through the callback transaction object.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
action | Callable | Required | Callable receiving the transaction object. |
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.
Callback and commit failures propagate through Err.
With SQLite, a shared query() from another worker waits for the transaction to end, and one from the same callback fails at once. A PostgreSQL pool runs ordinary queries and other transactions on separate connections. A single PostgreSQL connection rejects shared queries and nested transactions while a transaction is active.
See also
serialize
serialize(action: Callable) -> Variant, ErrRun a PostgreSQL transaction again only when its server error has SQLSTATE 40001. Each attempt creates a fresh transaction, with at most ten attempts.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
action | Callable | Required | Callable receiving the transaction object on each attempt. |
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.
Return the last transaction result unchanged when another error occurs or all attempts fail.
See also
serialize_async
serialize_async(action: Callable) -> await Variant, ErrRun a PostgreSQL transaction again only when its server error has SQLSTATE 40001. Each attempt creates a fresh transaction, with at most ten attempts.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
action | Callable | Required | Callable receiving the transaction object on each attempt. |
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.
Return the last transaction result unchanged when another error occurs or all attempts fail.
See also
migrate
migrate(statements: Array) -> int, ErrReturn migration's completion signal without waiting, for composition.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
statements | Array | Required | SQL migration statements in execution order. |
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.
migrate_async
migrate_async(statements: Array) -> await int, ErrReturn migration's completion signal without waiting, for composition.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
statements | Array | Required | SQL migration statements in execution order. |
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.
stats
stats() -> DictionaryReturn connection-pool state and cumulative waiting 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.
close
close() -> voidClose the current connection.
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.
is_open
is_open() -> boolCheck whether the selected driver is connected.
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.