gdドキュメント0.8.0

APIリファレンス

GDDatabaseClient

SQLiteとPostgreSQLに共通する、SQLの実行、1行ずつの読み取り、先頭行の取得、接続状況の確認に使います。

メソッド

open

open(opts: Dictionary) -> Variant, Err

設定の辞書に従ってSQLiteまたはPostgreSQLへ接続します。

引数

名前型省略時の値説明
optsDictionary省略不可処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

Variant, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

max_rowsとmax_bytesは0..2147483647を受け付けます。秒の指定は有限の0..9223372036.854776で、0は無期限です。ポートは1..65535です。

open_async

open_async(opts: Dictionary) -> await Variant, Err

設定の辞書に従ってSQLiteまたはPostgreSQLへ接続します。

引数

名前型省略時の値説明
optsDictionary省略不可処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

await Variant, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

max_rowsとmax_bytesは0..2147483647を受け付けます。秒の指定は有限の0..9223372036.854776で、0は無期限です。ポートは1..65535です。

query

query(sql: String, args: Array = []) -> Dictionary, Err

SQL文を実行します。SQLiteとPostgreSQLの両方で使えます。値を入れる位置は$1、$2のように書き、実際の値はargsで渡します。値をSQL文へ文字列としてつなげないでください。

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。値を入れる位置には$1、$2などを書きます。
argsArray[]SQL文中の$1、$2などに渡す値を、番号順に並べた配列。

戻り値

Dictionary, Err

結果を辞書で返します。先頭の1行だけが必要ならquery_row、大量の行を少しずつ読む場合はquery_rowsを使います。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

接続、パラメーターの設定、SQLの実行に失敗した場合はErrを返します。

関連文書

query_async

query_async(sql: String, args: Array = []) -> await Dictionary, Err

SQL文を実行します。SQLiteとPostgreSQLの両方で使えます。値を入れる位置は$1、$2のように書き、実際の値はargsで渡します。値をSQL文へ文字列としてつなげないでください。

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。値を入れる位置には$1、$2などを書きます。
argsArray[]SQL文中の$1、$2などに渡す値を、番号順に並べた配列。

戻り値

await Dictionary, Err

結果を辞書で返します。先頭の1行だけが必要ならquery_row、大量の行を少しずつ読む場合はquery_rowsを使います。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

接続、パラメーターの設定、SQLの実行に失敗した場合はErrを返します。

関連文書

query_row

query_row(sql: String, args: Array = []) -> Dictionary, Err

SQL文を実行して、先頭の1行を返します。該当する行がない場合はエラーになるため、Errを確認してください。

引数

名前型省略時の値説明
sqlString省略不可取得する行を指定するSQL文。
argsArray[]SQL文中のプレースホルダーに渡す値の配列。

戻り値

Dictionary, Err

先頭行を辞書で返します。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

一致する行がない場合と実行失敗はErrで返ります。

関連文書

query_row_async

query_row_async(sql: String, args: Array = []) -> await Dictionary, Err

SQL文を実行して、先頭の1行を返します。該当する行がない場合はエラーになるため、Errを確認してください。

引数

名前型省略時の値説明
sqlString省略不可取得する行を指定するSQL文。
argsArray[]SQL文中のプレースホルダーに渡す値の配列。

戻り値

await Dictionary, Err

先頭行を辞書で返します。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

一致する行がない場合と実行失敗はErrで返ります。

関連文書

query_rows

query_rows(sql: String, args: Array = []) -> GDDatabaseRows, Err

結果を1行ずつ読み取るためのオブジェクトを作ります。大量のデータをまとめてメモリに置かずに処理できます。読み取りを終えたときも、途中で止めるときもclose()を呼んでください。

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。
argsArray[]SQL文中のプレースホルダーに渡す値の配列。

戻り値

GDDatabaseRows, Err

行を読み取るGDDatabaseRowsです。next()で次の行へ進み、scan()またはvalues()でその行の値を取得します。ループのあとでerr()を確認してください。

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

