# MySQL/Ruby

[English]

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

## ダウンロード

- RubyForge
- tmtm.org

## 必要なもの

- MySQL 5.0.67
- Ruby 1.8.7, 1.9.1

これら以外でも 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, YEAR | Fixnum
  INT, BIGINT | FixnumまたはBignum
  FLOAT, DOUBLE | Float
  DECIMAL | String
  DATE, DATETIME, TIMESTAMP, TIME | Mysql::Time
  CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, TINYTEXT, TINYBLOB, TINYTEXT, MEDIUMBLOB, MEDIUMTEXT, LONGBLOB, LONGTEXT, ENUM, SET, BIT | String
  NULL | NilClass

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
  - Fix: Mysql#insert_id が 2**32 以上の時に不正な値を返す。
2009-02-01
  version 2.8.1
  - Ruby 1.9.1 に対応。
2008-09-29
  version 2.8
  version 2.7.7
  - MySQLへの接続時に SIGVTALRM で EINTR になることがある問題を修正 ([ruby-dev:31842])
  - MySQL/Ruby 2.7.* が Ruby 1.8.5 でコンパイルできなかった。
2008-06-20
  version 2.8pre4
  - エラー定義ファイルを外だし。その他。[ruby-dev:35152]
2008-06-17
  version 2.8pre3
  version 2.7.6
  - 64bit 環境で Mysql::Stmt#execute で大きな数値(2**30 以上)でエラーになる問題を修正。
2008-03-08
  version 2.8pre2
  version 2.7.5
  - 64bit 環境で Mysql::Stmt#fetch で数値が壊れる問題を修正。
2007-12-26
  version 2.8pre1
  - Ruby 1.9.0 対応
  - Incompat: Mysql::Result#each_hash が行毎にカラム名文字列を生成するのではなく、共有するようにした。
  - Incompat: ブロックつき Mysql#query で自動的にマルチステートメントモードにならないようにした。
2007-08-22
  version 2.7.4
  - BUG: Mysql::Stmt#execute がメモリリークしていた。
2006-12-20
  version 2.7.3
  - BUG: ブロックつき Mysql#query が、最後のクエリがエラーの場合に停止してしまう。
2006-10-28
  version 2.7.2
  - BUG: 結果を返さないクエリで Mysql::Stmt#result_metadata が nil を変えすようにした (Thanks to Hidetoshi)
  - BUG: Mysql#close で mysql_errno を見ないように変更
  - BUG: ブロックつき Mysql#query で複数ステートメント時にエラーを無視していた。
  - extconf.rb の Visual C++ 対応 (Thanks to Shugo Maeda)
  - BIT型に対応
  - Mysql::Field に TYPE_BIT, TYPE_NEWDECIMAL 追加
2006-06-04
  version 2.7.1
  - free() を xfree() に変更。Windows でのクラッシュの回避のため。(Tobias Grimm に感謝)
2005-08-22
  version 2.7
  - Mysql#options用定数追加。Mysql::OPT_GUESS_CONNECTION, Mysql::OPT_USE_EMBEDDED_CONNECTION, Mysql::OPT_USE_REMOTE_CONNECTION, Mysql::SET_CLIENT_IP
  - test.rb: 4.0.x, 5.0.x 対応
2005-08-16
  version 2.7-beta3
  - Mysql::Stmt#bind_result 追加
2005-08-02
  version 2.7-beta2
  - BUG: mysql.c.in: fetch_hash: 値が nil の要素がハッシュに含まれない。(Stefan Kaes に感謝)
  - 定数 Mysql::VERSION 追加
  - Mysql#prepare 追加
2005-07-24
  version 2.7-beta
  - Mysql#stmt_init 追加
  - Mysql::Stmt, Mysql::Time, Mysql::RowOffset クラス追加
  - Mysql::Error#sqlstate 追加
  - Mysql::Result#row_seek,row_tell が扱う offset 値を Mysql::RowOffset オブジェクトに変更
2005-07-31
  version 2.6.3
  - 定数 Mysql::VERSION 追加
2005-07-26
  version 2.6.2
  - BUG: mysql.c.in: fetch_hash: 値が nil の要素がハッシュに含まれない。(Stefan Kaes に感謝)
2005-06-28
  version 2.6.1
  - mysql.c.in: MacOSX でのコンパイルエラーを修正。
2005-04-25
  version 2.6
  - Mysql#option() 用の定数追加 Mysql::OPT_PROTOCOL, Mysql::OPT_READ_TIMEOUT, Mysql::OPT_WRITE_TIMEOUT, Mysql::SET_CHARSET_DIR, Mysql::SET_CHARSET_NAME, Mysql::SHARED_MEMORY_BASE_NAME, Mysql::SECURE_AUTH
  - Mysql#more_results?(), Mysql#next_result(), Mysql#set_server_option(), Mysql#sqlstate() 追加
  - Mysql#connect() のフラグ用定数追加 Mysql::CLIENT_MULTI_STATEMENTS, Mysql::CLIENT_MULTI_RESULTS
  - Mysql#set_server_option() 用の定数追加 Mysql::OPTION_MULTI_STATEMENTS_ON, Mysql::OPTION_MULTI_STATEMENTS_OFF
  - ブロック付き Mysql#query()
  - Mysql#reconnect(), Mysql#reconnect=() 追加
  - MySQL との接続が切れたときに、デフォルトでは再接続しないようにした。
