MySQL/Ruby

[English]

これは MySQL の Ruby API です。MySQL の C API とほぼ同等の機能があります。

ダウンロード

必要なもの

これら以外でも make できるかもしれませんが、確認してません。

ライセンス

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

インストール

次を実行してください。 

% ruby extconf.rb

または 

% ruby extconf.rb --with-mysql-dir=/usr/local/mysql

または 

% ruby extconf.rb --with-mysql-config

それから 

% make

extconf.rb には次のオプションを指定できます。

--with-mysql-include=dir
MySQL のへッダファイルの場所として /usr/local/include の代わりのディレクトリを指定します。
--with-mysql-lib=dir
MySQL のライブラリの場所として /usr/local/lib の代わりのディレクトリを指定します。
--with-mysql-dir=dir
--with-mysql-include=dir/include, --with-mysql-lib=dir/lib と同じです。
--with-mysql-config[=/path/to/mysql_config]
mysql_config コマンドの結果からコンパイルパラメータを得ます。

次で簡単なテストができます。 

% ruby ./test.rb -- [hostname [user [passwd [dbname [port [socket [flag]]]]]]]

test.rb に与える引数は Mysql.real_connect() の引数と同じです。

問題なければ、スーパーユーザでインストールしてください。 

# make install

注意

テスト時にライブラリ libmysqlclient が見つからないというエラーが出る場合は、make 時にライブラリの場所を指定する必要があります。次のようにして make してみてください。 

% env LD_RUN_PATH=libmysqlclient.soの場所 make

test.rb は Linux 上での動作しか確認していません。 他のプラットフォームではエラーが出るかもしれません。

使い方

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

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

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

Mysql クラス

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

クラスメソッド

init()

Mysql クラスオブジェクトを返します。mysqld に接続はしません。 Mysql#options() が必要な場合は、これを呼んだ後に行ないます。

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()

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

get_client_version()
client_version()

クライアントバージョン情報を数値で返します。

debug(str)

C API mysql_debug() と同じ。

オブジェクトメソッド

options(opt, val=nil)

C API の mysql_options() と同じです。 opt に指定する定数は C API から MYSQL_ 接頭辞を取り除いたものです。

例) Mysql::OPT_CONNECT_TIMEOUT

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()

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

autocommit(mode)

autocommit モードを mode に設定します。mode が nil, false, 0 の時はオフ、それ以外の場合はオンです。

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

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

character_set_name()

現在の文字セットを返します。

close()

接続を切断します。

commit()

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

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_client_info()
client_info()

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

get_client_version()
client_version()

クライアントバージョン情報を数値で返します。

get_host_info()
host_info()

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

get_proto_info()
proto_info()

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

get_server_info()
server_info()

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

get_server_version()
server_version()

サーバのバージョン情報を数値で返します。

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)

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

more_results?()

取得していないクエリ結果がある場合は真を返します。

next_result()

取得していないクエリ結果がある場合は真を返します。 この後に store_result() を実行するとクエリ結果を取得できます。

ping()

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

prepare(q)

クエリをサーバに送ります。この時点ではまだ実行されません。 Mysql::Stmt クラスオブジェクトを返します。

Mysql#stmt_init.prepare(q) と同じです。

query(q)
real_query(q)

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

query(q) {|res| ...}
real_query(q) {|res| ...}

クエリを実行します。 クエリが結果を返す場合、Mysql::Result オブジェクトを引数としてブロックを実行します。 ブロック終了時に Mysql::Result オブジェクトは解放されます。 マルチステートメントモードで、引数に「;」で区切られた複数のクエリを指定した場合は、クエリの数だけブロックを繰り返します。

MySQL/Ruby 2.8 からは、自動的にマルチステートメントモードにはならなくなりました。 Mysql.connect の flag に Mysql::CLIENT_MULTI_STATEMENTS を指定するか、Mysql#set_server_option(Mysql::OPTION_MULTI_STATEMENTS_ON) を実行してください。

refresh(r)

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

reload()

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

rollback()

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

select_db(db)

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

set_server_option(opt)

引数で指定したオプションをサーバに設定します。 引数には、Mysql::OPTION_MULTI_STATEMENTS_ON, Mysql::OPTION_MULTI_STATEMENTS_OFF が指定できます。

shutdown()

サーバを停止します。

ssl_set(key=nil, cert=nil, ca=nil, capath=nil, cipher=nil)

SSL接続を使用します。Mysql.init() 後、Mysql#connect() 前に行なう必要があります。

stat()

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

stmt_init()

Mysql::Stmt クラスオブジェクトを返します。

store_result()

クエリの結果の Mysql::Result クラスオブジェクトを返します。

thread_id()

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

use_result()

クエリの結果の Mysql::Result クラスオブジェクトを返します。

warning_count()

直前のクエリの警告数を返します。

オブジェクト変数

query_with_result

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

reconnect

true に設定すると MySQL サーバとの接続が切れたときに自動的に再接続します。 デフォルトは false です。

Mysql::Result クラス

クエリ結果のクラスです。

オブジェクトメソッド

free()

結果テーブル用メモリを解放します。

data_seek(offset)

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

fetch_field()

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

fetch_fields()

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

fetch_field_direct(fieldnr)

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

fetch_lengths()

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

fetch_row()

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

fetch_hash(with_table=false)

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

field_seek(offset)

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

field_tell()

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

num_fields()

項目数を返します。

num_rows()

検索件数を返します。

row_seek(offset)

現在の行の位置を設定します。 offset は内部表現で row_tell() が返した Mysql::RowOffset クラスオブジェクトです。

row_tell()

現在の行の位置を Mysql::RowOffset クラスオブジェクトで返します。

イテレータ

each() {|x| 〜}

検索結果の各行ごとに {〜} を繰り返します。x は項目値の配列です。

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

検索結果の各行ごとに {〜} を繰り返します。 x は項目名をキーとした項目値のハッシュです。 with_table が true の場合はキーにテーブル名も付加され、"テーブル名.項目名" という形式のキーになります。

Mysql::Field クラス

項目の詳細を表すクラスです。C API と異なり、オブジェクトは Mysql::Result とは独立して存在するので、Mysql::Result クラスオブジェクトが解放された後でも利用できます。が、そのため C API よりもメモリを使用します。

オブジェクト変数(読み出しのみ)

name
項目名
table
テーブル名
def
デフォルト値
type
項目の型
length
項目の長さ
max_length
検索結果中の項目値の最大長
flags
フラグ
decimals
小数部桁数

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

例) Mysql::Field::TYPE_STRING

flag に対応する定数は C API のものと同じです。

例) Mysql::Field::BLOB_FLAG

オブジェクトメソッド

hash()

上記の変数名をキーとするハッシュを返します。

例) obj.name == obj.hash['name']

is_not_null?()

フィールドが "NOT NULL" と定義されていれば真を返します。

is_num?()

フィールドが数値の場合は真を返します。

is_pri_key?()

フィールドがプライマリキーの場合は真を返します。

inspect()

文字列 "#<Mysql::Field:項目名>" を返します。

Mysql::Stmt クラス

MySQL でプリペアドステートメントを扱うためのクラスです。

使用例: 

my = Mysql.new(hostname, username, password, databasename)
st = my.prepare("insert into tblname (col1,col2,col3) values (?,?,?)")
st.execute("abc",123,Time.now)
st.prepare("select col1,col2,col3 from tblname")
st.execute
st.fetch  # => ["abc", 123, #<Mysql::Time:2005-07-24 23:52:55>]
st.close

オブジェクトメソッド

affected_rows()

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

bind_result(class, ...)

結果を返すクエリの場合に、取り出される値のクラスを指定します。 指定できるクラスは、Numeric, Integer, Fixnum, Float, Mysql::Time です。 nil を指定すると、自動判別します。 bind_result を実行しない場合は自動判別します。

close()

Mysql::Stmt オブジェクトを解放します。

data_seek(offset)

次に fetch() で取り出される行を offset 番目の行にします。 offset は 0 から始まります。

execute(arg, ...)

prepare() したクエリにパラメータを与えて実行します。

fetch()

execute() で実行したクエリの結果の値を配列で取り出します。 値を返さないクエリの場合や、最後まで取り出した場合は nil を返します。

配列の各要素は MySQL の型に応じて次のようになります。

