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 <adamk@cpan.org>
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.