gdドキュメント0.8.0

APIリファレンス

GDPostgresClient

1つのPostgreSQL接続を操作します。通常の関数は呼び出した処理だけを待たせ、_async付きの関数はSignalを返します。

プールは最初の問い合わせまで接続を作らず、必要な分だけ最大数まで増やします。上限に達した後の問い合わせは受付順に待ちます。各問い合わせは実行中に接続を1本専有します。トランザクションとquery_rows()は、完了するか閉じるまで接続を保持します。

キャンセルと期限超過は、借りていた接続を閉じます。サーバー上のSQLが止まることまでは保証しません。

SQLSTATEはe.info.codeに残ります。一意制約違反はErr.ALREADY_EXISTS、その他のサーバーエラーはErr.ERRORです。

認証はサーバーの要求に合わせてSCRAM-SHA-256またはMD5を使います。平文パスワードにはallow_cleartext_passwordが要ります。

  • JSONとJSONBの列はGD.data.json_decodeと同じ規則で読み、64ビット整数を保ちます。重複した名前などあいまいな値は、元のJSON文字列を返します。
  • numericは十進数の文字列で返します。realとdouble precisionは浮動小数点数で返します。
  • bool[]、smallint[]、int[]、bigint[]、real[]、double precision[]、numeric[]、text[]は要素の型、null、入れ子を保ちます。numeric[]の要素は十進数の文字列です。下限を明示した配列は元の文字列を返します。

接続はUTF8を指定します。サーバーが別のクライアント文字コードへの変更を通知した場合は、エラーで接続を閉じます。変更したSQL自体は実行済みの場合があります。

1つのSQL文に渡せる値は65535個までです。1回の送信は、SQLとパラメーターの文字列をUTF-8のバイト数で数えて約1 GiBまでです。query_manyの件数に固定上限はありません。

メソッド

open

open(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = {  }) -> Variant, Err
英語原文

Return a signal whose completion carries a value and an Err.

引数

名前型省略時の値説明
hostString"127.0.0.1"接続または待ち受けに使うホスト名・IPアドレス。
portint5432ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

Variant, Err

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

エラー

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

query

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

Send $1 and $2 values separately without interpolating them into SQL.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

Dictionary, Err

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

エラー

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

query_row

query_row(sql: String, args: Array = [], max_bytes: int = 0) -> Dictionary, Err
英語原文

Return only the first row and drain the rest to the protocol boundary.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。
max_bytesint0クエリごとの制限を指定するときの、結果の最大バイト数。

戻り値

Dictionary, Err

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

エラー

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

query_rows

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

Retain the connection's result and return one row per Next call.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

GDDatabaseRows, Err

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

エラー

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

query_values

query_values(sql: String, args: Array = []) -> Dictionary, Err
英語原文

Return column-ordered row arrays for bulk retrieval.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

Dictionary, Err

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

エラー

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

query_flat

query_flat(sql: String, args: Array = []) -> Dictionary, Err
英語原文

Return all values in one row-major array.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

Dictionary, Err

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

エラー

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

query_many

query_many(sql: String, rows: Array) -> Array, Err
英語原文

Batch one statement with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

Array, Err

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

エラー

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

fetch_many

fetch_many(sql: String, rows: Array) -> Array, Err
英語原文

Batch one statement and flatten all returned rows.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

Array, Err

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

エラー

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

fetch_values_many

fetch_values_many(sql: String, rows: Array) -> Array, Err
英語原文

Flatten rows from repeated statements as column-ordered arrays.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

Array, Err

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

エラー

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

fetch_flat_many

fetch_flat_many(sql: String, rows: Array) -> Array, Err
英語原文

Return all row values in one array.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

Array, Err

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

エラー

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

exec_many

exec_many(sql: String, rows: Array) -> int, Err
英語原文

Batch updates and return only the completion count without individual results.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

int, Err

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

エラー

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

open_async

open_async(host: String = "127.0.0.1", port: int = 5432, opts: Dictionary = {  }) -> await Variant, Err
英語原文

Return a signal whose completion carries a value and an Err.

引数

名前型省略時の値説明
hostString"127.0.0.1"接続または待ち受けに使うホスト名・IPアドレス。
portint5432ネットワークのポート番号。待ち受け時の0はOSがポートを選びます。
optsDictionary{ }処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。

戻り値

await Variant, Err

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

エラー

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

query_async

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

Send $1 and $2 values separately without interpolating them into SQL.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

await Dictionary, Err

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

エラー

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

query_row_async

query_row_async(sql: String, args: Array = [], max_bytes: int = 0) -> await Dictionary, Err
英語原文

Return only the first row and drain the rest to the protocol boundary.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。
max_bytesint0クエリごとの制限を指定するときの、結果の最大バイト数。

戻り値

await Dictionary, Err

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

エラー

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

query_rows_async

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

Retain the connection's result and return one row per Next call.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

await GDDatabaseRows, Err

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

エラー

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

query_values_async

query_values_async(sql: String, args: Array = []) -> await Dictionary, Err
英語原文

Return column-ordered row arrays for bulk retrieval.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

await Dictionary, Err

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

エラー

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

query_flat_async

query_flat_async(sql: String, args: Array = []) -> await Dictionary, Err
英語原文

Return all values in one row-major array.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
argsArray[]関数へ渡す引数、またはSQL文中のプレースホルダーに渡す値を、順番に並べた配列。

戻り値

await Dictionary, Err

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

エラー

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

query_many_async

query_many_async(sql: String, rows: Array) -> await Array, Err
英語原文

Batch one statement with different arguments into one wait and completion signal. The server still receives and counts each as an individual query.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

await Array, Err

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

エラー

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

fetch_many_async

fetch_many_async(sql: String, rows: Array) -> await Array, Err
英語原文

Batch one statement and flatten all returned rows.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

await Array, Err

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

エラー

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

fetch_values_many_async

fetch_values_many_async(sql: String, rows: Array) -> await Array, Err
英語原文

Flatten rows from repeated statements as column-ordered arrays.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

await Array, Err

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

エラー

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

fetch_flat_many_async

fetch_flat_many_async(sql: String, rows: Array) -> await Array, Err
英語原文

Return all row values in one array.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

await Array, Err

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

エラー

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

exec_many_async

exec_many_async(sql: String, rows: Array) -> await int, Err
英語原文

Batch updates and return only the completion count without individual results.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。
rowsArray省略不可入力順の行。データベースの一括実行では各行が1組のパラメーターです。

戻り値

await int, Err

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

エラー

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

is_open

is_open() -> bool
英語原文

---------------- Connections ----------------

引数

引数はありません。

戻り値

bool

エラー

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

close

close() -> void
英語原文

Close and release retained resources.

引数

引数はありません。

戻り値

void

値を返しません。

エラー

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

check

check(sql: String) -> Variant, Err
英語原文

Validate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。

戻り値

Variant, Err

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

エラー

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

check_async

check_async(sql: String) -> await Variant, Err
英語原文

Validate syntax and names without execution by preparing, describing, and discarding. Use the server's parser instead of duplicating SQL syntax locally.

引数

名前型省略時の値説明
sqlString省略不可実行するSQL文。外部から受け取った値はSQL文につなげず、別の配列で渡します。

戻り値

await Variant, Err

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

エラー

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

in_flight

in_flight() -> int
英語原文

Count operations awaiting encoding or replies.

引数

引数はありません。

戻り値

int

エラー

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

cached_stmts

cached_stmts() -> int
英語原文

Count cached statements.

引数

引数はありません。

戻り値

int

エラー

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