/ 
Net-MySQL-0.11
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',   # 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_record_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_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];
}

SEE ALSO

libmysql, IO::Socket

AUTHOR

Hiroyuki OYAMA <oyama@module.jp>

MAINTAINER

Takuya Tsuchida <tsucchi at cpan.org>

REPOSITORY

http://github.com/tsucchi/p5-Net-MySQL

COPYRIGHT AND LICENCE

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

Copyright (C) 2011 Takuya Tsuchida

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