MySQL::Easy - Perl extension to handle various mundane DBI session related things specific to mysql.

NAME

MySQL::Easy - Perl extension to handle various mundane DBI session related things specific to mysql.

SYNOPSIS

  use MySQL::Easy;

  my $trace = 0; # the trace arg is optional
  my $dbo = new MySQL::Easy("stocks", $trace);

  #  This is NEW (and totally untested):
  #  $dbo = new MySQL::Easy($existing_DBI_dbh, $trace);

  my $symbols = $dbo->firstcol(
      qq( select symbol from ohlcv where symbol != ?),
      "msft"
  );

  my $q = $dbo->ready("select * from ohlcv where symbol=?");
  for my $s (@$symbols) {
      my @a;

      $q->execute($s) or die $dbo->errstr;
      # Although the regular DBI will reconnect to the server when it loses
      # it's connection, any queries you had previously prepared will fail
      # until it reconnects.  easy::mysql handles all that for you so this
      # execute() will always work, if it's syntactically correct, even if
      # your server connection was lost since the last ready();

      print "@a" while @a = fetchrow_array $q;
  }

DESCRIPTION

   I don't remember how I used to live without this...
   I do like the way DBI and DBD work, but I wanted something
   _slightly_ prettier... _slightly_ handier.

   Here's the functions MySQL::Easy provides:

   $dbo = new MySQL::Easy( $db_name, $trace );
       # $db_name is the name of the database you're connecting to...
       # If you don't pick anything, it'll pick "test" for you.
       # $trace is a 1 or false, ... it's the DBI->trace() ...

   $dbo->do("sql statement bind=? bind=?", $bind1, $bind2);
       # this immediately executes the sql with the bind vars
       # given.  You can pas in a statement handle
       # instead of the string... this is faster if you're going
       # to use the sql over and over.  Returns a t/f like you'd
       # expect.  (i.e. $dbo->do("stuff") or die $dbo->errstr);

   $dbo->lock("table1", "table2", "table3");
       # MySQL::Easy uses only write locks.  Those are the ones
       # where nobody can read or write to the table except the
       # locking thread.  If you need a read lock, let Jet know.
       # Most probably though, if you're using this, it's a
       # smaller app, and it doesn't matter anyway.
   $dbo->unlock;

   $sth = $dbo->ready("Sql Sql Sql=? and Sql=?");
       # returns a DBI statement handle...
       # $sth->execute($bindvar); $sth->fetchrow_hashref; etc...

   $arr = $dbo->firstcol("select col from tab where x=? and y=?", $x, $y)
       # returns an arrayref of values for the sql.
       # You know, print "val: $_\n" for @$arr;
       # very handy...

   $id = $dbo->last_insert_id;
       # self explainatory?

   $dbo->trace(1); $dbo->do("sql"); $dbo->trace(0);
       # turns the DBI trace on and off.

   $dbo->errstr
       # returns an error string for the last error on the
       # thread...  Same as a $sth->errstr.  It's actually
       # described in DBI

   $dbo->check_warnings
       # I'll just give this example:
       $dbo->do("create temporary table cool( field enum('test1', 'test2') not null )");
       $dbo->do("insert into cool set field='test3'");
       $dbo->check_warnings 
           or die "SQL WARNING: $@\twhile inserting test field\n\t";

   $dbo->set_host($h); $dbo->set_port($p); 
   $dbo->set_user($U); $dbo->set_pass($p);
       # The first time you do a do/ready/firstcol/etc,
       # MySQL::Easy connects to the database.  You may use these
       # set functions to override values found in your ~/.my.cnf
       # for user and pass.  MySQL::Easy reads _only_ the user
       # and pass from that file.  The host name will default to
       # "localhost" unless explicitly set.  Also, it will die on
       # a fatal error if the user or pass is false and the
       # ~/.my.cnf cannot be opened.

   my $table;
   my $sth = $dbo->bind_execute("show tables", \( $table ) );
       # This was Josh's idea... And a good one.

   die $dbo->errstr unless $sth;  
       # bind_execute returns undef if either the bind
       # or execute phases fail.

   print "$table\n" while fetch $sth;

   # Anything from the DBI.pm manpage will work with the
   # $dbo (thanks to an AUTOLOAD function).

AUTHOR

Paul Miller <jettero@cpan.org>

I am using this software in my own projects... If you find bugs, please please please let me know. :)

Actually, let me know if you find it handy at all. Half the fun of releasing this stuff is knowing that people use it.

THANKS

For bugs and ideas: Josh Rabinowitz <joshr-cpan@joshr.com>

COPYRIGHT

GPL! I included a gpl.txt for your reading enjoyment.

Though, additionally, I will say that I'll be tickled if you were to include this package in any commercial endeavor. Also, any thoughts to the effect that using this module will somehow make your commercial package GPL should be washed away.

I hereby release you from any such silly conditions.