Alzabo::Runtime::Table - Table objects
use Alzabo::Runtime::Table;
This object is able to create rows, either by making objects based on existing data or inserting new data to make new rows.
This object also implements a method of lazy column evaluation that can be used to save memory and database wear and tear, though it needs to be used carefully. Please see the set_prefetch and add_group methods as well as "LAZY COLUMN LOADING" for details.
set_prefetch
add_group
insert
Takes the following parameters:
-- values => $hashref
This hashref should be a hash of column names to values.
Inserts the given values into the table and returns a new row object if it is successful. If no values are given for a primary key column and the column is sequenced then the values will be generated from the sequence.
All other parameters given will be passed directly to the Alzabo::Runtime::Row new method (such as the 'no_cache' parameter).
new
Exceptions:
AlzaboException - no value provided for unsequenced foreign key. AlzaboException - attempt to set non-NULL column to NULL AlzaboReferentialIntegrityException - insert violates referential integrity.
row_by_pk
-- pk => $pk_val or \%pk_val
DEPRECATED:
-- id => $pk_val or \%pk_val
These parameters are the same. The 'id' parameter will be removed in a future version.
Given a primary key value, this method will return a new Alzabo::Runtime::Row object matching this key. The primary key can be either a simple scalar, when the column is a single primary key, or a hash reference of column names to primary key when the primary key is more than one column.
If no rows in the database match the id value given then an empty list or undef will be returned (for list or scalar context).
AlzaboException - values provided are not enough or do not match primary key.
row_by_id
-- row_id => $row_id
Given a string representation of a row's id (as returned by the Alzabo::Runtime::Row id method), returns a new Alzabo::Runtime::Row object matching that id.
id
Returns a new Alzabo::Runtime::RowCursor object representing the query.
AlzaboException - no row matches the id.
rows_where
-- where => { column_name => $column_value }
A hash reference of column names to column values that will be SELECTed for.
-- from => $from
A FROM clause for a SQL statement. This can be omitted, in which case only the current table is used.
This is a simpler version of the rows_by_where_clause method that does a better job of abstracting SQL, at the expense of some flexibility.
Given these items this method generates SQL that will retrieve a set of primary keys for the table and return an array of rows based on that information.
rows_by_where_clause
-- where => $from
A WHERE clause for a SQL statement. This parameter is required.
-- bind => $one_value or \@values
An optional list of values to be bound to the statement execution.
Given these items this method generates SQL that will retrieve a set of primary keys for the table and return an array of rows based on that information. If you want the rows to come back in a specific order you'll probably have to use an 'ORDER BY' clause in your 'where' parameter.
WARNING: This method may be deprecated in the future in favor of something that abstracts SQL even more.
all_rows
Simply returns all the rows in the table.
row_count
Returns a scalar indicating how many rows the table has.
set_prefetch (Alzabo::Column objects)
Given a list of column objects, this makes sure that all Alzabo::Runtime::Row objects fetch this data as soon as they are created, as well as immediately after they know they have been expired in the cache.
NOTE: It is pointless (though not an error) to give primary key column here as these are always prefetched (in a sense).
prefetch
Returns a list of column names (not objects) that should be prefetched. Used by Alzabo::Runtime::Row.
add_group (Alzabo::Column objects)
Given a list of column objects, this method creates a group containing these columns. This means that if any column in the group is fetched from the database, they will all be fetched. Otherwise column are always fetched singly. Currently, a column cannot be part of more than one group.
NOTE: It is pointless to include a column that was given to the set_prefetch method in a group here, as it always fetched as soon as possible.
group_by_column ($column_name)
Given a column name, this returns a list of column names representing the group that this column is part of. If it is not part of a group, only the name passed in is returned. Used by Alzabo::Runtime::Row.
I stole this concept directly from Michael Schwern's Class::DBI module (credit where its due).
By default, row objects only load data from the database as it is requested via the select method. This is stored internally in the object after being fetched. If the object is expired in the cache, it will erase this information.
This is good because it saves on memory and make object creation but it is bad because you could potentially end up with one SQL call per column (excluding primary key columns, which are never fetched from the database).
The Alzabo::Runtime::Table class provides two method to help you handle this potential problem. Basically these methods allow you to declare usage patterns for the table.
The first method, set_prefetch, allows you to specify a list of columns to be fetched immediately after object creation or after an object discovers it is expired in the cache. These should be columns that you expect to use extremely frequently.
The second method, add_group, allows you to group columns together. If you attempt to fetch one of these columns, then all the columns in the group will be fetched. This is useful in cases where you don't often want certain data, but when you do you need several related pieces.
Dave Rolsky, <autarch@urth.org>
11 POD Errors
The following errors were encountered while parsing the POD:
Expected '=item *'
You forgot a '=back' before '=head1'
=back without =over
To install Alzabo, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Alzabo
CPAN shell
perl -MCPAN -e shell install Alzabo
For more information on module installation, please visit the detailed CPAN module installation guide.