/ 
Modwheel-0.3.1a
/ Modwheel::DB::Base

NAME

Modwheel::DB::Base - Generic Modwheel database class.

ABSTRACT

This class defines the Modwheel::DB interface and also defines default methods that other database classes can override.

Usually all Modwheel database classes inherits this class.

You can also see the documentation for these classes:

HOW TO SUBCLASS

To create your own class, say Modwheel::DB::Weird, that inherits all methods from Modwheel::DB::Base and overrides the fetch_next_id() method, you can do something like this:

   package Modwheel::DB::Weird;
   use base qw( Modwheel::DB::Base );
 use version; $VERSION = qv('0.0.1');
 use Acme::Bee::Bumblebee qw();
 use strict;

 # this driver requires module Acme::Bee::Bumblebee to be installed.
 sub driver_requires {
     return [qw( Acme::Bee::Bumblebee )]; 
 }

 sub fetch_next_id {
     my($self, $table, $optional_primary_key_name) = @_;
     my $new_id = $self->SUPER::fetch_next_id(@_);

     # be sure that this id is not taken by any bumblebees!
     while (Acme::Bee::Bumblebee->has_bee($new_id)) {
         $new_id = $self->SUPER::fetch_next_id(@_);
     }

     return $new_id;
 }
 
 1; # Magic true return value.

And then in your configuration file:

Site:
  RalphsWonderfulWorldOfBees:
    database:
      name: bees
      type: Weird
      username: ralph
      password: definityinfinity

INHERITANCE

This class inherits from Modwheel::Instance.

EXPORT

None.

INSTANCE METHODS

$db->connect()

Connect to the database.

Uses the database configuration of the current site to connect to the database. If a connection was established this function sets $db->connected to 1 and returns 1. Otherwise it sets $db->errstr to contain a description of the error and returns undef.

$db->driver_requires()

Returns a list of perl modules required for this driver to work.

$db->disconnect()

Disconnect from the database.

Sets $db->connected to 0 and disconnects from the database if a connection is open.

$db->autocommit($bool_autocommit)

If this is set, the database will automatically commit database transations.

$db->commit()

When autocommit is off, this method will commit the current database transation.

$db->rollback()

When autocommit is off, this method can be used to rollback all changes since the start of the current transaction.

$db->errstr()

Holds a description of the last error that occured.

$db->PrintError($bool_print_error)

If this is set, the database driver will print the contents of $db->errstr when any error occurs. This option is on by default.

$db->RaiseError($bool_raise_error)

If this is set, the database driver will print the contents of $db->errstr and _exit_ the running program when any error occurs. This option is off by default.

$db->trace($trace_level)

If this is set, the database driver will print verbose debugging information for any database action. This option is off by default.

$db->connected>

Will return true if we have a open database connection, false if not. Note however that we can't trust the output of this method.

$db->prepare($query)

Prepare a query for execution.

Example:

# Select all objects that has root as parent.
my $query = $db->build_select_q('object', '*', {parent => 1});

# Prepare and execute the query.
my $sth = $db->prepare($query);
$db->execute($sth);

# iterate over the results.
while (my $hres = $db->fetch_hashref($sth)) {
    print $hres->{name}
}
# always remember to end a prepared query:
$db->query_end($sth);
$db->execute($sth, @bind_variables)

Execute a prepared query. If you have a query with bind variables, attach them to this methods arguments.

Example:

# select objects by id. the '?' means that we want to bind the variable later.
my $query = $db->build_select_q('object', '*', {id => '?'});

# prepare and execute the query using bind variables:
my $id_to_fetch = 2;
my $sth = $db->prepare($query);
$db->execute($sth, $id_to_fetch);

[ ... work on the result ... ]

$db->query_end($sth);
$db->query($query)

Shortcut function for both prepare() and execute(). Returns back the query handle if everything went ok. NOTE: Remember to use $db->query_end($sth) when finished using this handle.

$db->query_end($sth)

End a query started by prepare() or query().

$db->fetchrow_array($sth)

Returns an array reference to the data returned by the current query.

$db->fetchrow_hash($sth)

Returns a hash reference to the data returned by the current query.

$db->fetchonerow_array($query, @bind_varuables)

Returns a arrayref to the data in the first row returned by query. It's a shortcut for writing:

my $query = "[...]";
my $sth   = $db->prepare($query);
$sth->execute($query, @bind_variables);
my $arrayref = $db->fetchrow_array($sth);
$db->query_end($sth);
$db->fetchonerow_hash($query, @bind_variables)

Same as fetchonerow_array but returns a hash reference instead.

$db->fetch_singlevar($query)

Return the first element from the first row of a query.

$db->exec_query($query)

If you have a query that just executes a command but does not fetch anything, this is the ideal function to use. RETURNS: the number of rows affected by the query.

$db->current_timestamp()

Get the current timestamp from the database as a string.

$db->fetch_next_id($table, $optional_primary_key_name)

Return the next available id from a table.

$db->build_insert_q($from_table, %$fields)

Build a insert query.

Arguments:

from_table

The table to insert data to.

%$fields

Fields to insert, this list must be sorted alphabetically so we can map the bind variables in order.

$db->build_update_q($from_table, %$fields, %$where)

Build a update query.

Arguments:

from_table

The table to update data in.

%$fields

Fields to update,

%$where

Only update fields matching i.e {parent => '?', active => 1} this list must be sorted alphabetically so we can map the bind variables in order.

$db->build_select_q($from_table, %$fields, %$options)

Build a select query.

Arguments:

from_table

The table to select data from.

%$fields

Fields to select.

%$where

Only select fields matching i.e {parent => '?', active => 1} this list must be sorted alphabetically so we can map the bind variables in order.

%$options

The following options are available:

order

which field(s) to order by. i.e ( {order => 'name,id DESC'} )

limit

limit the number of matches. i.e ( {limit => 10 } ).

offset

skip the n first numbers.

$db->build_delete_q($from_table, %$fields, %$options)

Build a delete query.

Arguments:

from_table

The table to delete data from.

%$fields

Fields to select.

%$where

Only delete fields matching i.e {parent => '?', active => 1} this list must be sorted alphabetically so we can map the bind variables in order.

%$options

The following options are available:

limit

limit the number of rows to delete. i.e ( {limit => 10 } ).

offset

skip the n first rows.

$db->quote($string)

Quote characters in a string that will interfere in our database operations.

$db->sqlescape($string)

Quote characters in a string that will interfere in our database operations.

$db->trim($string)

Remove leading and trailing whitespace from a string.

$db->maintainance()

Perform database maintainance.

PRIVATE METHODS

These are methods to be used internally in _this class or a sub-class only_ never used them from the outside world.

$db->_set_connected

Private: Set the current connection status.

$db->dbh()

Private: Access the current database handler object.

$db->_set_dbh($dbh)

Private: Sets the current database handler object.

$db->_build_q()

Private helper function for the build_*_q functions.

$db->_build_where_clause

Private helper function for the build_*_q functions.

HISTORY

0.01

Initial version.

SEE ALSO

The README included in the Modwheel distribution.

The Modwheel website: http://www.0x61736b.net/Modwheel/

AUTHORS

Ask Solem, ask@0x61736b.net.

COPYRIGHT, LICENSE

Copyright (C) 2007 by Ask Solem ask@0x61736b.net.

All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.