This module provides an object-oriented mechanism for retrieving and updating data in a DBI-accesible database.

In order to use this module, you should create a subclass of DBIx::SearchBuilder and a subclass of DBIx::SearchBuilder::Record for each table that you wish to access. (See the documentation of DBIx::SearchBuilder::Record for more information on subclassing it.)

Your DBIx::SearchBuilder subclass must override NewItem, and probably should override at least _Init also; at the very least, _Init should probably call _Handle and _Table to set the database handle (a DBIx::SearchBuilder::Handle object) and table name for the class. You can try to override just about every other method here, as long as you think you know what you are doing.

Creates a new SearchBuilder object and immediately calls _Init with the same parameters that were passed to new. If you haven't overridden _Init in your subclass, this means that you should pass in a DBIx::SearchBuilder::Handle (or one of its subclasses) like this:

my $sb = My::DBIx::SearchBuilder::Subclass->new( Handle => $handle );

However, if your subclass overrides _Init you do not need to take a Handle argument, as long as your subclass returns an appropriate handle object from the _Handle method. This is useful if you want all of your SearchBuilder objects to use a shared global handle and don't want to have to explicitly pass it in each time, for example.

This method is called by new with whatever arguments were passed to new. By default, it takes a DBIx::SearchBuilder::Handle object as a Handle argument, although this is not necessary if your subclass overrides _Handle.

This completely erases all the data in the SearchBuilder object. It's useful if a subclass is doing funky stuff to keep track of a search and wants to reset the SearchBuilder data without losing its own data; it's probably cleaner to accomplish that in a different way, though.

This routine takes a reference to a scalar containing an SQL statement. It massages the statement to limit the returned rows to only $self->RowsPerPage rows, skipping $self->FirstRow rows. (That is, if rows are numbered starting from 0, row number $self->FirstRow will be the first row returned.) Note that it probably makes no sense to set these variables unless you are also enforcing an ordering on the rows (with OrderByCols, say).

Returns the next row from the set as an object of the type defined by sub NewItem. When the complete set has been iterated through, returns undef and resets the search such that the following call to Next will start over with the first item retrieved from the database.

To apply the Limit inside the ON clause of a previously created left join, pass this option along with the alias returned from creating the left join. ( This is similar to using the EXPRESSION option when creating a left join but this allows you to refer to the join alias in the expression. )

The standard form takes a param hash with keys ALIAS1, FIELD1, ALIAS2 and FIELD2. ALIAS1 and ALIAS2 are column aliases obtained from $self->NewAlias or a $self->Limit. FIELD1 and FIELD2 are the fields in ALIAS1 and ALIAS2 that should be linked, respectively. For this type of join, this method has no return value.

Supplying the parameter TYPE => 'left' causes Join to preform a left join. in this case, it takes ALIAS1, FIELD1, TABLE2 and FIELD2. Because of the way that left joins work, this method needs a TABLE for the second field rather than merely an alias. For this type of join, it will return the alias generated by the join.

Instead of ALIAS1/FIELD1, it's possible to specify EXPRESSION, to join ALIAS2/TABLE2 on an arbitrary expression.

It is also possible to join to a pre-existing, already-limited DBIx::SearchBuilder object, by passing it as COLLECTION2, instead of providing an ALIAS2 or TABLE2.

In order to test most of the features of DBIx::SearchBuilder, you need to provide make test with a test database. For each DBI driver that you would like to test, set the environment variables SB_TEST_FOO, SB_TEST_FOO_USER, and SB_TEST_FOO_PASS to a database name, database username, and database password, where "FOO" is the driver name in all uppercase. You can test as many drivers as you like. (The appropriate DBD:: module needs to be installed in order for the test to work.) Note that the SQLite driver will automatically be tested if DBD::Sqlite is installed, using a temporary file as the database. For example: