DBIx::SearchBuilder::Record abstracts the agony of writing the common and generally
simple SQL statements needed to serialize and De-serialize an object to the
database. In a traditional system, you would define various methods on
your object create, find, modify, and delete being the most common.
In each method you would have a SQL statement like:

select * from table where value=blah;

If you wanted to control what data a user could modify, you would have to
do some special magic to make accessors do the right thing. Etc. The
problem with this approach is that in a majority of the cases, the SQL is
incredibly simple and the code from one method/object to the next was
basically the same.

With::Record, you can in the simple case, remove all of that code and
replace it by defining two methods and inheriting some code. Its pretty
simple, and incredibly powerful. For more complex cases, you can, gasp,
do more complicated things by overriding certain methods. Lets stick with
the simple case for now.

The two methods in question are _Init and _ClassAccessible, all they
really do are define some values and send you on your way. As you might
have guessed the _ suggests that these are private methods, they are.
They will get called by your record objects constructor.

_Init

Defines what table we are talking about, and set a variable to store
the database handle.

_ClassAccessible

Defines what operations may be performed on various data selected
from the database. For example you can define fields to be mutable,
or immutable, there are a few other options but I dont understand
what they do at this time.

Here we set our handle and table name, while its not obvious so far, well
see later that $handle (line: 006) gets passed via ::Record::new when a
new instance is created. Thats actually an important concept, the DB handle
is not bound to a single object but rather, its shared across objects.

Creates a new DBIx::SearchBuilder::Handle, and then connects to the database using
that handle. Pretty straight forward, the password  is what I use
when there is no password. I could probably leave it blank, but I find
it to be more clear to define it.

009:
010: my $s = Simple->new($handle);
011:
012: $s->LoadById(1);

LoadById is one of four LoadBy methods, as the name suggests it searches
for an row in the database that has id=0. ::SearchBuilder has, what I
think is a bug, in that it current requires there to be an id field. More
reasonably it also assumes that the id field is unique. LoadById($id) will
do undefined things if there is >1 row with the same id.

In addition to LoadById, we also have:

LoadByCol

Takes two arguments, a column name and a value. Again, it will do
undefined things if you use non-unique things.

LoadByCols

Takes a hash of columns=>values and returns the *first* to match.
First is probably lossy across databases vendors.

Now that we have a populated object, we should do something with it! ::Record
automagically generates accessos and mutators for us, so all we need to do
is call the methods. Accessors are named <Field>(), and Mutators are named
Set<Field>($). On to the example, just appending this to the code from
the last example.

Pretty simple! Thats really all there is to it. Set<Field>($) returns
a boolean and a string describing the problem. Lets look at an example of
what will happen if we try to set a Id which we previously defined as
read only.

Currently Set<Field> updates the data in the database as soon as you call
it. In the future I hope to extend ::Record to better support transactional
operations, such that updates will only happen when you say so.

Finally, adding a removing records from the database. ::Record provides a
Create method which simply takes a hash of key=>value pairs. The keys
exactly map to database fields.

An older way to specify fieldsattributes in a derived class.
(The current preferred method is by overriding Schema; if you do
this and dont override _ClassAccessible, the module will generate
an appropriate _ClassAccessible based on your Schema.)

_Object takes a single column name and an array reference.
It creates new object instance of class specified in _ClassAccessable
structure and calls LoadById on recently created object with the
current column value as argument. It uses the array reference as
the object constructors arguments.
Subclasses can override _Object to insert custom access control or
define default contructor arguments.

Note that if you are using a Schema with a REFERENCES field,
this is unnecessary: the method to access the columns value will
automatically turn it into the appropriate object.