Keywords: Ruby PostgreSQL

[English | Japanese]

# Postgres reference

Last update: Mon, 5 Mar 2001 00:34:55 +0900

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