NAME

       Alzabo::QuickRef - A quick reference to methods in the Alzabo classes

GENERAL

       This reference is intended to provide a quick reference to some of the more commonly used
       methods that Alzabo provides.  In addition, this reference can give you an idea of what
       classes contain certain types of methods, so you have an idea of where to look in order to
       figure out how to achieve a certain task.

   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

   Retrieving data
       Alzabo::Runtime::Schema

       This object allows you to connect to the database.  It contains several data retrieval
       methods including "join".

       •   load_from_file

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

       •   set_user ($user)

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

       •   set_password ($password)

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

       •   set_host ($host)

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

       •   connect (%params)

           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.

       •   join

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

       •   function/select

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

       •   table ($name)

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

       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.

       •   insert

           Insert a new row and return it.

       •   row_by_pk

           Returns the row identified by the primary key give.

       •   rows_where

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

       •   all_rows

           Retrieves all the rows in the table.

       •   function/select

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

       •   potential_row

           Make a new "Alzabo::Runtime::Row" in the "potential" state.

       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.

       •   select (@list_of_column_names)

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

       •   update (%hash_of_columns_and_values)

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

       •   delete

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

       •   rows_by_foreign_key

           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.

       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.

       •   next

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

       •   all_rows

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

   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.

       •   reverse_engineer

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

       •   load_from_file

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

       •   create

           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.

       •   make_sql

           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.

       •   drop

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

       •   delete

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

AUTHOR

       Dave Rolsky, <autarch@urth.org>