MySQLの型Rubyのクラス
TINYINT, SMALLINT, MEDIUMINT, YEARFixnum
INT, BIGINTFixnumまたはBignum
FLOAT, DOUBLEFloat
DECIMALString
DATE, DATETIME, TIMESTAMP, TIMEMysql::Time
CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, TINYTEXT, TINYBLOB, TINYTEXT, MEDIUMBLOB, MEDIUMTEXT, LONGBLOB, LONGTEXT, ENUM, SET, BITString
NULLNilClass
field_count()

prepare したクエリが返す結果のフィールド数を返します。

free_result()

検索結果を解放します。

insert_id()

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

num_rows()

検索結果の行数を返します。

param_count()

prepare() したクエリのパラメータ「?」の数を返します。

prepare(q)

クエリをサーバに送ります。この時点ではまだ実行されません。 execute() で実行されます。

result_metadata()

prepare() したクエリの返される結果のフィールドを Mysql::Result クラスオブジェクトで返します。

row_seek(offset)

次に fetch() で取り出される行を offset の位置にします。 data_seek と異なり offset は row_tell() で返される Mysql::RowOffset クラスオブジェクトです。

row_tell()

現在の行の位置を Mysql::RowOffset クラスオブジェクトで返します。

sqlstate()

エラーコードを SQLSTATE 文字列で返します。

イテレータ

each() {|x| 〜}

検索結果の各行ごとに {〜} を繰り返します。 x は fetch() で返されるものと同じ配列です。

Mysql::Time クラス

Mysql::Stmt で使われる日時を表すためのクラスです。

クラスメソッド

new(year=0,month=0,day=0,hour=0,minute=0,second=0,neg=false,second_part=0)

Mysql::Timeクラスを作成します。

オブジェクト変数

year
年
month
月
day
日
hour
時
minute
分
second
秒
neg
時刻が正の場合は false, 負の場合は true
second_part
秒の小数点以下。未使用

Mysql::Error クラス

MySQL のエラーを表わすクラスです。 MySQL のエラーが発生した場合に例外として生成されます。

オブジェクト変数(読み出しのみ)

error
エラーメッセージ
errno
エラー番号

errno に対応する定数は C API のものと同じです。

例) Mysql::Error::CR_UNKNOWN_HOST

履歴

2010-02-11
version 2.8.2
2009-02-01
version 2.8.1
2008-09-29
version 2.8
version 2.7.7
2008-06-20
version 2.8pre4
2008-06-17
version 2.8pre3
version 2.7.6
2008-03-08
version 2.8pre2
version 2.7.5
2007-12-26
version 2.8pre1
2007-08-22
version 2.7.4
2006-12-20
version 2.7.3
2006-10-28
version 2.7.2
2006-06-04
version 2.7.1
2005-08-22
version 2.7
2005-08-16
version 2.7-beta3
2005-08-02
version 2.7-beta2
2005-07-24
version 2.7-beta
2005-07-31
version 2.6.3
2005-07-26
version 2.6.2
2005-06-28
version 2.6.1
2005-04-25
version 2.6
2005-02-12
version 2.5.2
2004-09-20
version 2.5.1
2004-08-31
version 2.5
2003-08-10
version 2.4.5
2003-02-23
version 2.4.4a
2003-01-29
version 2.4.4
2003-01-05
version 2.4.3c
2002-12-24
version 2.4.3b
2002-11-07
version 2.4.3a
2002-09-10
version 2.4.3
2002-01-07
version 2.4.2
2001-12-02
version 2.4.1
2001-10-12
version 2.4.0
2001-03-25
version 2.3.2a
2001-03-19
version 2.3.2
2000-09-02
version 2.3.1
2000-07-22
version 2.3.0
2000-05-27
version 2.2.1a
2000-05-10
version 2.2.1
1999-09-28
version 2.2.0
1999-09-24
version 2.1.7
1999-06-17
version 2.1.6
1999-06-12
version 2.1.5
1999-05-30
version 2.1.4
1999-04-13
version 2.1.3
1999-02-01
version 2.1.2
1999-01-24
version 2.1.1
1999-01-17
version 2.1
1998-11-29
version 2.0.1
1998-11-15
version 2.0
1998-08-13
version 1.0

作者

e-mail: とみたまさひろ tommy@tmtm.org http://tmtm.org

TOMITA Masahiro
Last modified: Sun Feb 1 17:48:26 JST 2009