Ruby/MySQL

[English page]

Ruby で記述された MySQL の Ruby API です。MySQL の C API とほぼ同等の機能があります。MySQL/Ruby と ほぼ互換があります。

必要なもの

• Ruby 1.6.8 以上

ライセンス

このプログラムは Ruby ライセンスに従います。

インストール

% ruby ./setup.rb
% ruby ./test.rb hostname user passwd
# ruby ./install.rb

セットアップ

% ruby ./setup.rb

MySQL の UNIX ドメインソケットを調べます。UNIX ドメインがない環境 (Microsoft Windows 等)では必要ありません。また、UNIX ドメインソケット が /tmp/mysql.sock である環境(MySQLをソースからコンパイルした場合等)で も必要ありません。

テスト

% ruby ./test.rb hostname user passwd

test.rb に与える hostname, user, passwd は MySQL サーバと、そのサーバ上でデータベースを作成することができるユーザ／パス ワードを指定してください。

インストール

# ruby ./install.rb

上記コマンドで Ruby の標準的なライブラリディレクトリ (Config::CONFIG["rubylibdir"])にインストールされます。他のディレクトリ に置きたい場合は手でコピーしてください。

ない機能

• 古いプロトコル(ver 9)には対応していません。
• C API の mysql_character_set_name(), mysql_debug() には対応していません。
• Mysql#options() は OPT_LOCAL_INFILE のみ対応しています。
• Mysql::Field#max_length は常に 0 です。

使い方

例)

require "mysql"
my = Mysql::new("host", "user", "passwd", "db")
res = my.query("select * from tbl")
res.each do |row|
  col1 = row[0]
  col2 = row[1]
end

リファレンス

メソッド名は C API の関数から mysql_ 接頭辞を除いたものと同じです。メ ソッドの使用方法も基本的に対応する C API 関数と同様ですので、詳細は MySQL のマニュアルを見てください。

メソッド中でエラーが発生した場合は Mysql::Error 例外が発生します。

特に意味のある値を返さない関数は self を返します。

Mysql クラス

MySQL を操作するためのクラスです。

クラスメソッド

init()

Mysql クラスオブジェクトを返します。mysqld には接続しません。

real_connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)

connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)

new(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)

mysqld に接続し、Mysql クラスオブジェクトを返します。flag の定数は C API のものと同じです。

例) Mysql::CLIENT_FOUND_ROWS

escape_string(str)

quote(str)

insert, update 用に文字列をクォートします。

get_client_info()

client_info()

クライアントバージョン情報の文字列を返します。

debug(str)

未対応

オブジェクトメソッド

options(opt, val=nil)

接続のためのオプションを設定します。現在有効なオプションは Mysql::OPT_LOCAL_INFILE のみです。val を省略するか真の値を設定すると、 LOAD DATA LOCAL INFILE クエリが使用できます。

real_connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)

connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)

Mysql::real_connect() と同じです。Mysql::init() で生成したオブジェクト をサーバに接続するために使用します。

affected_rows()

影響された行数を返します。

change_user(user=nil, passwd=nil, db=nil)

接続ユーザを変更します。

character_set_name()

未対応

close()

接続を切断します。

create_db(db)

データベースを作成します。

drop_db(db)

データベースを破棄します。

dump_debug_info()

C API mysql_dump_debug_info() と同じ。

errno()

エラー番号を返します。

error()

エラーメッセージを返します。

escape_string(str)

quote(str)

insert, update 用に文字列をクオートします。C API の mysql_real_escape_string() と同じ。

field_count()

最後に実行されたクエリの項目数を返します。

get_host_info()

host_info()

接続情報を文字列で返します。

get_proto_info()

proto_info()

接続プロトコルバージョンを数値で返します。

get_server_info()

server_info()

サーバのバージョン情報を文字列で返します。

info()

直前のクエリの情報を文字列で返します。特に情報がなければ nil が返りま す。

insert_id()

最後に生成された AUTO_INCREMENT 項目の値を返します。

kill(id)

id で指定したスレッドを殺します。

list_dbs(db=nil)

データベースの一覧を配列で返します。

list_fields(table, field=nil)

テーブル内の項目情報の一覧を示す Mysql::Result クラスオブジェクトを返 します。

list_processes()

サーバ上の現在のスレッドの一覧を示す Mysql::Result クラスオブジェクト を返します。

list_tables(table=nil)

テーブルの一覧を配列で返します。

ping()

サーバが生きているかどうかをチェックします。

query(q)

クエリを実行します。クエリが結果を返す場合、自動的に store_result() も 実行して、Mysql::Result クラスオブジェクトを返します。 query_with_result に false が設定されていれば、store_result() は実行し ません。結果を返さないクエリの場合は nil を返します。

query_with_result

query_with_result=bool

true に設定すると query() 時に store_result() も実行して、MysqlRes ク ラスオブジェクトを返します。false に設定するとその動作は行われません。 デフォルトは true です。

real_query(q)

クエリを実行します。query() と異なり、store_result() は実行しません。

refresh(r)

サーバのログやキャッシュ等をフラッシュします。

reload()

アクセス権テーブルを再読み込みします。

select_db(db)

データベースを選択します。

shutdown()

サーバを停止します。

stat()

サーバの状態を文字列で返します。

store_result()

クエリの結果の Mysql::Result クラスオブジェクトを返します。結果をすべ てメモリに読み込みます。

thread_id()

現在の接続のスレッドIDを返します。

use_result()

クエリの結果の Mysql::Result クラスオブジェクトを返します。結果は Mysql::Result#fetch_row または Mysql::Result#fetch_hash の度に１レコー ドずつ読み込まれます。

Mysql::Result クラス

クエリ結果のクラスです。互換のために MysqlRes という別名もあります。

オブジェクトメソッド

data_seek(offset)

現在の行の位置を offset 番目の行にします。

each() {|x| 〜}

fetch_row() を繰り返し呼び出し、fetch_row() 毎にブロックを実行します。 ブロック引数は fetch_row() の戻り値です。

each_hash(with_table=false) {|x| 〜}

fetch_hash() を繰り返し呼び出し、fetch_hash() 毎にブロックを実行します。 ブロック引数は fetch_hash() の戻り値です。

fetch_field()

現在の項目の Mysql::Field クラスオブジェクトを返します。次に呼ばれた時 は次の項目を返します。

fetch_fields()

項目全体を表す Mysql::Field クラスオブジェクトの配列を返します。

fetch_field_direct(n)

n 番目の項目の Mysql::Field クラスオブジェクトを返します。

fetch_lengths()

現在の行の各項目値の長さの配列を返します。

fetch_row()

検索結果の１行を返します。次に呼ばれた時は次の行を返します。戻り値は項 目値の配列です。

fetch_hash(with_table=false)

検索結果の１行を返します。次に呼ばれた時は次の行を返します。戻り値は項 目名をキーとした項目値のハッシュです。with_table が true の場合はキー にテーブル名も付加され、"テーブル名.項目名" という形式のキーになります。

field_seek(offset)

現在の項目位置を offset 番目の項目にします。

field_tell()

現在の項目の位置を返します。

free()

結果テーブル用メモリを解放します。GC::start を呼び出します。

num_fields()

項目数を返します。

num_rows()

検索件数を返します。

row_seek(offset)

現在の行の位置を設定します。data_seek() と同じです。

row_tell()

現在の行の位置を返します。

Mysql::Field クラス

項目の詳細を表すクラスです。互換のために MysqlField という別名もありま す。

オブジェクトメソッド

name()

項目名

table()

テーブル名

def()

デフォルト値

type()

項目の型

type に対応する定数は C API のものから FIELD_ 接頭辞を除いたものです。 例) Mysql::Field::TYPE_STRING

length()

項目の長さ

max_length()

検索結果中の項目値の最大長

flags()

フラグ

flag に対応する定数は C API のものと同じです。例) Mysql::Field::BLOB_FLAG

decimals()

小数部桁数

hash()

上記の変数名をキーとするハッシュを返します。例) obj.name == obj.hash['name']

Mysql::Error クラス

MySQL のエラーを表わすクラスです。MySQL のエラーが発生した場合に例外と して生成されます。互換のために MysqlError という別名もあります。

オブジェクトメソッド

errno()

エラー番号

errno に対応する定数は C API のものと同じです。例) Mysql::Error::CR_UNKNOWN_HOST

error()

エラーメッセージ

履歴

2004-10-07 ver. 0.2.5

• Mysql#close せずにプログラムが終了した場合、mysqld のエラーログに「Aborted connection」が記録される。

2004-01-21 ver. 0.2.4

• 値を返さないクエリの時に query() が nil を返すようにした(MySQL/Rubyとの互換のため)

2004-01-11 ver. 0.2.3a

• list_dbs(), list_tables() がおかしな値を返していた

2004-01-11 ver. 0.2.3

• list_dbs(), list_tables() に続くクエリがエラーになるバグを修正

2003-10-21 ver. 0.2.2

• Ruby の warning の回避
• setup.rb, install.rb の追加

2003-08-27 ver. 0.2.1

• 256レコード以上の結果レコードがエラーになるバグを修正

2003-08-19 ver. 0.2.0

• LOAD DATA LOCAL INFILE サポート
• Mysql#options() サポート (Mysql::OPT_LOCAL_INFILE のみ)
• UNIXSocket が未定義の環境のための変更
• トランザクション未サポートのサーバ接続時にエラーになるバグを修正

2003-08-16 ver. 0.1.5

• サーバー側エラーシンボル(ER_*)追加

2003-08-11 ver. 0.1.4

• real_connect() の flag に nil を指定するとエラーになるバグを修正

2003-07-27 ver. 0.1.3

• Ruby 1.8.0 対応

2003-07-25 ver. 0.1.2

• fetch_lengths(), fetch_row() のバグを修正

2003-07-24 ver. 0.1.1

• list_dbs(), list_tables() のバグを修正
• 英語のドキュメントを追加

2003-07-23 ver. 0.1

• 初期バージョン。

作者

とみたまさひろ tommy@tmtm.org http://www.tmtm.org