Alzabo (version 0.64) - Method Quick Reference

Index


GENERAL

Architecture

The general design of Alzabo is as follows.

There are objects representing the schema, which contains table objects. Table objects contain column, foreign key, and index objects. Column objects contain column definition objects. A single column definition may be shared by multiple columns, but has only one owner.

This is a diagram of these inheritance relationships:

  Alzabo::* (::Schema, ::Table, ::Column, ::ColumnDefinition, ::ForeignKey, ::Index)
                   /   \
	        is parent to
                 /       \
 Alzabo::Create::*   Alzabo::Runtime::*

This a diagram of how objects contain other objects:

                      Schema - makes--Alzabo::SQLMaker subclass object (many)
                     /      \
              contains       contains--Alzabo::Driver subclass object (1)
                  |                 \
               Table (0 or more)     Alzabo::RDBMSRules subclass object (1)
                /  \                  (* Alzabo::Create::Schema only)
               /    \
              contains--------------------
             /        \                   \
            /          \                   \
     ForeignKey      Column (0 or more)    Index (0 or more)
     (0 or more)       |
                    contains
                       |
		  ColumnDefinition (1)

Note that more than one column _may_ share a single definition object (this is explained in the Alzabo::Create::ColumnDefinition documentation). This is only relevant if you are writing a schema creation interface.

Alzabo, Alzabo::Create, and Alzabo::Runtime

These modules are mostly used just to load other modules. The Alzabo::Runtime module can be used to preload schemas at compile time by doing:

  use Alzabo::Runtime qw( schema1 schema2 schema3 );

Alzabo::MethodMaker

This module can be used to generate many useful convenience methods. This is done by auto-generating methods in new packages and re-blessing some of the schema objects into these packages. To have it generate all the possible methods for a schema you would do:

  use Alzabo::MethodMaker ( schema => 'some_schema',
                            # Root for new packages
                            class_root => 'My::Data',
                            # Make all possible methods
                            all => 1 );

This will make convenience methods for such things as getting table and column objects, following various types of foreign keys, and getting data from row objects.

METHODS

Creating/removing a schema

Alzabo::Create::Schema

This object represents a schema, and contains one or more table objects. It is only used when creating or altering a schema, as opposed to when fetching data. Data manipulation is done via the Alzabo::Runtime::* classes.

methodclass/objectdescriptionmore info
reverse_engineer
class

Connect to a database and reverse engineer a schema. Returns a new schema object.

More
load_from_file
class

Load an existing schema object from disk. Returns a new schema object.

More
create
object

If the schema has not yet been instantiated in an RDBMS, this method will instantiate the schema. If it has been previously instantiated, it will bring the schema in the RDBMS into sync with its object representation (altering tables/columns, etc.) Where possible, exist data will be preserved.

More
make_sql
object

Returns an array, each element of which is a SQL statement. The SQL is either the SQL to create the schema from scratch or the SQL needed to update the RDBMS to match the current object. See the create method for more details.

More
drop
object

Drop the database from the RDBMS where it was created. Does not remove the schema object itself from disk.

More
delete
object

Delete the schema object files from disk. Does not drop the database from the RDBMS.

More


Retrieving data

Alzabo::Runtime::Schema

This object allows you to connect to the database. It contains one data retrieval, method join.

methodclass/objectdescriptionmore info
load_from_file
class

Load an existing schema object from disk. Returns a new schema object.

More
set_user
 ($user)
object

Set the username to be used when connecting to the database.

More
set_password
 ($password)
object

Set the password to be used when connecting to the database.

More
set_host
 ($host)
object

Set the host to be used when connecting to the database.

More
connect
 (%params)
object

Connect to the RDBMS. This will use the previously set username/password/host, though these can be overridden by the %params given to the call.

Important: This method must be called before any data retrieval is attempted.

More
join
object

Fetch rows from one or more tables based on a table join. Returns either a Alzabo::Runtime::RowCursor or Alzabo::Runtime::JoinCursor object.

More
function/select
object

Allows you to execute arbitrary column aggregate SQL functions such as AVG or MAX with a multi-table join.

More
table
 ($name)
object

Returns an Alzabo::Runtime::Table object. This is important because most of the row fetching operations are table object methods.

More


Alzabo::Runtime::Table

Objects in this class have methods allowing you to insert new rows as well as retrieving exist data in the form of Alzabo::Runtime::Row or Alzabo::Runtime::RowCursor objects.

All methods that return a single row return an Alzabo::Runtime::Row object.

All methods that return multiple rows return an Alzabo::Runtime::RowCursor object.

All methods that return rows can be given the no_cache parameter, which ensures that the row(s) returned will not be cached. Rows obtained in this manner should not be updated or deleted, as this will play havoc with the caching system. See the Alzabo::Runtime::Row documentation for more details.

All methods that return multiple rows in the form of a cursor object can take an order_by parameter. See the Alzabo::Runtime::Table documentation for more details.

methodclass/objectdescriptionmore info
insert
object

Insert a new row and return it.

More
row_by_pk
object

Returns the row identified by the primary key give.

More
rows_where
object

Retrieves a set of rows based on a where clause. Please see the method documentation for details on how where clauses are constructed.

More
all_rows
object

Retrieves all the rows in the table.

More
function/select
object

Allows you to execute arbitrary column aggregate SQL functions such as AVG or MAX.

More
potential_row
object

Make a new Alzabo::Runtime::PotentialRow object.

More


Alzabo::Runtime::Row

Objects in this class represent a single row of data. You can retrieve the actual column values from it, update it, or delete it.

methodclass/objectdescriptionmore info
select
 (@list_of_column_names)
object

Given a list of column names, this method returns the values for those columns.

More
update
 (%hash_of_columns_and_values)
object

Given a hash of columns and values, this method will update the database and the object to match those values.

More
delete
object

Deletes the row from the database. Further attempts to retrieve data from this row will throw an exception.

More
rows_by_foreign_key
object

Given a foreign key object from the row's table to another table, returns either an Alzabo::Runtime::Row object or an Alzabo::Runtime::RowCursor object for the row(s) in the table to which the relationship exists, based on the value of the relevant column(s) in the current row.

This method can also take a no_cache and/or order_by parameter.

More


Alzabo::Runtime::RowCursor

Objects in this class are used to return multiple rows as a cursor, rather than as a list. This is much more efficient, at the expense of a few extra lines in your code.

methodclass/objectdescriptionmore info
next
object

Returns the next Alzabo::Runtime::Row object, or undef if there are no more.

More
all_rows
object

Returns a list of all the remaining Alzabo::Runtime::Row objects, or an empty list if there are no more.

More


AUTHOR

Dave Rolsky, <autarch@urth.org>