# $Id: README.ja,v 1.2 2002/01/07 01:22:51 tommy Exp $

MySQL Ruby Module ver2.4.2

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

[必要なもの]

・MySQL 3.23.10 以上
・Ruby 1.4.5 以上

これら以外でも make できるかもしれませんが、確認してません。MySQL は 
3.21.x, 3.22.x でも make できるようにしたつもりですが、試してません :-X

[インストール]

次を実行してください。

	% ruby extconf.rb
	% 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 
	と同じです。

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

	% ruby -I. ./test.rb hostname user passwd

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

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

	# make install

注意:

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

2. スタティックライブラリの libmysqlclient.a を使用する場合は、いくつか
   ライブラリが必要になる場合があります。未解決シンボルのエラーが出る場
   合は extconf.rb 中の「have_library('m')」「have_library('z')」を有効
   にしてください。

[使い方]

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

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

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

require "mysql"
	mysql モジュールをロードします。

[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()
	クライアントバージョン情報の文字列を返します。

    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()
	影響された行数を返します。

    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)
	テーブル内の項目情報の一覧を示す MysqlRes クラスオブジェクトを返
	します。

    list_processes()
	サーバ上の現在のスレッドの一覧を示す MysqlRes クラスオブジェクト
	を返します。

    list_tables(table=nil)
	テーブルの一覧を配列で返します。

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

    query(q)
	クエリを実行します。Ruby では文字列の長さを判断できるので、
	real_query() はありません。
	クエリが結果を返す場合、自動的に store_result() も実行して、
	MysqlRes クラスオブジェクトを返します。
	query_with_result に false が設定されていれば、store_result() は
	実行しません。

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

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

    select_db(db)
	データベースを選択します。

    shutdown()
	サーバを停止します。

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

    store_result()
	クエリの結果の MysqlRes クラスオブジェクトを返します。

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

    use_result()
	クエリの結果の MysqlRes クラスオブジェクトを返します。

 オブジェクト変数

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

[MysqlRes クラス]

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

 オブジェクトメソッド

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

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

    fetch_field()
	現在の項目の MysqlField クラスオブジェクトを返します。次に呼ばれ
	た時は次の項目を返します。

    fetch_fields()
	項目全体を表す MysqlField クラスオブジェクトの配列を返します。

    fetch_field_direct(fieldnr)
	fieldnr 番目の項目の MysqlField クラスオブジェクトを返します。

    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() が返
	した値です。

    row_tell()
	現在の行の位置を内部表現で返します。

 イテレータ

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

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

[MysqlField クラス]

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

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

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

 オブジェクトメソッド

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

    inspect()
	文字列 "#<MysqlField:項目名>" を返します。

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

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

[MysqlError クラス]

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

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

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

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

[履歴]

  2002-01-07	2.4.2
    ・MySQL 4.0 対応。
    ・uint を unsigned int に変更（mswin対応）。

  2001-12-02	2.4.1
    ・不要な extern を削除（Cygiwn対応）。
    ・extconf.rb のオプションを変更。

  2001-10-12	2.4.0
    ・Ruby 1.7 に対応。
    ・Mysql::debug(), Mysql#change_user(), Mysql#character_set_name(),
      Mysql#dump_debug_info() を追加。

  2001-03-25	2.3.2a
    ・t/50update.rb の判定方法を変更

  2001-03-19	2.3.2
    ・一定数(20回) MysqlRes オブジェクトを生成したら、強制的に GC する
      ようにした。
    ・Mysql#escape_string(), Mysql#quote() は
      mysql_real_escape_string() を使用するようにした。

  2000-09-02	2.3.1
    ・Mysql#initialize() を追加(Ruby 1.6 対応)。

  2000-07-22	2.3.0
    ・MysqlRes#free() を追加。
    ・Mysql#initialize(), MysqlRes#initialize() を有効にした。
    ・true を返していたメソッドを、self を返すようにした。

  2000-05-27	2.2.1a
    ・test.rb を引数でパラメータを指定できるようにした。

  2000-05-10	2.2.1
    ・データベースからのデータを「汚染された」文字列に変更。
    ・テストスクリプト追加。

  1999-09-28	2.2.0
    ・Mysql::init(), Mysql#options(), Mysql#real_connect() を追加。
    ・Mysql#field_count を追加。

  1999-09-24	2.1.7
    ・MySQL 3.22.26 に対応。
    ・MysqlField#inspect() を追加。

  1999-06-17	2.1.6
    ・fetch_field で落ちることがあった。

  1999-06-12	2.1.5
    ・Ruby 1.3.x 対応が中途半端だった。

  1999-05-30	2.1.4
    ・Ruby 1.3.x に対応。

  1999-04-13	2.1.3
    ・fetch_hash/each_hash の引数の数の定義が間違っていた。
    ・fetch_hash/each_hash に true を指定した時の項目名が欠けていた。
    ・NULL値の項目があると fetch_hash/each_hash の動きがおかしかった。

  1999-02-01	2.1.2
    ・Mysql#refresh() と Mysql::REFRESH_* を追加。
    ・MySQL 3.21.xx にも対応(させたつもり…)。

  1999-01-24	2.1.1
    ・MysqlError#error(), MysqlError#errno() を追加。
    ・MysqlError::CR_* を追加。

  1999-01-17	2.1
    ・fetch_hash, each_hash を C ソースに移動。
    ・MysqlField#hash() を追加。
    ・escape_string, get_client_info をオブジェクトメソッドとしても
      使えるようにした。

  1998-11-29	2.0.1
    ・fetch_hash, each_hash に with_table 引数を追加。
    ・やっぱり get_* メソッド名も C API と同じにした。
    ・mysql-compat.rb を alias で書き直した。
    ・Mysql の定数 CLIENT_* が MysqlField の定数になっていた。

  1998-11-15	2.0
    ・メソッド名を C API と同じにした。
    ・C++ でも通るように書き直した。

  1998-08-13	1.0
    ・初期バージョン。

[作者]

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