Postgres reference

PGconn

PostgreSQLにアクセスするためのクラス。その他のメソッドはlibpqとほぼ同じインタフェースで提供されます。

例えば、localhost 上の PostgreSQL に接続し、query を出すためには以下のようにして行います。

require "postgres"
conn = PGconn.connect("localhost", 5432, "", "", "test1")
res = conn.exec("select * from a;")

スーバークラス:

Object

クラスメソッド:

connect(pghost, pgport, pgoptions, pgtty, dbname, login, passwd) new(pghost, pgport, pgoptions, pgtty, dbname, login, passwd) open(string)

PostgreSQLサーバと接続します。オプションの意味は以下の通りです。: pghost : サーバのホスト名(文字列); pgport : サーバがlistenしているポート番号(整数); pgoptions : backendを起動する際のオプション(文字列); pgtty : backendがデバッグメッセージを表示するtty(文字列); dbname : 接続するデータベース名(文字列); login : ユーザ名(文字列); passwd : パスワード(文字列)
オプションを文字列で渡す場合のフォーマットです。: host=name : サーバのホスト名(文字列); hostaddr=addr : サーバのIPアドレス(文字列); port=number サーバがlistenしているポート番号(整数); options=string : backendを起動する際のオプション(文字列); tty=anything : backendがデバッグメッセージを表示するtty(文字列); dbname=name : 接続するデータベース名(文字列); user=username : ユーザ名(文字列); password=censored : パスワード(文字列); sslmode=mode : SSLモードの指定(文字列) (disable, allow, prefer, require); service=name : 他のパラメータ用に使用されるサービス名(文字列); connect_timeout=seconds : 接続タイムアウト時間(整数)

失敗した場合は PGError 例外が発生します。

methods:

db: 接続したデータベース名を返します。
host: 接続したサーバ名を返します。
user: サーバへ接続時に認証したユーザ名を返します。
options: backendを起動する際に指定したoptionを返します。
port: サーバへ接続する際に使用したポート番号を返します。
tty: 接続しているpgttyを返します。
error: 接続に関するエラーメッセージを返します。
finish
close: バックエンドとの接続を終了します。
reset: バックエンドとの通信ポートをリセットします。この関数はバックエンドとのソケット接続を終了し、いずれかのバックエンドとの新しい接続の再確立を試みます。
trace(port): バックエンドとのメッセージの受渡しのトレースを有効にします。メッセージはportで指定された File クラスのインスタンスへ書き出されます。
untrace: バックエンドとのメッセージの受渡しのトレースを無効にします。
exec(sql): sqlで指定されたSQL問い合わせ文をPostgreSQLへ送ります。問い合わせが成功した場合には、結果がPGresultクラスのインスタンスとして返され、そうでない場合は例外が発生します。
query(sql): sqlで指定されたSQL問い合わせ文をPostgreSQLへ送ります。問い合わせが成功した場合には、結果が Array クラスのインスタンスとして返され、そうでない場合は nil が返されます。
async_exec(sql): sqlで指定されたSQL問い合わせ文をPostgreSQLへ非同期で送ります。問い合わせが成功した場合には、結果がPGresultクラスのインスタンスとして返され、そうでない場合は例外が発生します。
async_query(sql): sqlで指定されたSQL問い合わせ文をPostgreSQLへ非同期で送ります。問い合わせが成功した場合には、結果が Array クラスのインスタンスとして返され、そうでない場合は nil が返されます。
get_notify: バックエンドから未処理の通知リストを得て、Array クラスのインスタンスとして返します。バックエンドからの未処理の通知がない場合には、nil が返されます。
insert_table(table, array): tableで指定されたテーブルに対し、arrayの内容を挿入します。arrayは Array クラスのインスタンスでなければなりません。
getline: バックエンドサーバから改行コードで終る行を読み取ります。fgets(3)と同様に、このメソッドはget(3)と同様に終端行をヌルに変換します。getlineはEOFの場合は、nil を、行全体を読み取った場合は0を、まだ改行コードを読み取っていない場合は1を返します。このメソッドを使用する時の注意点は、バックエンドサーバが結果の送信を完了したことを示す単一文字"."を新規行に送信したことを確認しなければならないことです。
サンプルコードpsql.rbは、copyプロトコルを正しく扱うソースを含んでいます。
putline(string): stringで指定された文字列をバックエンドーサーバへ送信します。使用者はデータの送信が完了したことをバックエンドに示すために、単一文字"."を明示的に送信しなければなりません。
endcopy: バックエンドと同期をとります。このメソッドはバックエンドがcopyを完了するまで待ちます。putlineやgetlineを使用した場合に使用すべきメソッドです。copyがうまく完了した場合には nil が返り、そうでない場合は例外が発生します。
set_client_encoding: クライアントの文字コードを指定します(文字列)。
client_encoding: クライアントの文字コードを返します(文字列)。
lo_import(file): fileをラージオブジェクトにインポートします。成功するとPGlargeクラスのインスタンスが返されます。失敗すると PGError 例外が発生します。
lo_export(oid, file): ラージオブジェクトを file に保存します。
lo_create([mode]): 新しくラージオブジェクトをつくります。成功するとPGlarge クラスのインスタンスが返されます。失敗すると PGError 例外が発生します。
lo_open(oid, [mode]): oid のラージオブジェクトを開きます。成功するとPGlarge クラスのインスタンスが返されます。失敗すると PGError 例外が発生します。"INV_READ","INV_WRITE"のどちらかのモードを指定します。失敗すると PGError 例外が発生します。モードを省略した場合は"INV_READ"です。
lo_unlink(oid): oidのラージオブジェクトを削除します。

PGresult

Queryの結果として得られたタップルをwrapするクラス．このクラスのインスタンスは、queryを行うたびに生成されます。故に得られた結果が不要になった場合には、clearを呼び出してメモリを解放するようにして下さい。

スーパークラス:

Object

メソッド:

status

問い合わせ結果のステータスを返します。ステータスは以下の値のうちのいずれか一つを返します。: EMPTY_QUERY; COMMAND_OK; TUPLES_OK; COPY_OUT; COPY_IN

result

問い合わせ結果のタップル(インスタンス)を、配列で返します。

fields

問い合わせの結果のフィールド(属性)を、配列で返します。

num_tuples

問い合わせ結果のタップル(インスタンス)の数を返します。

num_fields

問い合わせの結果のフィールド(属性)の数を返します。

fieldname(index)

与えられたフィールド(属性)の索引(field index)に対応するフィールド(属性)の名前を返します。フィールド・インディケータは0から開始されます。

fieldnum(name)

与えられたフィールド(属性)の名前に対応する、フィールド(属性)の索引を返します。

type(index)

与えられたフィールド(属性)に対応するフィールドの型を返します。内部コーディングされている型が整数で返されます。フィールド・インディケータは0から開始されます。

size(index)

与えられたフィールド(属性)に対応するフィールドのサイズをバイト数で返します。返されるサイズが-1の場合、フィールドは可変長です。フィールド・インディケータは0から開始されます。

getvalue(tup_num, field_num)

フィールド(属性)の値を返します。ほとんどの問い合わせに対して、getvalueによって返される値は、ヌルで終わるASCII文字列で表現されます。問い合わせの結果がバイナリカーソルであった場合、getvalueによって返される値は、バックエンド・サーバの内部フォーマットに依存したバイナリで表現されます。データを正しいタイプにキャストしたり、変換したりするのはプログラマの責任です。PGresultのインスタンスはqueryのたびに生成されます。不要になった場合は、プログラマが責任をもってclearを呼び出しメモリを解放して下さい。

getlength(tup_num, field_num)

フィールド(属性)の長さをバイトで返します。

cmdtuples

最後の問い合わせコマンドの影響をうけた行数を返します。

cmdstatus

最後の問い合わせコマンドのコマンドステータスを文字列で返します。

oid

挿入された行のOIDを返します。

clear

問い合わせの結果生成されたPGresultのインスタンスをクリアします。

PGlarge

ラージオブジェクトにアクセスするためのクラス。このオブジェクトは lo_import, lo_create, lo_open の結果として返されます。

super class:

Object

methods:

open([mode]): ラージオブジェクトを開きます。 "INV_READ","INV_WRITE"のどちらかのモードを指定します。失敗すると PGError 例外が発生します。モードを省略した場合は"INV_READ"です。
close: ラージオブジェクトを閉じます。以降このオブジェクトに対するアクセスは例外を発生します。
read([length]): length バイト読み込んでその文字列を返します。length が省略された時には、全てのデータを読み込みます。
write(str): strをラージオブジェクトに書き込みます。書き込んだバイト数を返します。
seek(offset, whence): ラージオブジェクトのポインタを offset 移動します。whence は SEEK_SET, SEEK_CUR, and SEEK_END が指定できます。それぞれ 0,1,2と数字で指定しても構いません。
tell: ラージオブジェクトのポインタの現在の位置を返します。
unlink: ラージオブジェクトを削除します。
oid: ラージオブジェクトの oid を返します。
size: ラージオブジェクトのサイズを返します。
export(file): fileにラージオブジェクトを書き出します。