NAME

       DBIx::Safe - Safer access to your database through a DBI database handle

VERSION

       This documents version 1.2.5 of the DBIx::Safe module

SYNOPSIS

         use DBIx::Safe;

         $dbh = DBI->connect($dbn, $user, $pass, {AutoCommit => 0});

         my $safedbh = DBIx::Safe->new({ dbh => $dbh });

         $safedbh->allow_command('SELECT INSERT UPDATE');

         $safedbh->allow_regex(qr{LOCK TABLE \w+ IN EXCLUSIVE MODE});

         $safedbh->deny_regex(qr{LOCK TABLE pg_});

         $safedbh->allow_attribute('PrintError RaiseError');

DESCRIPTION

       The purpose of this module is to give controlled, limited access to an application, rather
       than simply passing it a raw database handle through DBI. DBIx::Safe acts as a wrapper to
       the database, by only allowing through the commands you tell it to. It filters all things
       related to the database handle - methods and attributes.

       The typical usage is for your application to create a database handle via a normal DBI
       call to new(), then pass that to DBIx::Safe->new(), which will return you a DBIx::Safe
       object. After specifying exactly what is and what is not allowed, you can pass the object
       to the untrusted application. The object will act very similar to a DBI database handle,
       and in most cases can be used interchangeably.

       By default, nothing is allowed to run at all. There are many things you can control.  You
       can specify which SQL commands are allowed, by indicating the first word in the SQL
       statement (e.g. 'SELECT'). You can specify which database methods are allowed to run (e.g.
       'ping'). You can specify a regular expression that allows matching SQL statements to run
       (e.g. 'qr{SET TIMEZONE}'). You can specify a regular expression that is NOT allowed to run
       (e.g. qr(UPDATE xxx}). Finally, you can indicate which database attributes are allowed to
       be read and changed (e.g. 'PrintError'). For all of the above, there are matching methods
       to remove them as well.

   Deciding what statements to allow
       Anytime a statement is sent to the server via the DBIx::Safe database handle, it is first
       examined to see if it is allowed to run or not. There are three major checks that occur
       when a statement is sent. First, the initial word of the statement, known as the command,
       is extracted. Next, the entire statement is checked against the list of denied regular
       expressions.  Next, the command is checked against the list of allowed commands. If there
       is no match, the statement is checked against the list of allowed regular expressions.

       Each DBD may implement additional or slightly different checks. For example, if using
       Postgres, no semi-colons are allowed unless the command is one of SELECT, INSERT, UPDATE,
       or DELETE, to prevent multiple commands from running. (The four listed commands can be
       checked in another way for multiple commands, so they are allowed to have semicolons).

   Deciding what attributes to allow
       Database handle attributes are controlled by a single list of allowed keys. If the key is
       allowed, the underlying database handle value is returned or changed (or both).  Note that
       the attribute "AutoCommit" is never allowed to be changed.

   Methods
       new()

       Creates a new DBIx::Safe object. Requires a mandatory "dbh" argument containing an active
       database handle. Optional arguments are "allow_command", "allow_regex", "deny_regex", and
       "allow_attribute".

       allow_command()

       Specifies which commands are allowed to be used. Can be a whitespace-separated list of
       words in a string, or an arrayref of such strings. Returns the current list of allowed
       commands. Duplicate commands will throw an error.

       unallow_command()

       Same as allow_command, but will remove words from the list.

       allow_regex()

       Specifies regular expressions which are allowed to run. Argument must be a regular
       expression, or an arrayref of regular expressions. Returns the current list.

       unallow_regex()

       Same as allow_regex, but will remove regexes from the list.

       deny_regex()

       Specifies regular expressions which are NOT allowed to run. Arguments and return the same
       as allow_regex().

       undeny regex()

       Same as deny_regex, but will remove regexes from the list.

       allow_attribute()

       Specifies database handle attributes that are allowed to be changed. By default, nothing
       can be read.  Argument is a whitespace-separated list of words in a string, or an arrayref
       of such strings. Returns the current list.

       unallow_attribute()

       Same as allow_attributes, but removes attributes from the list.

   Testing
       DBIx::Safe has a very comprehensive test suite, so please use it! The only thing you
       should need is a database connection, by setting the environment variables DBI_DSN and
       DBI_USER (and DBI_PASS if needed).

       You can optionally run the module through Perl::Critic by setting the TEST_AUTHOR
       environment variable.  You will need to have the modules Perl::Critic and
       Test::Perl::Critic installed.

       Please report any test failures to the author or bucardo-general@bucardo.org.

   Supported Databases
       Due to the difficulty of ensuring safe access to the database, each type of database must
       be specifically written into DBIx::Safe. Current databases supported are: Postgres
       (DBD::Pg).

WEBSITE

       The latest version and other information about DBIx::Safe can be found at:
       http://bucardo.org/dbix_safe/

DEVELOPMENT

       The latest development version can be checked out by using git:

         git clone http://bucardo.org/dbixsafe.git/

BUGS

       Bugs should be reported to the author or bucardo-general@bucardo.org.

AUTHOR

       Greg Sabino Mullane <greg@endpoint.com>

LICENSE AND COPYRIGHT

       Copyright 2006-2007 Greg Sabino Mullane <greg@endpoint.com>.

       This software is free to use: see the LICENSE file for details.