gdDocumentation0.8.0

API reference

GDDatabaseClient

Client providing shared SQLite and PostgreSQL queries, streaming Rows, first-row lookup, and connection statistics.

Methods

open

open(opts: Dictionary) -> Variant, Err

Return open's completion signal without waiting, for composition.

Parameters

NameTypeDefaultDescription
optsDictionaryRequiredNamed 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, Err

Return open's completion signal without waiting, for composition.

Parameters

NameTypeDefaultDescription
optsDictionaryRequiredNamed 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, Err

Execute 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

NameTypeDefaultDescription
sqlStringRequiredPortable SQL using numbered placeholders such as $1 for both supported drivers.
argsArray[]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, Err

Execute 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

NameTypeDefaultDescription
sqlStringRequiredPortable SQL using numbered placeholders such as $1 for both supported drivers.
argsArray[]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, Err

Run 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

NameTypeDefaultDescription
sqlStringRequiredQuery selecting the desired row.
argsArray[]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, Err

Run 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

NameTypeDefaultDescription
sqlStringRequiredQuery selecting the desired row.
argsArray[]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, Err

Open a sequential row result for processing large query results incrementally. Close it when finished or when stopping early.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL query.
argsArray[]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, Err

Open a sequential row result for processing large query results incrementally. Close it when finished or when stopping early.

Parameters

NameTypeDefaultDescription
sqlStringRequiredSQL query.
argsArray[]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, Err

Run 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

NameTypeDefaultDescription
actionCallableRequiredCallable 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, Err

Run 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

NameTypeDefaultDescription
actionCallableRequiredCallable 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, Err

Run a PostgreSQL transaction again only when its server error has SQLSTATE 40001. Each attempt creates a fresh transaction, with at most ten attempts.

Parameters

NameTypeDefaultDescription
actionCallableRequiredCallable 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, Err

Run a PostgreSQL transaction again only when its server error has SQLSTATE 40001. Each attempt creates a fresh transaction, with at most ten attempts.

Parameters

NameTypeDefaultDescription
actionCallableRequiredCallable 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, Err

Return migration's completion signal without waiting, for composition.

Parameters

NameTypeDefaultDescription
statementsArrayRequiredSQL 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, Err

Return migration's completion signal without waiting, for composition.

Parameters

NameTypeDefaultDescription
statementsArrayRequiredSQL 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() -> Dictionary

Return 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() -> void

Close 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() -> bool

Check 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.