OCI8

このクラスのインスタンスはデータベースへの接続に対応します。JDBC の java.sql.Connection, Perl/DBI の database handle: $dbh に対応します。

OCI8.new(userid, password, dbname = nil, privilege = nil)

userid, password でもってオラクルへ接続します。dbname は Net8 の 接続文字列です。DBA 権限が必要な場合は privilege に :SYSDBA また は :SYSOPERを指定します。 Oracle クライアントが 10g 以降ならば、dbname として、"//ホスト名_or_IP:ポート番号/ORACLE_SID" が使用できます。

 # sqlplus scott/tiger
 conn = OCI8.new("scott", "tiger")

 # sqlplus scott/tiger@orcl.world
 conn = OCI8.new("scott", "tiger", "orcl.world")

 # sqlplus 'sys/change_on_install as sysdba'
 conn = OCI8.new("sys", "change_on_install", nil, :SYSDBA)

 # sqlplus scott/tiger@//oracle_db.example.com/XE
 conn = OCI8.new("scott", "tiger", "//oracle_db.example.com/XE")

OS認証でもってOracleに接続するには、userid, password に nil を渡してください。(new in 1.0.0-rc2)

logoff()

オラクルとの接続を切ります。コミットされてないトランザクションは ロールバックされます。

 conn = OCI8.new("scott", "tiger")
 ... do something ...
 conn.logoff

exec(sql, *bindvars)

sql 文を実行します。sql 文が SELECT文、INSERT/UPDATE/DELETE文、 CREATE/ALTER/DROP文、PL/SQL文、それぞれ場合で戻り値の種類が異なり ます。

bindvars がある場合、バインド変数としてバインドしてから実行します。

SELECT 文でブロックがついてない場合、OCI8::Cursor のインスタンス を返します。

 conn = OCI8.new('scott', 'tiger')
 cursor = conn.exec('SELECT * FROM emp')
 while r = cursor.fetch()
   puts r.join(',')
 end
 cursor.close
 conn.logoff

SELECT 文でブロックがついている場合、イテレータとして動き、処理 した行数が返ります。ブロックにはフェッチしたデータが配列でわたり ます。NULL値は ruby 側では nil にマッピングしてあります。

 conn = OCI8.new('scott', 'tiger')
 num_rows = conn.exec('SELECT * FROM emp') do |r|
   puts r.join(',')
 end
 puts num_rows.to_s + ' rows were processed.'
 conn.logoff

INSERT/UPDATE/DELETE文の場合、それぞれ処理した行数が返ります。

 conn = OCI8.new('scott', 'tiger')
 num_rows = conn.exec('UPDATE emp SET sal = sal * 1.1')
 puts num_rows.to_s + ' rows were updated.'
 conn.logoff

CREATE/ALTER/DROP文の場合、true が返ります。

 conn = OCI8.new('scott', 'tiger')
 conn.exec('CREATE TABLE test (col1 CHAR(6))')
 conn.logoff

PL/SQL文の場合、実行後のバインド変数の値が配列となって返ります。

 conn = OCI8.new('scott', 'tiger')
 conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
 # => ["0123", 123]
 conn.logoff

上記の例では、:str と :num という2つのバインド変数が あります。初期値としてそれぞれ"幅4で値は ABCD の文字列"と"値 123 の数値"が設定されてから、PL/SQL文が実行され、実行後のバインド変数 の値が配列として返ってきます。配列の順番はバインド変数の順番と同 じです。

parse(sql)

カーソルを作成し、sql 文実行の準備をします。OCI8::Cursor のインス タンスが返ります。

describe_table(table_name)

(new in 1.0.0 without 'rc')

OCI8::Metadata::TableまたはOCI8::Metadata::View を戻します。テーブル名が見つからないときは OCIError(Ora-04043) の例外が発生します。

commit()

トランザクションをコミットします。

 conn = OCI8.new("scott", "tiger")
 conn.exec("UPDATE emp SET sal = sal * 1.1") # yahoo
 conn.commit
 conn.logoff

rollback()

トランザクションをロールバックします。

 conn = OCI8.new("scott", "tiger")
 conn.exec("UPDATE emp SET sal = sal * 0.9") # boos
 conn.rollback
 conn.logoff

autocommit?

autocommit モードの状態を返します。デフォルトは false です。この 値が true のとき、INSERT/UPDATE/DELETE文が実行される毎に自動的に コミットされます。

autocommit = boolean_value

autocommit モードの状態を変更します。

 conn = OCI8.new("scott", "tiger")
 conn.autocommit = true
 ... do something ...
 conn.logoff

long_read_len

LONG 型、LONG RAW 型のデータをフェッチするときに内部で確保されるサイズを取得します。 デフォルト値は 65535 です。ruby-oci8 1.0 ではフェッチできる最大長となります。 フェッチした値が long_read_len よりも長いときはエラーとなります。 ruby-oci8 2.0 ではピース単位フェッチを行うときの１ピースのサイズとなります。 ピース単位フェッチは内部で自動的に行なわれます。

参照: LONG や LONG RAW のデータを使うには？

long_read_len = size

long_read_len のサイズを設定します。

参照: LONG や LONG RAW のデータを使うには？

prefetch_rows = rows

change the prefetch rows size. This reduces network round trips when fetching multiple rows. The default value is 1.

non_blocking?

ブロッキング/非ブロッキングモードの状態を返します。デフォルトは false、つまりブロッキングモードです。

non_blocking= boolean_value

ブロッキング/非ブロッキングモードの状態を変更します。

break

実行中の他スレッドの OCI 呼出しをキャンセルします。このメソッドを 実行するには非ブロッキングモードである必要があります。