Alzabo (version 0.64) - Alzabo::Runtime::Schema

Index



NAME

Alzabo::Runtime::Schema - Schema objects


SYNOPSIS

  use Alzabo::Runtime::Schema qw(some_schema);
  my $schema = Alzabo::Runtime::Schema->load_from_file( name => 'foo' );
  $schema->set_user( $username );
  $schema->set_password( $password );
  $schema->connect;


DESCRIPTION

This object can only be loaded from a file. The file is created whenever a corresponding Alzabo::Create::Schema object is saved.


INHERITS FROM

Alzabo::Schema

Note: all relevant documentation from the superclass has been merged into this document.


METHODS

load_from_file

Loads a schema from a file. This is the only constructor for this class.

Parameters

Returns

An Alzabo::Runtime::Schema object.

Throws

Alzabo::Exception::Params

user

Returns

The username used by the schema when connecting to the database.

set_user ($user)

Set the username to use when connecting to the database.

password

Returns

The password used by the schema when connecting to the database.

set_password ($password)

Set the password to use when connecting to the database.

host

Returns

The host used by the schema when connecting to the database.

port

Returns

The port used by the schema when connecting to the database.

set_host ($host)

Set the host to use when connecting to the database.

set_port ($port)

Set the port to use when connecting to the database.

referential_integrity

Returns

A boolean value indicating whether this schema will attempt to maintain referential integrity.

set_referential_integrity ($boolean)

Sets the value returned by the referential_integrity method. If true, then when Alzabo::Runtime::Row objects are deleted, updated, or inserted, they will report this activity to any relevant Alzabo::Runtime::ForeignKey objects for the row, so that the foreign key objects can take appropriate action.

Defaults to false.

connect (%params)

Calls the Alzabo::Driver->connect method for the driver owned by the schema. The username, password, host, and port set for the schema will be passed to the driver, as will any additional parameters given to this method. See the Alzabo::Driver->connect method for more details.

join

Joins are done by taking the tables provided in order, and finding a relation between them. If any given table pair has more than one relation, then this method will fail. The relations, along with the values given in the optional where clause will then be used to generate the necessary SQL. See Alzabo::Runtime::JoinCursor for more information.

Parameters

Returns

If the select parameter (or tables parameter) specified that more than one table is desired, then this method will return an Alzabo::Runtime::JoinCursor object representing the results of the join. Otherwise, the method returns an Alzabo::Runtime::RowCursor object.

Throws

Alzabo::Exception::Logic

one_row

This method takes the exact same parameters as the join method but instead of returning a cursor, it returns a single array of row object. These will be the rows representing the first ids that are returned by the database.

function and select

These two methods differ only in their return values.

Parameters

These methods is used to call arbitrary SQL functions such as 'AVG' or 'MAX'. The function (or functions) should be the return values from the functions exported by the SQLMaker subclass that you are using. Please see Using SQL functions for more details.

Returns

function

The return value of this method is highly context sensitive.

If you only requested a single function ( DISTINCT(foo) ), then it returns the first value in scalar context and all the values in list context.

If you requested multiple functions ( AVG(foo), MAX(foo) ) then it returns a single array reference (the first row of values) in scalar context and a list of array references in list context.

select

This method always returns a new Alzabo::DriverStatement object containing the results of the query.

name

Returns

A string containing the name of the schema.

tables (@optional_list)

Returns

A list of Alzabo::Runtime::Table object named in the list given. If no list is provided, then it returns all table objects in the schema.

Throws

Alzabo::Exception::Params

table ($name)

Returns

An Alzabo::Runtime::Table object representing the specified table.

Throws

Alzabo::Exception::Params

has_table ($name)

Returns

A true or false value depending on whether or not the table exists in the schema.

start_transaction

Starts a transaction. Calls to this function may be nested and it will be handled properly.

rollback

Rollback a transaction.

finish_transaction

Finishes a transaction with a commit. If you make multiple calls to start_transaction, make sure to call this method the same number of times.

run_in_transaction ( sub { code... } )

This method takes a subroutine reference and wraps it in a transaction.

It will preserve the context of the caller and returns whatever the wrapped code would have returned.

driver

Returns

The Alzabo::Driver subclass object for the schema.

rules

Returns

The Alzabo::RDBMSRules subclass object for the schema.

sqlmaker

Returns

The Alzabo::SQLMaker subclass object for the schema.


JOINING A TABLE MORE THAN ONCE

It is possible to join to the same table more than once in a query. Table objects support a method called alias that when called, returns an object that can be used in the same query as the original table object, but which will be treated as a separate table. This is to allow starting with something like this:

  SELECT ... FROM Foo AS F1, Foo as F2, Bar AS B ...

The object returned from the table functions more or less exactly like a table object. When using this table to set where clause or order by (or any other) conditions, it is important that the column objects for these conditions be retrieved from the alias object.

For example:

 my $foo_alias = $foo_tab->alias;
 my $cursor = $schema->join( select => $foo_tab,
                             join   => [ $foo_tab, $bar_tab, $foo_alias ],
                             where  => [ [ $bar_tab->column('baz'), '=', 10 ],
                                         [ $foo_alias->column('quux'), '=', 100 ] ],
                             order_by => $foo_alias->column('briz') );

If we were to use the $foo_tab object to retrieve the 'quux' and 'briz' columns then the join would simply not work as expected.

It is also possible to use multiple aliases of the same table in a join, so that this:

 my $foo_alias1 = $foo_tab->alas;
 my $foo_alias2 = $foo_tab->alas;

will work just fine.


USER AND PASSWORD INFORMATION

This information is never saved to disk. This means that if you're operating in an environment where the schema object is reloaded from disk every time it is used, such as a CGI program spanning multiple requests, then you will have to make a new connection every time. In a persistent environment, this is not a problem. In a mod_perl environment, you could load the schema and call the set_user and set_password methods in the server startup file. Then all the mod_perl children will inherit the schema with the user and password already set. Otherwise you will have to provide it for each request.

You may ask why you have to go to all this trouble to deal with the user and password information. The basic reason was that I did not feel I could come up with a solution to this problem that was secure, easy to configure and use, and cross-platform compatible. Rather, I think it is best to let each user decide on a security practice with which they feel comfortable. If anybody does come up with such a scheme, then code submissions are more than welcome.


CAVEATS

Refential Integrity

If Alzabo is attempting to maintain referential integrity and you are not using caching, then situations can arise where objects you are holding onto in memory can get out of sync with the database and you will not know this. If you are using one of the cache modules then attempts to access data from an expired or deleted object will throw an exception, allowing you to try again (if it is expired) or give up (if it is deleted). Please see Alzabo::ObjectCache for more details.


AUTHOR

Dave Rolsky, <autarch@urth.org>