SQLの実行開始時のエラーは戻り値のErrで確認します。行を読み取る途中で起きたエラーはrows.err()で確認します。

関連文書

query_rows_async

query_rows_async(sql: String, args: Array = []) -> await GDDatabaseRows, Err

結果を1行ずつ読み取るためのオブジェクトを作ります。大量のデータをまとめてメモリに置かずに処理できます。読み取りを終えたときも、途中で止めるときもclose()を呼んでください。

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。
argsArray[]SQL文中のプレースホルダーに渡す値の配列。

戻り値

await GDDatabaseRows, Err

行を読み取るGDDatabaseRowsです。next()で次の行へ進み、scan()またはvalues()でその行の値を取得します。ループのあとでerr()を確認してください。

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

SQLの実行開始時のエラーは戻り値のErrで確認します。行を読み取る途中で起きたエラーはrows.err()で確認します。

関連文書

transaction

transaction(action: Callable) -> Variant, Err

複数のSQLを1つのトランザクションとして実行します。渡した関数が成功を返すと変更を確定(コミット)し、エラーを返すと取り消します(ロールバック)。関数が受け取った専用のオブジェクトを使い、関連するSQLを実行してください。

引数

名前型省略時の値説明
actionCallable省略不可トランザクションオブジェクトを受け取るCallable。

戻り値

Variant, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

渡した関数の実行や変更の確定に失敗した場合は、Errを返します。

SQLiteでは、別のワーカーからの共有query()はトランザクションの終了まで待ち、同じコールバックからの共有query()はすぐエラーになります。PostgreSQLのプールでは、通常のquery()とほかのトランザクションは別の接続を使います。単一のPostgreSQL接続では、トランザクション中の共有query()と二重のトランザクションを拒否します。

関連文書

transaction_async

transaction_async(action: Callable) -> await Variant, Err

複数のSQLを1つのトランザクションとして実行します。渡した関数が成功を返すと変更を確定(コミット)し、エラーを返すと取り消します(ロールバック)。関数が受け取った専用のオブジェクトを使い、関連するSQLを実行してください。

引数

名前型省略時の値説明
actionCallable省略不可トランザクションオブジェクトを受け取るCallable。

戻り値

await Variant, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

渡した関数の実行や変更の確定に失敗した場合は、Errを返します。

SQLiteでは、別のワーカーからの共有query()はトランザクションの終了まで待ち、同じコールバックからの共有query()はすぐエラーになります。PostgreSQLのプールでは、通常のquery()とほかのトランザクションは別の接続を使います。単一のPostgreSQL接続では、トランザクション中の共有query()と二重のトランザクションを拒否します。

関連文書

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.

引数

名前型省略時の値説明
actionCallable省略不可英語原文 Callable receiving the transaction object on each attempt.

戻り値

Variant, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

英語原文

Return the last transaction result unchanged when another error occurs or all attempts fail.

関連文書

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.

引数

名前型省略時の値説明
actionCallable省略不可英語原文 Callable receiving the transaction object on each attempt.

戻り値

await Variant, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

英語原文

Return the last transaction result unchanged when another error occurs or all attempts fail.

関連文書

migrate

migrate(statements: Array) -> int, Err
英語原文

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

引数

名前型省略時の値説明
statementsArray省略不可実行順に並べたマイグレーション用SQL文。

戻り値

int, Err

この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

migrate_async

migrate_async(statements: Array) -> await int, Err
英語原文

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

引数

名前型省略時の値説明
statementsArray省略不可実行順に並べたマイグレーション用SQL文。

戻り値

await int, Err

完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。

エラー

処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。

stats

stats() -> Dictionary
英語原文

Return connection-pool state and cumulative waiting statistics.

引数

引数はありません。

戻り値

Dictionary

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

close

close() -> void
英語原文

Close the current connection.

引数

引数はありません。

戻り値

void

値を返しません。

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。

is_open

is_open() -> bool
英語原文

Check whether the selected driver is connected.

引数

引数はありません。

戻り値

bool

エラー

この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。