NAME

Mysql::Admin -- shorthands for MySQL database administration and connections


SYNOPSIS

   use DBI;
   use Mysql::Admin qw(dbi_connect);
   $db = DBI->connect(dbi_connect($dbdir), "", "");
   $db = DBI->connect(dbi_connect($dbdir, $hostname, $dbname),
                      $login, $passwd);
   # or
   use Mysql;
   use Mysql::Admin qw(setenv);
   setenv($dbdir); $db = Mysql->connect($hostname);
   ($socket, $port) = setenv($dbdir);
   # or
   use Mysql::Admin qw(start stop reload);
   start($dbdir);
   stop($dbdir);
   reload($dbdir);


DESCRIPTION

Mysql::Admin provides some shorthands for connecting to a MySQL data base (either by DBI or Mysql) and for administrative operations. All these shorthands share the assumption that the directory of the MySQL database contains a file named setenv (format see below) with the connection parameters.

Usually, setenv will be created by our MySQL installation procedure (reference is below) that allows to run any number of MySQL daemons on one system without disturbing each other by using non-standard locations and non-standard port numbers.

Instead of passing a bunch of parameters the operations of this module allow to specify your database just be the name of the directory it is contained in. This is the mysql subdirectory of the directory created earlier by our installation procedure.

Following operations are supported:

dbi_connect
returns a string ready for the first parameter of the DBI->connect operation. Note that dbi_connect has a side effect by setting the environment parameters (see below). If the UNIX domain socket of your MySQL is the only way to connect to it, DBI->connect will not succeed unless MYSQL_UNIX_PORT has been set by dbi_connect or setenv. This is a restriction due to the limited support of the DBD driver module for MySQL.

setenv
sets the environment parameters for MySQL in dependence of the file setenv in $dbdir. setenv returns a tuple consisting of the socket (path name), and the port number.

start
starts the database daemon mysqld for $dbdir.

stop
shuts the database daemon mysqld for $dbdir.

reload
reloads the database of $dbdir.


DIAGNOSTICS

MySQL::Admin aborts with following messages to Carp::croak in case of fatal errors:

``MYSQL_TCP_PORT parameter in %s missing''
Generated by setenv if MYSQL_TCP_PORT is missing in setenv.

``MYSQL_UNIX_PORT parameter in %s missing''
Issued by setenv if MYSQL_UNIX_PORT is missing in setenv.

``no databases found in %s''
This error is fired by dbi_connect if no database name was given and no database (beside the administrative database named mysql) was found in $dbdir.

``unable to fork''
start, stop, or reload was unable to spawn a subprocess.

``unable to open %s''
setenv generates this error message if the file setenv under $dbdir cannot be opened.


ENVIRONMENT

setenv sets following environment parameters for MySQL:

MYSQL_UNIX_PORT
Path name of the UNIX domain socket of the database.

MYSQL_TCP_PORT
TCP/IP port number of the data base.


FILES

/usr/local/mysql-scripts
Directory containing some tools for maintaining a MySQL data base including an installation procedure installdb. Example:
   /usr/local/mysql-scripts/installdb/ /some/where/db

logfile (below $dbdir)
Log file used by mysqld.

setenv (below $dbdir)
File created by createdb that stores the environment parameters for MySQL. It contains the settings for MYSQL_UNIX_PORT and MYSQL_TCP_PORT. Example ($dbdir is assumed to be /some/where/db/mysql):
   MYSQL_UNIX_PORT=/some/where/db/mysql/socket
   MYSQL_TCP_PORT=17169

socket (below $dbdir)
UNIX domain socket of the MySQL daemon.

mysql (below $dbdir)
Administrative database of MySQL.

/usr/local/mysql
Directory containing the MySQL software package.

/usr/local/mysql/mysqld
Binary of the MySQL daemon, invoked by start.

/usr/local/mysql/mysqladmin
reload and stop are passed to this command.


SEE ALSO

createdb
Creates a new database. This tool is installed by the installation procedure and lives in the bin sub directory (see above). More about createdb may be found at:

Installation Procedure for MySQL
We have setup a page that shows how to start your own MySQL daemon.


AUTHOR

Andreas Borchert


BUGS

This module assumes that MySQL has been installed under /usr/local/mysql.

Connections to different MySQL databases in parallel could be troublesome because of the use of environment variables for passing the connection parameters. This is not a bug of this module but of MySQL.