db_postgres

高水準 PostgreSQL データベースのラッパーです。そのほかのデータベース実装でもインタフェースは共通化してあります。

関連: db_odbc, db_sqlite, db_mysql.

パラメータの置換

すべての db_* モジュールにおいてパラメータの置換は共通形式をサポートしています。つまり、値の置換先を表すのに ? (疑問符) を使います。用例:

sql"INSERT INTO myTable (colA, colB, colC) VALUES (?, ?, ?)"

備考: このモジュールではパラメータの置換方法を二通りサポートしています。

1. SqlQuery では ?, ?, ?, ... (すべての db_* モジュールで共通)

2. SqlPrepared では $1, $2, $3, ... を使います

prepare(db, "myExampleInsert",
        sql"""INSERT INTO myTable
              (colA, colB, colC)
              VALUES ($1, $2, $3)""",
        3)

用例

データベースの接続開始

import db_postgres
let db = open("localhost", "user", "password", "dbname")
db.close()

テーブルの作成

db.exec(sql"DROP TABLE IF EXISTS myTable")
db.exec(sql("""CREATE TABLE myTable (
                 id integer,
                 name varchar(50) not null)"""))

データの挿入

db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
        "Dominik")

DbConn = PPGconn
データベース接続のカプセル化   ソース 編集
Row = seq[string]
データセットの行。NULL データベース値は nil へ変換されます。  ソース 編集
InstantRow = object
  res: PPGresult               ## 行の取得で使われます
  line: int                    ## 要求されたテキスト
  
使用できるハンドル   ソース 編集
SqlPrepared = distinct string
準備済みクエリの識別子   ソース 編集

プロシージャ

proc dbError(db: DbConn) {...}{.noreturn, raises: [DbError], tags: [].}
DbError 例外を発生させます。  ソース 編集
proc dbQuote(s: string): string {...}{.raises: [], tags: [].}
データベースで使う文字列のクォート処理を行います。  ソース 編集
proc tryExec(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): bool {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}
クエリの実行を試行します。成功時は trueを、それ以外は false を返します。  ソース 編集
proc tryExec(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): bool {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [].}
クエリの実行を試行します。成功時は trueを、それ以外は false を返します。  ソース 編集
proc exec(db: DbConn; query: SqlQuery; args: varargs[string, `$`]) {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}
クエリを実行します。失敗したときは EDB が発生します。  ソース 編集
proc exec(db: DbConn; stmtName: SqlPrepared; args: varargs[string]) {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}
  ソース 編集
proc prepare(db: DbConn; stmtName: string; query: SqlQuery; nParams: int): SqlPrepared {...}{.
    raises: [DbError], tags: [].}
新しい SqlPrepared ステートメントを作成します。 パラメータの置換は $1, $2, $3, などで行われます。   ソース 編集
proc `[]`(row: InstantRow; col: int): string {...}{.inline, raises: [], tags: [].}
指定された行にある列のテキストを返します   ソース 編集
proc unsafeColumnAt(row: InstantRow; index: int): cstring {...}{.inline, raises: [], tags: [].}
指定された行にある列の cstring を返します   ソース 編集
proc len(row: InstantRow): int {...}{.inline, raises: [], tags: [].}
指定された行にある列の数値を返します   ソース 編集
proc getRow(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
一行取得します。クエリで行が返されないときは、このプロシージャは各列を空文字にした Row を返します。  ソース 編集
proc getRow(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
  ソース 編集
proc getAllRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): seq[Row] {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
クエリを実行した結果をデータセット全体として返します  ソース 編集
proc getAllRows(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): seq[Row] {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
準備済みクエリを実行した結果をデータセット全体として返します。  ソース 編集
proc getValue(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): string {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
クエリを実行した結果としてデータセットの最初の行にある最初の列を返します。データセットに行が無いか、データベースの値が NULL ならば "" を返します。  ソース 編集
proc getValue(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): string {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
クエリを実行した結果としてデータセットの最初の行にある最初の列を返します。データセットに行が無いか、データベースの値が NULL ならば "" を返します。  ソース 編集
proc tryInsertID(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{.
    tags: [WriteDbEffect], raises: [DbError, ValueError].}
クエリを実行後 (通常は "INSERT") に行の生成 ID、あるいはエラーならば -1 返します。Postgre において、これはクエリへ RETURNING id を追加します。つまり、プライマリ・キーは名前付き id として動作します。  ソース 編集
proc insertID(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{.
    tags: [WriteDbEffect], raises: [DbError, ValueError].}
クエリを実行後 (通常は "INSERT") に行の生成 ID を返します。Postgre において、これはクエリへ RETURNING id を追加します。つまり、プライマリ・キーは名前付き id として動作します。  ソース 編集
proc execAffectedRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError, ValueError].}
クエリを実行後 (通常は "UPDATE") に処理対象となった行数を返します。  ソース 編集
proc execAffectedRows(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError, ValueError].}
クエリを実行後 (通常は "UPDATE") に処理対象となった行数を返します。  ソース 編集
proc close(db: DbConn) {...}{.tags: [DbEffect], raises: [].}
データベースの接続を終了します。  ソース 編集
proc open(connection, user, password, database: string): DbConn {...}{.tags: [DbEffect],
    raises: [DbError].}

データベースの接続を開始します。接続を確立できないときは EDb が発生します。

クライアントでも Postgres キーワード・値の文字列を接続で使えます。

用例:

con = open("", "", "", "host=localhost port=5432 dbname=mydb")

詳細情報は http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING を参照してください。

  ソース 編集
proc setEncoding(connection: DbConn; encoding: string): bool {...}{.tags: [DbEffect],
    raises: [].}
データベース接続のエンコーディングを設定します。成功時は true を、失敗時は false を返します。  ソース 編集

イテレータ

iterator fastRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
クエリを実行した結果をデータセットとしてイテレートします。これは非常に高速ですが、潜在的な危険性があります: for ループ本体で別のクエリを実行してしまうと結果は未定義 (undefined) となります。なお、 Postgres では安全対策が講じられています。  ソース 編集
iterator fastRows(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
準備したクエリの実行後に結果をデータセットとしてイテレートします。  ソース 編集
iterator instantRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): InstantRow {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
fastRows と似ていますが、 [] で要求されたテキスト列の取得に使えるハンドルを返します。返されたハンドルはイテレータ本体でのみ有効です。  ソース 編集
iterator instantRows(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): InstantRow {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
fastRows と似ていますが、 [] で要求されたテキスト列の取得に使えるハンドルを返します。返されたハンドルはイテレータ本体でのみ有効です。  ソース 編集
iterator instantRows(db: DbConn; columns: var DbColumns; query: SqlQuery;
                    args: varargs[string, `$`]): InstantRow {...}{.tags: [ReadDbEffect],
    raises: [DbError].}
  ソース 編集
iterator rows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
fastRows と似ていますが、安全性を優先しているため処理速度は遅いです。  ソース 編集
iterator rows(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect], raises: [DbError].}
fastRows と似ていますが、安全性を優先しているため処理速度は遅いです。  ソース 編集