/ 
Net-MySQL-0.04
River stage one • 2 direct dependents • 2 total dependents
/ Net::MySQL

NAME

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

SYNOPSIS

use Net::MySQL;

my $mysql = Net::MySQL->new(
    hostname => 'mysql.example.jp',
    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 protool 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(
    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:

hostname

Name of the host where MySQL daemon runs.

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"" in " 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_fiend_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.

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

SEE ALSO

libmysql, IO::Socket::INET, Math::BigInt

AUTHOR

Hiroyuki OYAMA <oyama@crayfish.co.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.