<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Mail::Toaster::Mysql</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:_netbios@teneight-slave.macports.org" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#subroutines">SUBROUTINES</a></li>
<li><a href="#dependencies">DEPENDENCIES</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#todo">TODO</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Mail::Toaster::Mysql - so much more than just installing mysql</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>Functions for installing, starting, stopping, querying, and otherwise interacting with MySQL.</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>I find myself using MySQL for a lot of things. Geographically distributed dns systems (MySQL replication), mail servers, and all the other fun stuff you'd use a RDBMS for. As such, I've got a growing pile of scripts that have lots of duplicated code in them. As such, the need for this perl module grew.</p>
<pre>
Currently used in:
mysql_replicate_manager v1.5+
uron.net user_*.pl
polls.pl
nt_export_djb_update.pl
toaster_setup.pl</pre>
<p>
</p>
<hr />
<h1><a name="subroutines">SUBROUTINES</a></h1>
<dl>
<dt><strong><a name="new" class="item">new</a></strong></dt>
<dd>
<pre>
use Mail::Toaster::Mysql;
my $mysql = Mail::Toaster::Mysql->new();</pre>
</dd>
<dt><strong><a name="autocommit" class="item">autocommit</a></strong></dt>
<dt><strong><a name="backup" class="item">backup</a></strong></dt>
<dd>
<p>Back up your mysql databases</p>
<pre>
$mysql->backup( $dot );</pre>
<p>The default location for backups is /var/backups/mysql. If you want them stored elsewhere, set backupdir = /path/to/backups in your .my.cnf (as shown in the FAQ) or pass it via -d on the command line.</p>
<p>You will need to have cronolog, gzip, and mysqldump installed in a "normal" location. Your backups will be stored in a directory based on the date, such as /var/backups/mysql/2003/09/11/mysql_full_dump.gz. Make sure that path is configured to be backed up by your backup software.</p>
<pre>
arguments required:
dot - a hashref of values from a .my.cnf file</pre>
</dd>
<dt><strong><a name="connect" class="item">connect</a></strong></dt>
<dd>
<pre>
my ($dbh, $dsn, $drh) = $mysql->connect($dot, $warn, $verbose);</pre>
<p>$dot is a hashref of key/value pairs in the same format you'd find in ~/.my.cnf. Not coincidentally, that's where it expects you'll be getting them from.</p>
<p>$warn allows you to determine whether to die or warn on failure or error. To warn, set $warn to a non-zero value.</p>
<p>$verbose will print out helpful messages should you be having problems.</p>
</dd>
<dt><strong><a name="db_vars" class="item">db_vars</a></strong></dt>
<dd>
<p>This sub is called internally by $mysql->connect and is used principally to set some reasonable defaults should you not pass along enough connection parameters in $dot.</p>
</dd>
<dt><strong><a name="flush_logs" class="item">flush_logs</a></strong></dt>
<dd>
<pre>
$mysql->flush_logs($dbh, $verbose)</pre>
<p>runs the mysql "FLUSH LOGS" query on the server. This commits any pending (memory cached writes) to disk.</p>
</dd>
<dt><strong><a name="get_hashes" class="item">get_hashes</a></strong></dt>
<dd>
<p>Gets results from a mysql query as an array of hashes</p>
<pre>
my @r = $mysql->get_hashes($dbh, $sql);</pre>
<p>$dbh is a database handle</p>
<p>$sql is query</p>
</dd>
<dt><strong><a name="install" class="item">install</a></strong></dt>
<dd>
<p>Installs MySQL</p>
</dd>
<dt><strong><a name="is_newer" class="item">is_newer</a></strong></dt>
<dd>
<pre>
my $ver = $mysql->version($dbh);
my $newer = $mysql->is_newer("4.1.0", $ver);</pre>
<p>if ($newer) { print "you are brave!" };</p>
<p>As you can see, is_newer can be very useful, especially when you need to execute queries with syntax differences between versions of Mysql.</p>
</dd>
<dt><strong><a name="parse_dot_file" class="item">parse_dot_file</a></strong></dt>
<dd>
<pre>
$mysql->parse_dot_file ($file, $start, $verbose)</pre>
<p>Example:</p>
<pre>
my $dot = $mysql->parse_dot_file(".my.cnf", "[mysql_replicate_manager]", 0);</pre>
<pre>
$file is the file to be parsed.</pre>
<p>$start is the [identifier] where we begin looking for settings. This expects the format used in .my.cnf MySQL configuration files.</p>
<p>A hashref is returned wih key value pairs</p>
</dd>
<dt><strong><a name="phpmyadmin_install" class="item">phpmyadmin_install</a></strong></dt>
<dd>
<p>Install PhpMyAdmin from FreeBSD ports.</p>
<pre>
$mysql->phpmyadmin_install;</pre>
</dd>
<dt><strong><a name="query" class="item">query</a></strong></dt>
<dd>
<pre>
my $sth = $mysql->query ($dbh, $query, $warn)</pre>
<p>$dbh is the database handle you've already acquired via $mysql->connect.</p>
<p>$query is the SQL statement to execute.</p>
<p>If $warn is set, we don't die if the query fails. This way you can decide when you call the sub whether you want it to die or return a failed $sth (and likely an error message).</p>
<pre>
execute performs whats necessary to execute a statement
Always returns true regardless of # of rows affected.
For non-Select, returns # of rows affected: No rows = 0E0
For Select, simply starts query. Follow with fetch_*</pre>
</dd>
<dt><strong><a name="query_confirm" class="item">query_confirm</a></strong></dt>
<dd>
<pre>
$mysql->query_confirm($dbh, $query );</pre>
<p>Use this if you want to interactively get user confirmation before executing a query.</p>
</dd>
<dt><strong><a name="sanity" class="item">sanity</a></strong></dt>
<dd>
<p>A place to do validation tests on values to make sure they are reasonable</p>
<p>Currently we only check to assure the password is less than 32 characters and the username is less than 16. More tests will come.</p>
</dd>
<dt><strong><a name="shutdown_mysqld" class="item">shutdown_mysqld</a></strong></dt>
<dd>
<p>Shuts down mysql using a $drh handle.</p>
<pre>
my $rc = $mysql->shutdown_mysqld($dbvs, $drh);</pre>
<p>$dbvs is a hashref containing: host, user, pass</p>
<p>returns error_code 200 on success, 500 on error. See error_desc for details.</p>
</dd>
<dt><strong><a name="tables_lock" class="item">tables_lock</a></strong></dt>
<dd>
<pre>
my $sth = $mysql->tables_lock($dbh );
# do some mysql stuff
$mysql->tables_unlock($dbh, $sth);</pre>
<p>Takes a statement handle and does a global lock on all tables. Quite useful when you want do do things like make a tarball of the database directory, back up the server, etc.</p>
</dd>
<dt><strong><a name="tables_unlock" class="item">tables_unlock</a></strong></dt>
<dd>
<pre>
$mysql->tables_unlock($dbh, $sth );</pre>
<p>Takes a statement handle and does a global unlock on all tables. Quite useful after you've used $mysql->tables_lock, done your deeds and wish to release your lock.</p>
</dd>
<dt><strong><a name="status" class="item">status</a></strong></dt>
<dt><strong><a name="version" class="item">version</a></strong></dt>
<dd>
<pre>
my $ver = $mysql->version($dbh);</pre>
<p>Returns a string representing the version of MySQL running.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="dependencies">DEPENDENCIES</a></h1>
<pre>
DBI.pm - /usr/ports/databases/p5-DBI
DBD::mysql - /usr/ports/databases/p5-DBD-mysql</pre>
<p>In order to use this module, you must have DBI.pm and DBD::Mysql installed. If they are not installed and you attempt to use this module, you should get some helpful error messages telling you how to install them.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Matt Simerson <<a href="mailto:matt@tnpi.net">matt@tnpi.net</a>></p>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>None known. Report any to author.</p>
<p>
</p>
<hr />
<h1><a name="todo">TODO</a></h1>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>The following are all man/perldoc pages:</p>
<pre>
Mail::Toaster
Mail::Toaster::Conf
toaster.conf
toaster-watcher.conf</pre>
<pre>
<a href="http://www.mail-toaster.com/">http://www.mail-toaster.com/</a></pre>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 2003-2012, The Network People, Inc. All Rights Reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<p>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</p>
<p>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</p>
<p>Neither the name of the The Network People, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.</p>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</body>
</html>