Version 0.022
This Module aims to take the repetitiveness out of simple database activity. It delivers far less than an ORM like DBIC, but is also far simpler and easier to learn. At this time it only supports INSERT, UPDATE, DELETE, SELECT, and COUNT, and it supports a WHERE clause. It is also possible to execute a string as a SQL command. Future enhancements will support a Stored Procedure interface, GROUP BY and ORDER BY. It is not intended to add support for JOIN, if that support is ever added it would be implemented as mocking a View.
IhQ is a sensible choice if you are concerned with basic SQL operations, and can move any joins out to a View or Stored Procedure. It's advantage is that it is pretty simple and is intuitive if you already know SQL.
I presume that others have written similar wrappers in the past, and in fact IhasQuery is superficially similar to Fey:SQL, but differs significantly in that it requires no predefinition (it needs a DBI handle and the name of a table, which is close enough to no predefinition) and is dumber.
use IhasQuery ;
my $fieldname = <I>some field in sometable</I> ;
my $queryvalue = <I>some value I want to match</I> ;
my $dbh = <I>... some code to create a DBI handle, see the DBI documentation...</I> ;
my $table_stuff = IhasQuery->new( $dbh, 'stuff' ) ;
$table_stuff->setwhere( $fieldname, '=', $queryvalue ) ;
say $table_stuff->preview( 'SELECT' ) ; # see the SQL for select
$table_stuff->select() ; # do SQL
my %HASH = $q->fetchrow_hash() ;
# Execute the same query but in fewer lines
$table_stuff->select( 'SETWHERE' => [ $fieldname, '=', $queryvalue ], ) ;
The new constructor requires a valid DBI Handle. It doesn't check anything, so you won't know anything is wrong until you try to execute something. By passing the DBI Handle rather than instiating it internally you can have any number of IhasQuery objects all sharing the same DBI Handle. The second argument binds the object to a specific table (required).
This sets a Hash used when Fields/Values are required. fields is used to retrieve the list of fields in the current resultset, or in the hash that was passed into field_values. The list is internally updated when a select query is run or field_values are updated.
The count method immediately executes SELECT COUNT (*) with the current where clause, and returns the result as a simple scalar value. The count_all method does the same thing, but instead sets the current Where clause to ALL.
my $count = $q->count() ;
Provide the content of the where clause. The method where() requires providing the exact sql (don't include where as it is prepended when generating the query). The method setwhere() takes three arguments $fieldname, $operator, $value and creates the where clause. Normally if you want to return ALL rows pass the string 'ALL' to where. $q->where( 'ALL' ), if no where is specified, the default is ALL.
preview() returns the query that would be executed. You should pass the operation as an upercase string, $q->preview('INSERT'), preview tries to generate a preview regardless.
Clears all current query settings. Whenever values are passed to an IhQ object they remain until overwritten or cleared. It is a good practice to use clear frequently. When 'CLEAR' is specified in the hash passed to a database method, a dummy value is required, the value passed is ignored and clear is processed first.
$q->clear() ; # Clear all values held in $q.
$q->select(
'CLEAR' => 0 , # The value here does not matter, it is ignored.
'WHERE' => 'ALL' ) ;
These two commands fetch the next row from the current resultset. fetchrow returns an array, fetchrow_hash returns a hash. When using fetchrow the fields method can be used to match fieldnames to the rows.
After the last row is fetched with fetchrow or fetchrow_hash, the last_row method will return true, last_error returns the last DBI error recieved. Both of these values are cleared immediately before any query execution.
These methods provide the sequel basics. Most of the other methods can be passed together in a hash, where the method name capitalized serves as the key. field_values and setwhere respectively require a hash reference and an array reference. The methods return 0 or the dbi error. Anything returned needs to be accessed with the fetchrow, fetchrow_hash and last_row methods.
query takes a string as an argument and passes it to dbi. As with the database methods it returns 0 on success or the error from dbi if there is one. As with the database methods, anything returned by the query needs to be accessed with the fetchrow, fetchrow_hash and last_row methods.
IhasQuery does not currently support joins. Since joins should only be used on the server side in CREATE VIEW or STORED_PROCEDURE statements this is arguably a good thing. Since, in the real world programmers often do not have the proper access to the database, the eventual solution will be for IhasQuery to create its' own views and stored_update procedures.
If you want fast and simple access to your data, and don't need the intelligence and features that DBIx::Class offers, an IhasQuery Model may be just what the Doctor ordered.
John Karr, <brainbuz at brainbuz.org>
Please report any bugs or feature requests to bug-ihasquery at rt.cpan.org, or through
the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc IhasQuery
You can also look for information at:
Copyright 2010 John Karr.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 3 or at your option any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.