Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Safe(3)		      User Contributed Perl Documentation	       Safe(3)

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

       This documents version 1.2.5 of the DBIx::Safe module

	 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');

       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.


       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".


       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.


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


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


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


       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.


       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.


       Same as allow_attributes, but removes attributes	from the list.

       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

   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).

       The latest version and other information	about DBIx::Safe can be	found

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

	 git clone

       Bugs should be reported to the author or

       Greg Sabino Mullane <>

       Copyright 2006-2007 Greg	Sabino Mullane <>.

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

perl v5.32.1			  2007-10-15			       Safe(3)


Want to link to this manual page? Use this URL:

home | help