Dave Rolsky > Alzabo > Alzabo::Runtime::Schema

Download:
Alzabo-0.92.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  4
Open  1
View/Report Bugs
Module Version: 2   Source  

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 ^

Objects in this class represent schemas, and can be used to retrieve data from that schema.

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

METHODS ^

load_from_file ( name => $schema_name )

Loads a schema from a file. This is the only constructor for this class. It returns an Alzabo::Runtime::Schema object. Loaded objects are cached in memory, so future calls to this method may return the same object.

Throws: Alzabo::Exception::Params, Alzabo::Exception::System

set_user ($user)

Sets the username to use when connecting to the database.

user

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

set_password ($password)

Set the password to use when connecting to the database.

password

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

set_host ($host)

Set the host to use when connecting to the database.

host

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

set_port ($port)

Set the port to use when connecting to the database.

port

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

set_referential_integrity ($boolean)

Turns referential integrity checking on or off. If it is on, 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.

This defaults to false. If your RDBMS supports foreign key constraints, these should be used instead of Alzabo's built-in referential integrity checking, as they will be much faster.

referential_integrity

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

set_quote_identifiers ($boolean)

If this is true, then all SQL constructed for this schema will have quoted identifiers (like `Table`.`column` in MySQL).

This defaults to false. Turning this on adds some overhead to all SQL generation.

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.

disconnect

Calls the Alzabo::Driver->disconnect() method for the driver owned by the schema.

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.

This method takes the following parameters:

If the "select" parameter specified that more than one table is desired, then this method will return n JoinCursor object representing the results of the join. Otherwise, the method returns a RowCursor object.

Throws: Alzabo::Exception::Logic, Alzabo::Exception::Params

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 objects. These will be the rows representing the first row (a set of one or more table's primary keys) that is returned by the database.

Throws: Alzabo::Exception::Logic, Alzabo::Exception::Params

function and select

These two methods differ only in their return values.

They both take the following parameters:

These methods are used to call arbitrary SQL functions such as 'AVG' or 'MAX', and to select data from individual columns. 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.

Throws: Alzabo::Exception::Logic, Alzabo::Exception::Params

function() return values

The return value of this method is highly context sensitive.

If you only requested a single element in your "select" parameter, such as "DISTINCT(foo)", then it returns the first value in scalar context and all the values as an array in list context.

If you requested multiple functions such as "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() return values

This method always returns a new Alzabo::DriverStatement object containing the results of the query. This object has an interface very similar to the Alzabo cursor interface, and has methods such as next(), next_as_hash(), etc.

row_count

This method is simply a shortcut to get the result of COUNT('*') for a join. It equivalent to calling function() with a "select" parameter of COUNT('*').

Throws: Alzabo::Exception::Logic, Alzabo::Exception::Params

prefetch_all

This method will set all the tables in the schema to prefetch all their columns. See the lazy column loading section in Alzabo::Runtime::Table for more details.

prefetch_all_but_blobs

This method will set all the tables in the schema to prefetch all their non-blob-type columns.

This method is called as soon as a schema is loaded.

prefetch_none

This method turns of all prefetching.

JOINING A TABLE MORE THAN ONCE ^

It is possible to join to the same table more than once in a query. Table objects contain an alias() method 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 faciliaties queries similar to the following SQL::

  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->alias;

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

If we were to use the $foo 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 will work properly:

 my $foo_alias1 = $foo->alias;
 my $foo_alias2 = $foo->alias;

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. For example, 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.

In addition, there are a number of modules aimed at helping store and use this sort of information on CPAN, including DBIx::Connect and AppConfig, among others.

AUTHOR ^

Dave Rolsky, <autarch@urth.org>

syntax highlighting: