/ 
SQL-Biblosoph-1.2
/ SQL::Bibliosoph

NAME

SQL::Bibliosoph - A SQL Statements Library

VERSION

1.0

SYNOPSIS

use SQL::Bibliosoph;

my $bs = SQL::Biblioshoph->new(
		dsn		 => $database_handle,
		catalog => [ qw(users products <billing) ],
);

# Using dynamic generated functions.  Wrapper funtions 
# are automaticaly created on module initialization.
# Query should something like:

# --[ get_products ]
#  SELECT id,name FROM  product WHERE country = ?

my $products_ref = $bs->get_products($country);

# Forcing numbers in parameters
# Query:

# --[ get_products ]
#  SELECT id,name FROM  product WHERE country = ? LIMIT #?,#?


# Parameter ordering and repeating
# Query:

# --[ get_products ]
#  SELECT id,name 
#  		FROM  product 
#  		WHERE 1? IS NULL OR country = 1? 
#  		 AND  price > 2? * 0.9 AND print > 2? * 1.1
#  		LIMIT #3?,#4?

my $products_ref = $bs->get_products($country,$price,$start,$limit);


# Selecting only one row (add row_ at the begining)
# Query:

# --[ get_one ]
#  SELECT name,age FROM  person where id = ?;

my $product_ref = $bs->row_get_one($product_id);

# Selecting only one value (same query as above)

my $product_name = $bs->row_get_one($product_id)->[1];

# Inserting a row, with an auto_increment PK.
# Query:

# --[ insert_person ]
#  INSERT INTO person (name,age) VALUES (?,?);

my $last_insert_id = $bs->insert_person($name,$age);


# Updating some rows
# Query:

# --[ age_persons ]
#  UPDATE person SET age = age + 1 WHERE birthday = ?

my $updated_persons = $bs->age_persons($today);

DESCRIPTION

SQL::Bibliosoph is a SQL statement library engine that allow to clearly separate SQL statements from PERL code. It is currently tested on MySQL 5.x, but it should be easly ported to other engines.

The catalog files are prepared a the initialization, for performance reasons. The use of prepared statement also helps to prevents SQL injection attacks. SQL::Bibliosoph supports bind parameters in statements definition and bind parements reordering. (SEE SQL::Bibliosoph::CatalogFile for details).

All functions throw 'carp' on error. The error message is 'SQL ERROR' and the mysql error reported by the driver.

Constructor parameters

dsn

The database handler. For example:

my $dbh = DBI->connect($dsn, ...);
my $bb = SQL::Bibliosoph(dsn=>$dsn, ...);

catalog

An array ref containg filenames with the queries. This files should use de SQL::Bibliosoft::CatalogFile format (SEE Perldoc for details). The suggested extension for these files is 'bb'. The name can be preceded with a "<" forcing the catalog the be open in "read-only" mode. In the mode, UPDATE, INSERT and REPLACE statement will be parsed. Note the calling a SQL procedure or function that actually modifies the DB is still allowed!

All the catalogs will be merged, be carefull with namespace collisions. the statement will be prepared at module constuction.

catalog_str

Allows to define a SQL catalog using a string (not a file). The queries will be merged with Catalog files (if any).

constants_from

In order to use the same constants in your PERL code and your SQL modules, you can declare a module using `constants_from` paramenter. Constants exported in that module (using @EXPORT) will be replaced in all catalog file before SQL preparation.

constants_path

Define the search path for `constants_from` PERL modules.

Bibliosoph

n. person having deep knowledge of books. bibliognostic.

AUTHORS

SQL::Biblosoph by Matias Alejo Garcia (matias at confronte.com) and Lucas Lain (lucas at confronte.com).

COPYRIGHT

Copyright (c) 2007 Matias Alejo Garcia. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT / WARRANTY

The SQL::Bibliosoph is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

SEE ALSO

SQL::Bibliosoph::CatalogFile

At http://nits.com.ar/bibliosoph you can find: * Examples * VIM syntax highlighting definitions for bb files * CTAGS examples for indexing bb files.

ACKNOWLEDGEMENTS

To Confronte.com and its associates to support the development of this module.

BUGS

This module is only tested with MySQL. Migration to other DB engines should be simple accomplish. If you would like to use Bibliosoph with other DB, please let me know and we can help you if you do the testing.