NAME

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

SYNOPSIS

my $modwheel = Modwheel->new($modwheel_config);
my $db = Modwheel::DB->new({
    modwheel => $modwheel;
});

$db->connect || die $modwheel->error;

# [...]

$db->disconnect;

DESCRIPTION

PURPOSE

Modwheel::DB automaticly chooses the database driver you specify in the configuration, you don't use this class directly.

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 strict;
 use warnings;
 use base qw( Modwheel::DB::Base );
 use version; $VERSION = qv('0.0.1');
 use Class::InsideOut::Policy::Modwheel qw(:std);
 use Acme::Bee::Bumblebee qw();
 {

     # 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

SUBROUTINES/METHODS

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.

$db->create_dsn()

Inherited drivers must define this function to create the database configuration.

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(int $bool_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.

INHERITANCE

This class inherits from Modwheel::Instance.

DIAGNOSTICS

None.

CONFIGURATION AND ENVIRONMENT

See Modwheel::Manual::Config

DEPENDENCIES

DBI
Params::Util
version

INCOMPATIBILITIES

None known.

BUGS AND LIMITATIONS

None known.

VERSION

v0.3.3

AUTHOR

Ask Solem, ask@0x61736b.net.

LICENSE AND COPYRIGHT

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.

To install Modwheel, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Modwheel

CPAN shell

perl -MCPAN -e shell
install Modwheel

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

PURPOSE

HOW TO SUBCLASS

SUBROUTINES/METHODS

INSTANCE METHODS

PRIVATE METHODS

INHERITANCE

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

VERSION

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions