# $Id: README,v 1.24 2003/08/09 15:48:30 tommy Exp $

MySQL Ruby Module ver2.4.5

This is the MySQL API module for Ruby. It provides the same functions
for Ruby programs that the MySQL C API provides for C programs.

[Requirement]

* MySQL 3.23.54+
* Ruby 1.6.8+

The module may work for other versions, but that has not been verified.

[License]

This program is under Ruby's license.

[Install]

1st:
	% ruby extconf.rb
  or
	% ruby extconf.rb --with-mysql-dir=/usr/local/mysql
  or
	% ruby extconf.rb --with-mysql-config

  then
	% make

  extconf.rb has following options:

    --with-mysql-include=<dir>
	MySQL header file directory. Default is /usr/local/include.

    --with-mysql-lib=<dir>
	MySQL library directory. Default is /usr/local/lib.

    --with-mysql-dir=<dir>
	Same as --with-mysql-include=<dir>/include,
	--with-mysql-lib=<dir>/lib.

    --with-mysql-config[=/path/to/mysql_config]
	Get compile-parameter from mysql_config command.

2nd:
	% ruby -I. ./test.rb hostname user passwd

  test.rb should be invoked with three arguments that indicate the
  MySQL server hostname, and the username and password for a MySQL
  account that can create a database named "rubytest".  An optional
  fourth argument is allowed, to specify a database name to use rather
  than "rubytest".  The database should not already exist.

3rd:
	# make install

Note:

1. If you get error like 'libmysqlclient not found' when testing, you
   need to specify the directory in which the library is located so
   that make can find it.
	% env LD_RUN_PATH=<libmysqlclient.so directory> make

2. If you use the libmysqlclient.a static library, additional
   libraries may be needed. Edit extconf.rb to enable
   "have_library('m')" and "have_library('z')" for the -lm and -lz
   libraries if necessary.

[Usage]

The names of methods provided by this module basically are the same as
the names of the functions in the C API, except that the Ruby method
names do not begin with a 'mysql_' prefix. For example, the Ruby
query() method corresponds to the C API mysql_query() function. For
details on the use of each Ruby method, see the descriptions of the
corresponding C functions in the MySQL Reference Manual.

Some Ruby methods may be invoked under other names that serve as
equivalent aliases, as noted below.

If an error occurs when a method executes, it raises a MysqlError
exception.

require "mysql"
	loading mysql module.

[Mysql class]

 CLASS METHODS
    init()
	Used for Mysql#options()
    real_connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)
	alias: connect(), new()
    escape_string(str)
	alias: quote()
    get_client_info()
	alias: client_info()
    debug(str)

 OBJECT METHODS
    options(opt, val=nil)
    real_connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, sock=nil, flag=nil)
	alias: connect()
    affected_rows()
    change_user(user=nil, passwd=nil, db=nil)
    character_set_name()
    close()
    create_db(db)
    dump_debug_info()
    drop_db(db)
    errno()
    error()
    escape_string(str)
	alias: quote()
    field_count()
    get_host_info()
	alias: host_info()
    get_proto_info()
	alias: proto_info()
    get_server_info()
	alias: server_info()
    info()
    insert_id()
    kill(id)
    list_dbs(db=nil)
    list_fields(table, field=nil)
    list_processes()
    list_tables(table=nil)
    ping()
    query(q)
    refresh(r)
    reload()
    select_db(db)
    shutdown()
    stat()
    store_result()
    thread_id()
    use_result()

 OBJECT VARIABLES
    query_with_result
	If true, query() also invokes store_result() and returns a
	MysqlRes object.  Default is true.

[MysqlRes class]

 OBJECT METHODS
    free()
    data_seek(offset)
    fetch_field()
    fetch_fields()
    fetch_field_direct(fieldnr)
    fetch_lengths()
    fetch_row()
    fetch_hash(with_table=false)
    field_seek(offset)
    field_tell()
    num_fields()
    num_rows()
    row_seek(offset)
    row_tell()

 ITERATOR
    each() {|x| ...}
	'x' is array of column values.
    each_hash(with_table=false) {|x| ...}
	'x' is hash of column values, and the keys are the column names.

[MysqlField class]

 OBJECT VARIABLES (read only)
    name
    table
    def
    type
    length
    max_length
    flags
    decimals

 OBJECT METHODS
    hash()
    inspect()
	return string formatted "#<MysqlField:name>".

[MysqlError class]

 OBJECT VARIABLES (read only)
    error
    errno

[History]

  2003-08-10	2.4.5
    * extconf.rb: correspond to MySQL 4.1.
    * mysql.c.in: correspond to Ruby 1.8.

  2003-02-23	2.4.4a
    * make extconf.rb to correspond to Ruby 1.8.0

  2003-01-29	2.4.4
    * add Mysql::OPT_LOCAL_INFILE.
    * add --with-mysql-config option to extconf.rb.
    * extconf.rb automatically detect typical library.

  2003-01-05	2.4.3c
    * modified English README. Thanks to Paul DuBois.

  2002-12-24	2.4.3b
    * make extconf.rb to correspond to Ruby 1.6.8.

  2002-11-07	2.4.3a
    * fix bug duplicating constant.

  2002-09-10	2.4.3
    * for error number with prefix ER_ .
    * get error constant from errmsg.h and mysqld_error.h automatically.

  2002-01-07	2.4.2
    * for MySQL 4.0.
    * change `uint' to `unsigned int' (for mswin).

  2001-12-02	2.4.1
    * remove `extern' (for Cygiwn).
    * change option of extconf.rb.

  2001-10-12	2.4.0
    * for Ruby 1.7.
    * add Mysql::debug(), Mysql#change_user(), Mysql#character_set_name(),
      Mysql#dump_debug_info().

[Author]

  e-mail: TOMITA Masahiro <tommy@tmtm.org>
  http://www.tmtm.org/mysql/