Net::MySQL - Pure Perl MySQL network protocol interface.

- NAME
- SYNOPSIS
- DESCRIPTION

- Net::MySQL API
- Net::MySQL::RecordIterator API

- SUPPORT OPERATING SYSTEM
- SEE ALSO
- AUTHOR
- COPYRIGHT AND LICENCE

# NAME

Net::MySQL - Pure Perl MySQL network protocol interface.

# SYNOPSIS

      use Net::MySQL;

      my $mysql = Net::MySQL->new(
          # hostname => 'mysql.example.jp',   # Default use UNIX socket
          database => 'your_database_name',
          user     => 'user',
          password => 'password'
      );

      # INSERT example
      $mysql->query(q{
          INSERT INTO tablename (first, next) VALUES ('Hello', 'World')
      });
      printf "Affected row: %d\n", $mysql->get_affected_rows_length;

      # SLECT example
      $mysql->query(q{SELECT * FROM tablename});
      my $record_set = $mysql->create_record_iterator;
      while (my $record = $record_set->each) {
          printf "First column: %s Next column: %s\n",
              $record->[0], $record->[1];
      }
      $mysql->close;

# DESCRIPTION

Net::MySQL is a Pure Perl client interface for the MySQL database. This module implements network protocol between server and client of MySQL, thus you don't need external MySQL client library like libmysqlclient for this module to work. It means this module enables you to connect to MySQL server from some operation systems which MySQL is not ported. How nifty!

Since this module's final goal is to completely replace DBD::mysql, API is made similar to that of DBI.

From perl you activate the interface with the statement

        use Net::MySQL;

After that you can connect to multiple MySQL daemon and send multiple queries to any of them via a simple object oriented interface.

There are two classes which have public APIs: Net::MySQL and Net::MySQL::RecordIterator.

        $mysql = Net::MySQL->new(
            hostname => $host,
            database => $database,
            user     => $user,
            password => $password,
        );

Once you have connected to a daemon, you can can execute SQL with:

        $mysql->query(q{
            INSERT INTO foo (id, message) VALUES (1, 'Hello World')
        });

If you want to retrieve results, you need to create a so-called statement handle with:

        $mysql->query(q{
            SELECT id, message FROM foo
        });
        if ($mysql->has_selected_record) {
            my $a_record_iterator = $mysql->create_record_iterator;
            # ...
        }

This Net::MySQL::RecordIterator object can be used for multiple purposes. First of all you can retreive a row of data:

        my $record = $a_record_iterator->each;

The `each()` method takes out the reference result of one line at a time, and the return value is ARRAY reference.

## Net::MySQL API

`new(HASH)`

          use Net::MySQL;
          use strict;

          my $mysql = Net::MySQL->new(
              unixsocket => $path_to_socket,
              hostname   => $host,
              database   => $database,
              user       => $user,
              password   => $password,
          );

  The constructor of Net::MySQL. Connection with MySQL daemon is established and the object is returned. Argument hash contains following parameters:

unixsocket
  Path of the UNIX socket where MySQL daemon. default is /tmp/mysql.sock. Supposing hostname is omitted, it will connect by UNIX Socket.

hostname
  Name of the host where MySQL daemon runs. Supposing hostname is specified, it will connect by INET Socket.

port
  Port where MySQL daemon listens to. default is 3306.

database
  Name of the database to connect.

user / password
  Username and password for database authentication.

timeout
  The waiting time which carries out a timeout when connection is overdue is specified.

debug
  The exchanged packet will be outputted if a true value is given.

`create_database(DB_NAME)`
  A `create_DATABASE()` method creates a database by the specified name.

          $mysql->create_database('example_db');
          die $mysql->get_error_message if $mysql->is_error;

`drop_database(DB_NAME)`
  A `drop_database()` method deletes the database of the specified name.

          $mysql->drop_database('example_db');
          die $mysql->get_error_message if $mysql->is_error;

`query(SQL_STRING)`
  A `query()` method transmits the specified SQL string to MySQL database, and obtains the response.

`create_record_iterator()`
  When SELECT type SQL is specified, Net::MySQL::RecordIterator object which shows the reference result is returned.

          $mysql->query(q{SELECT * FROM table});
          my $a_record_iterator = $mysql->create_recrod_iterator();

  Net::MySQL::RecordIterator object is applicable to acquisition of a reference result. See /Net::SQL::RecordIterator API for more.

`get_affected_rows_length()`
  returns the number of records finally influenced by specified SQL.

          my $affected_rows = $mysql->get_affected_rows_length;

`get_insert_id()`
  MySQL has the ability to choose unique key values automatically. If this happened, the new ID will be stored in this attribute.

`is_error()`
  TRUE will be returned if the error has occurred.

`has_selected_record()`
  TRUE will be returned if it has a reference result by SELECT.

`get_field_length()`
  return the number of column.

`get_field_names()`
  return column names by ARRAY.

`close()`
  transmits an end message to MySQL daemon, and closes a socket.

## Net::MySQL::RecordIterator API

Net::MySQL::RecordIterator object is generated by the `query()` method of Net::MySQL object. Thus it has no public constructor method.

`each()`
  `each()` method takes out only one line from a result, and returns it as an ARRAY reference. `undef` is returned when all the lines has been taken out.

          while (my $record = $a_record_iterator->each) {
              printf "Column 1: %s Column 2: %s Collumn 3: %s\n",
                  $record->[0], $record->[1], $record->[2];
          }

# SUPPORT OPERATING SYSTEM

This module has been tested on these OSes.

- MacOS 9.x
with MacPerl5.6.1r.

- MacOS X
with perl5.6.0 build for darwin.

- Windows2000
with ActivePerl5.6.1 build631.

- FreeBSD 3.4 and 4.x
with perl5.6.1 build for i386-freebsd.

with perl5.005_03 build for i386-freebsd.

- Linux
with perl 5.005_03 built for ppc-linux.

with perl 5.6.0 bult for i386-linux.

- Solaris 2.6 (SPARC)
with perl 5.6.1 built for sun4-solaris.

with perl 5.004_04 built for sun4-solaris.

Can use on Solaris2.6 with perl5.004_04, although make test is failure.

This list is the environment which I can use by the test usually. Net::MySQL will operate also in much environment which is not in a list.

I believe this module can work with whatever perls which has IO::Socket. I'll be glad if you give me a report of successful installation of this module on rare OSes.

# SEE ALSO

libmysql, the IO::Socket manpage

# AUTHOR

Hiroyuki OYAMA <oyama@module.jp>

# COPYRIGHT AND LICENCE

Copyright (C) 2002 Hiroyuki OYAMA. Japan. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Net::MySQL - Pure Perl MySQL network protocol interface.