NAME
SQL::Script - An object representing a series of SQL statements,
normally stored in a file
PREAMBLE
For far too long we have been throwing SQL scripts at standalone binary
clients, it's about time we had some way to throw them at the DBI
instead.
Since I'm sick and tired of waiting for someone that knows more about
SQL than me to do it properly, I shall implement it myself, and wait for
said people to send me patches to fix anything I do wrong.
At least this way I know the API will be done in a usable way.
DESCRIPTION
This module provides a very simple and straight forward way to work with
a file or string that contains a series of SQL statements.
In essense, all this module really does is slurp in a file and split it
by semi-colon+newline.
However, by providing an initial data object and API for this function,
my hope is that as more people use this module, better mechanisms can be
implemented underneath the same API at a later date to read and split
the script in a more thorough and complete way.
It may well become the case that SQL::Script acts as a front end for a
whole quite of format-specific SQL splitters.
METHODS
new
# Default naive split
$script = SQL::Script->new;
# Custom split (string)
$script = SQL::Script->new( split_by => "\n\n;" );
# Custom split (regexp)
$script = SQL::Script->new( split_by => qr/\n\n;/ );
# Create a script object from pre-split statements
$script = SQL::Script->new( statements => \@sql );
The "new" constructor create a new SQL script object, containing zero
statements.
It takes a single option param or "split_by" which can be either a
string or regexp by which to split the SQL.
Returns a new SQL::String object, or throws an exception on error.
read
# Read a SQL script from one of several sources
$script->read( 'filename.sql' );
$script->read( \$sql_string );
$script->read( $io_handle );
The "read" method is used to read SQL from an input source (which can be
provided as either a file name, a reference to a SCALAR containing the
SQL, or as an IO handle) and split it into a set of statements.
If the SQL::Script object already contains a set of statements, they
will be overwritten and replaced.
Returns true on success, or throw an exception on error.
split_by
The "split_by" accessor returns the string or regexp that will be used
to split the SQL into statements.
statements
In list context, the "statements" method returns a list of all the
individual statements for the script.
In scalar context, it returns the number of statements.
split_sql
The "split_sql" method takes a reference to a SCALAR containing a string
of SQL statements, and splits it into the separate statements, returning
them as a reference to an ARRAY, or throwing an exception on error.
This method does NOT update the internal state, it simply applies the
appropriate parsing rules.
run
The "run" method executes the SQL statements in the script object.
Returns true if ALL queries are executed successfully, or "undef" on
error.
(These return values may be changed in future, probably to a style where
all the successfully executed queries are returned, and the object
throws an exception on error)
SUPPORT
Bugs should be reported via the CPAN bug tracker at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL-Script>
For other issues, contact the author.
AUTHOR
Adam Kennedy <
[email protected]>
COPYRIGHT
Copyright 2007 - 2009 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
