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)

PostgreSQLサーバと接続します。オプションの意味は以下の通りです。

pghost : サーバのホスト名(文字列)

pgport : サーバがlistenしているポート番号(整数)

pgoptions : backendを起動する際のオプション(文字列)

pgtty : backendがデバッグメッセージを表示するtty(文字列)

dbname : 接続するデータベース名(文字列)

login : ユーザ名(文字列)

dbname : パスワード(文字列)

失敗した場合は 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)

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

cmdstatus

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

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にラージオブジェクトを書き出します。