2005-02-12
  version 2.5.2
  - BUG: Mysql#connect で接続すると接続が切断されない。(Andres Salomon に感謝)
2004-09-20
  version 2.5.1
  - Mysql#set_ssl() 追加。
2004-08-31
  version 2.5
  - MySQL 4.1.x 対応
  - MysqlRes, MysqlField, MysqlError を Mysql::Result, Mysql::Field, Mysql::Error に変更。
  - Mysql.client_version(), Mysql.get_client_version(), Mysql#client_version(), Mysql#get_client_version(), Mysql#server_version(), Mysql#get_server_version(), Mysql#warning_count(), Mysql#commit(), Mysql#rollback(), Mysql#autocommit() 追加。
  - Mysql::Field#is_not_null?(), Mysql::Field#is_pri_key?(), Mysql::Field#is_num?() 追加。
  - MysqlField::TYPE_VAR_STRING 追加。
2003-08-10
  version 2.4.5
  - extconf.rb: MySQL 4.1 対応。
  - mysql.c.in: Ruby 1.8 対応。
2003-02-23
  version 2.4.4a
  - extconf.rb の Ruby 1.8.0 対応。
2003-01-29
  version 2.4.4
  - Mysql::OPT_LOCAL_INFILE を追加。
  - extconf.rb に --with-mysql-config オプションを追加
  - extconf.rb 時に主なライブラリを自動検出するようにした。
2003-01-05
  version 2.4.3c
  - 英語の README の改版。Paul DuBois に感謝。
2002-12-24
  version 2.4.3b
  - extconf.rb の Ruby 1.6.8 対応。
2002-11-07
  version 2.4.3a
  - エラー定数が重複定義されることがあるバグを修正。
2002-09-10
  version 2.4.3
  - ER_ で始まるエラー定数にも対応した。
  - errmsg.h と mysqld_error.h から自動的にエラー定数を取得するようにした。
2002-01-07
  version 2.4.2
  - MySQL 4.0 対応。
  - uint を unsigned int に変更（mswin対応）。
2001-12-02
  version 2.4.1
  - 不要な extern を削除（Cygiwn対応）。
  - extconf.rb のオプションを変更。
2001-10-12
  version 2.4.0
  - Ruby 1.7 に対応。
  - Mysql::debug(), Mysql#change_user(), Mysql#character_set_name(), Mysql#dump_debug_info() を追加。
2001-03-25
  version 2.3.2a
  - t/50update.rb の判定方法を変更
2001-03-19
  version 2.3.2
  - 一定数(20回) MysqlRes オブジェクトを生成したら、強制的に GC するようにした。
  - Mysql#escape_string(), Mysql#quote() は mysql_real_escape_string() を使用するようにした。
2000-09-02
  version 2.3.1
  - Mysql#initialize() を追加(Ruby 1.6 対応)。
2000-07-22
  version 2.3.0
  - MysqlRes#free() を追加。
  - Mysql#initialize(), MysqlRes#initialize() を有効にした。
  - true を返していたメソッドを、self を返すようにした。
2000-05-27
  version 2.2.1a
  - test.rb を引数でパラメータを指定できるようにした。
2000-05-10
  version 2.2.1
  - データベースからのデータを「汚染された」文字列に変更。
  - テストスクリプト追加。
1999-09-28
  version 2.2.0
  - Mysql::init(), Mysql#options(), Mysql#real_connect() を追加。
  - Mysql#field_count を追加。
1999-09-24
  version 2.1.7
  - MySQL 3.22.26 に対応。
  - MysqlField#inspect() を追加。
1999-06-17
  version 2.1.6
  - fetch_field で落ちることがあった。
1999-06-12
  version 2.1.5
  - Ruby 1.3.x 対応が中途半端だった。
1999-05-30
  version 2.1.4
  - Ruby 1.3.x に対応。
1999-04-13
  version 2.1.3
  - fetch_hash/each_hash の引数の数の定義が間違っていた。
  - fetch_hash/each_hash に true を指定した時の項目名が欠けていた。
  - NULL値の項目があると fetch_hash/each_hash の動きがおかしかった。
1999-02-01
  version 2.1.2
  - Mysql#refresh() と Mysql::REFRESH_* を追加。
  - MySQL 3.21.xx にも対応(させたつもり…)。
1999-01-24
  version 2.1.1
  - MysqlError#error(), MysqlError#errno() を追加。
  - MysqlError::CR_* を追加。
1999-01-17
  version 2.1
  - fetch_hash, each_hash を C ソースに移動。
  - MysqlField#hash() を追加。
  - escape_string, get_client_info をオブジェクトメソッドとしても使えるようにした。
1998-11-29
  version 2.0.1
  - fetch_hash, each_hash に with_table 引数を追加。
  - やっぱり get_* メソッド名も C API と同じにした。
  - mysql-compat.rb を alias で書き直した。
  - Mysql の定数 CLIENT_* が MysqlField の定数になっていた。
1998-11-15
  version 2.0
  - メソッド名を C API と同じにした。
  - C++ でも通るように書き直した。
1998-08-13
  version 1.0
  - 初期バージョン。

## 作者

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

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