APIリファレンス
GDDatabaseClient
SQLiteとPostgreSQLに共通する、SQLの実行、1行ずつの読み取り、先頭行の取得、接続状況の確認に使います。
メソッド
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, Err設定の辞書に従ってSQLiteまたはPostgreSQLへ接続します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
opts | Dictionary | 省略不可 | 処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。 |
戻り値
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へ接続します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
opts | Dictionary | 省略不可 | 処理の設定を名前と値で指定する辞書。省略した項目には、この関数の既定値が使われます。 |
戻り値
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, ErrSQL文を実行します。SQLiteとPostgreSQLの両方で使えます。値を入れる位置は$1、$2のように書き、実際の値はargsで渡します。値をSQL文へ文字列としてつなげないでください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 実行するSQL文。値を入れる位置には$1、$2などを書きます。 |
args | Array | [] | 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, ErrSQL文を実行します。SQLiteとPostgreSQLの両方で使えます。値を入れる位置は$1、$2のように書き、実際の値はargsで渡します。値をSQL文へ文字列としてつなげないでください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 実行するSQL文。値を入れる位置には$1、$2などを書きます。 |
args | Array | [] | 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, ErrSQL文を実行して、先頭の1行を返します。該当する行がない場合はエラーになるため、Errを確認してください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 取得する行を指定するSQL文。 |
args | Array | [] | SQL文中のプレースホルダーに渡す値の配列。 |
戻り値
Dictionary, Err
先頭行を辞書で返します。
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
一致する行がない場合と実行失敗はErrで返ります。
関連文書
query_row_async
query_row_async(sql: String, args: Array = []) -> await Dictionary, ErrSQL文を実行して、先頭の1行を返します。該当する行がない場合はエラーになるため、Errを確認してください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 取得する行を指定するSQL文。 |
args | Array | [] | 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()を呼んでください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 実行するSQL文。 |
args | Array | [] | 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()を呼んでください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
sql | String | 省略不可 | 実行するSQL文。 |
args | Array | [] | 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を実行してください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
action | Callable | 省略不可 | トランザクションオブジェクトを受け取る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を実行してください。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
action | Callable | 省略不可 | トランザクションオブジェクトを受け取る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.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
action | Callable | 省略不可 | 英語原文 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.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
action | Callable | 省略不可 | 英語原文 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.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
statements | Array | 省略不可 | 実行順に並べたマイグレーション用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.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
statements | Array | 省略不可 | 実行順に並べたマイグレーション用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を返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。