The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SQL-Script-1.06
River stage one • 4 direct dependents • 4 total dependents
4 ++
/ SQL::Script

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.