.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Alzabo::Intro 3pm"
.TH Alzabo::Intro 3pm "2015-05-24" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alzabo::Intro \- Introductory information about Alzabo
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document provides an introduction to the basics of using Alzabo,
primarily focused on the RDBMS-OO mapping functionality.
.SH "CREATING A SCHEMA"
.IX Header "CREATING A SCHEMA"
The first thing you'll want to do is create a schema.  The easiest way
to do this is to reverse
engineer an existing schema.
The Mason \s-1GUI,\s0 available in the separate \f(CW\*(C`Alzabo::GUI::Mason\*(C'\fR
distribution, provides another means of creating a schema.
.PP
And of course, you can create one through a custom Perl script which
uses the various \f(CW\*(C`Alzabo::Create::*\*(C'\fR classes.  Here's the beginning
of such a script:
.PP
.Vb 1
\&  use Alzabo::Create::Schema;
\&
\&  eval
\&  {
\&      my $s = Alzabo::Create::Schema\->new( name  => \*(Aqfoo\*(Aq,
\&                                           rdbms => \*(AqMySQL\*(Aq );
\&
\&      my $table = $s\->make_table( name => \*(Aqsome_table\*(Aq );
\&
\&      my $a_col = $table\->make_column( name => \*(Aqa_column\*(Aq,
\&                                       type => \*(Aqint\*(Aq,
\&                                       nullable   => 0,
\&                                       sequenced  => 0,
\&                                       attributes => [ \*(Aqunsigned\*(Aq ] );
\&
\&      $table\->add_primary_key($a_col);
\&
\&      my $b_col = $table\->make_column( name => \*(Aqb_column\*(Aq,
\&                                       type => \*(Aqvarchar\*(Aq,
\&                                       length   => 240,
\&                                       nullable => 0 );
\&
\&      $table\->make_index( columns => [ { column => $b_col,
\&                                         prefix => 10 } ] );
\&
\&      ...
\&
\&      $s\->save_to_file;
\&  };
\&
\&  if ($@) { handle exceptions }
.Ve
.SH "USAGE EXAMPLES"
.IX Header "USAGE EXAMPLES"
Alzabo is a powerful tool but as with many powerful tools it can also
be a bit overwhelming at first.  The easiest way to understand some of
its basic capabilities is through some examples.  Let's first assume
that you've created the following schema:
.PP
.Vb 4
\&  TABLE: Movie
\&  movie_id                 tinyint      \-\- primary key
\&  title                    varchar(200)
\&  release_year             year
\&
\&  TABLE: Person
\&  person_id                tinyint      \-\- primary key
\&  name                     varchar(200)
\&  birthdate                date
\&  birthplace_location_id   tinyint      \-\- foreign key to location
\&
\&  TABLE: Job
\&  job_id                   tinyint      \-\- primary key
\&  job                      varchar(200) \-\- something like \*(Aqactor\*(Aq or \*(Aqdirector\*(Aq
\&
\&  TABLE: Credit
\&  movie_id                 tinyint      \-\- primary key part 1, foreign key to movie
\&  person_id                tinyint      \-\- primary key part 2, foreign key to person
\&  job_id                   tinyint      \-\- primary key part 3, foreign key to job
\&
\&  TABLE: Location
\&  location_id              tinyint      \-\- primary key
\&  location                 varchar(200) \-\- \*(AqNew York City\*(Aq or \*(AqUSA\*(Aq
\&  parent_location_id       tinyint      \-\- foreign key to location
.Ve
.SS "Fetching data"
.IX Subsection "Fetching data"
In Alzabo, data is returned in the form of a row
object.  This object can be used to access the
data for an individual row.
.PP
Unless you are retrieving a row via a unique identifier (usually its
primary key), you will be given a cursor
object.  This is quite similar to how \f(CW\*(C`DBI\*(C'\fR uses statement handles
and is done for similar reasons.
.PP
First of all, let's do something simple. Let's assume I have a
person_id value and I want to find all the movies that they were in
and print the title, year of release, and the job they did in the
movie.  Here's what it looks like:
.PP
.Vb 1
\&  my $schema = Alzabo::Runtime::Schema\->load_from_file( name => \*(Aqmovies\*(Aq );
\&
\&  my $person_t = $schema\->table(\*(AqPerson\*(Aq);
\&  my $credit_t = $schema\->table(\*(AqCredit\*(Aq);
\&  my $movie_t  = $schema\->table(\*(AqMovie\*(Aq);
\&  my $job_t    = $schema\->table(\*(AqJob\*(Aq);
\&
\&  # returns a row representing this person.
\&  my $person = $person_t\->row_by_pk( pk => 42 );
\&
\&  # all the rows in the credit table that have the person_id of 42.
\&  my $cursor =
\&      $person\->rows_by_foreign_key
\&          ( foreign_key =>
\&            $person_t\->foreign_keys_by_table($credit_t) );
\&
\&  print $person\->select(\*(Aqname\*(Aq), " was in the following films:\en\en";
\&
\&  while (my $credit = $cursor\->next)
\&  {
\&      # rows_by_foreign_key returns a RowCursor object.  We immediately
\&      # call its next method, knowing it will only have one row (if
\&      # it doesn\*(Aqt then our referential integrity is in trouble!)
\&      my $movie =
\&          $credit\->rows_by_foreign_key
\&              ( foreign_key =>
\&                $credit_t\->foreign_keys_by_table($movie_t) )\->next;
\&
\&      my $job =
\&          $credit\->rows_by_foreign_key
\&              ( foreign_key =>
\&                $credit_t\->foreign_keys_by_table($job_t) )\->next;
\&
\&      print $movie\->select(\*(Aqtitle\*(Aq), " released in ", $movie\->select(\*(Aqrelease_year\*(Aq), "\en";
\&      print \*(Aq  \*(Aq, $job\->(\*(Aqjob\*(Aq), "\en";
\&  }
.Ve
.PP
A more sophisticated version of this code would take into account that
a person can do more than one job in the same movie.
.PP
The method names are quite verbose, so let's redo the example using
\&\f(CW\*(C`Alzabo::MethodMaker\*(C'\fR:
.PP
.Vb 5
\&  # Assume that the method_namer() subroutine pluralizes things as one
\&  # would expect.
\&  use Alzabo::MethodMaker( schema      => \*(Aqmovies\*(Aq,
\&                           all         => 1,
\&                           name_maker  => \e&method_namer );
\&
\&  my $schema = Alzabo::Runtime::Schema\->load_from_file( name => \*(Aqmovies\*(Aq );
\&
\&  # instantiates a row representing this person.
\&  my $person = $schema\->Person\->row_by_pk( pk => 42 );
\&
\&  # all the rows in the credit table that have the person_id of 42.
\&  my $cursor = $person\->Credits;
\&
\&  print $person\->name, " was in the following films:\en\en";
\&
\&  while (my $credit = $cursor\->next)
\&  {
\&      my $movie = $credit\->Movie;
\&
\&      my $job = $credit\->Job;
\&
\&      print $movie\->title, " released in ", $movie\->release_year, "\en";
\&      print \*(Aq  \*(Aq, $job\->job, "\en";
\&  }
.Ve
.SS "Updating data"
.IX Subsection "Updating data"
Updates are done by calling the \f(CW\*(C`update()\*(C'\fR method on a row object:
.PP
.Vb 2
\&  $movie\->update( title => \*(AqChungking Express\*(Aq,
\&                  year  => 1994 );
.Ve
.PP
If you are using \f(CW\*(C`Alzabo::MethodMaker\*(C'\fR, the per-column accessors it
generates for row objects can be used to set a column's value:
.PP
.Vb 1
\&  $movie\->title(\*(AqChungking Express\*(Aq);
.Ve
.PP
Be careful with this, though, because updates are done immediately
against the \s-1RDBMS,\s0 meaning each call to a setter method issues an
\&\f(CW\*(C`UPDATE\*(C'\fR query.  It's much more efficient to call the \f(CW\*(C`update()\*(C'\fR
method once with multiple values.
.SS "Deleting data"
.IX Subsection "Deleting data"
To delete a row, just call it's \f(CW\*(C`delete()\*(C'\fR method:
.PP
.Vb 1
\&  $movie\->delete;
.Ve
.SS "Validating data"
.IX Subsection "Validating data"
Let's assume that we've been passed a hash of values representing an
update to the location table. Here's a way of making sure that that
this update won't lead to a loop in terms of the parent/child
relationships.
.PP
.Vb 3
\&  sub update_location
\&  {
\&      my $self = shift; # this is the row object
\&
\&      my %data = @_;
\&
\&      if ( $data{parent_location_id} )
\&      {
\&          my $parent_location_id = $data{parent_location_id};
\&          my $location_t = $schema\->table(\*(AqLocation\*(Aq);
\&
\&          while ( my $location =
\&                  $location_t\->row_by_pk( pk => $parent_location_id ) )
\&          {
\&              die "Insert into location would create loop"
\&                  if $location\->select(\*(Aqparent_location_id\*(Aq) == $data{location_id};
\&
\&              $parent_location_id = $location\->select(\*(Aqparent_location_id\*(Aq);
\&          }
\&      }
\&  }
.Ve
.PP
Once again, let's rewrite the code to use
\&\f(CW\*(C`Alzabo::MethodMaker\*(C'\fR:
.PP
.Vb 3
\&  sub update_location
\&  {
\&      my $self = shift; # this is the row object
\&
\&      my %data = @_;
\&
\&      if ( $data{parent_location_id} )
\&      {
\&          my $location = $self;
\&          while ( my $location = $location\->parent )
\&          {
\&              die "Insert into location would create loop"
\&                  if $location\->parent_location_id == $data{location_id};
\&          }
\&      }
\&  }
.Ve
.SS "Using \s-1SQL\s0 functions"
.IX Subsection "Using SQL functions"
Each subclass of Alzabo::SQLMaker is capable of exporting functions
that allow you to use all the \s-1SQL\s0 functions that your \s-1RDBMS\s0 provides.
These functions are normal Perl functions.  They take as arguments
normal scalars (strings and numbers), \f(CW\*(C`Alzabo::Column\*(C'\fR objects, or
the return value of another \s-1SQL\s0 function.  They may be used to select
data via the \f(CW\*(C`select()\*(C'\fR and \f(CW\*(C`function()\*(C'\fR methods in both the
\&\f(CW\*(C`Alzabo::Runtime::Table\*(C'\fR and
\&\f(CW\*(C`Alzabo::Runtime::Schema\*(C'\fR classes.  They may also be used as part of updates, inserts,
and where clauses in any place that is valid \s-1SQL.\s0
.PP
Examples:
.PP
.Vb 1
\& use Alzabo::SQLMaker::MySQL qw(MAX NOW PI);
\&
\& my $max =
\&     $table\->function( select => MAX( $table\->column(\*(Aqbudget\*(Aq) ),
\&                       where  => [ $table\->column(\*(Aqcountry\*(Aq), \*(Aq=\*(Aq, \*(AqUSA\*(Aq ] );
\&
\& $table\->insert( values => { create_date => NOW() } );
\&
\& $row\->update( pi => PI() );
\&
\& my $cursor =
\&     $table\->rows_where( where =>
\&                         [ $table\->column(\*(Aqexpire_date\*(Aq), \*(Aq<=\*(Aq, NOW() ] );
\&
\& my $cursor =
\&     $table\->rows_where( where =>
\&                         [ LENGTH( $table\->column(\*(Aqpassword\*(Aq) ), \*(Aq<=\*(Aq, 5 ] );
.Ve
.PP
The documentation for the Alzabo::SQLMaker subclass for your \s-1RDBMS\s0
will contain a detailed list of all exportable functions.
.SS "Row Objects Not in the Database"
.IX Subsection "Row Objects Not in the Database"
Sometimes you'll want to create an object with the row object \s-1API,\s0 but
which does not represent a row in the database.  See the
\&\f(CW\*(C`Alzabo::Runtime::Row\*(C'\fR documentation for details on how these objects can be created.
.SS "Changing the schema"
.IX Subsection "Changing the schema"
In MySQL, there are a number of various types of integers.  The type
\&\f(CW\*(C`TINYINT\*(C'\fR can hold values from \-128 to 127.  But what if have more
than 127 movies?  And if that's the case we might have more than 127
people too.
.PP
For safety's sake, it might be best to make all of the primary key
integer columns \f(CW\*(C`INT\*(C'\fR columns instead.  And while we're at it we want
to make them \f(CW\*(C`UNSIGNED\*(C'\fR as well, as we don't need to insert negative
numbers into these columns.
.PP
You could break out the \s-1RDBMS\s0 manual (because you probably forgot the
exact \f(CW\*(C`ALTER TABLE\*(C'\fR syntax you'll need).  Or you could use Alzabo.
Note that this time we use a
\&\f(CW\*(C`Alzabo::Create::Schema\*(C'\fR object, not
\&\f(CW\*(C`Alzabo::Runtime::Schema\*(C'\fR.
.PP
.Vb 1
\&  my $schema = Alzabo::Create::Schema\->load_from_file( name => \*(Aqmovies\*(Aq );
\&
\&  foreach my $t ( $schema\->tables )
\&  {
\&      foreach my $c ( $t\->columns )
\&      {
\&           if ( $c\->is_primary_key and lc $c\->type eq \*(Aqtinyint\*(Aq )
\&           {
\&                $c\->set_type(\*(Aqint\*(Aq);
\&                $c\->add_attribute(\*(Aqunsigned\*(Aq);
\&           }
\&      }
\&  }
\&
\&  $schema\->create( user => \*(Aquser\*(Aq, password => \*(Aqpassword\*(Aq );
\&  $schema\->save_to_file;
.Ve
.PP
Because Alzabo keeps track of the schema's state the last time it was
created in the \s-1RDBMS,\s0 the \f(CW\*(C`create()\*(C'\fR method here will generate the
appropriate \s-1SQL\s0 to alter the \s-1RDBMS\s0 schema so that it matches the
schema as defined in Alzabo.
.SH "TRANSACTIONS"
.IX Header "TRANSACTIONS"
Alzabo uses transactions internally in order to guarantee consistency.
Obviously, if you are using a database such as MySQL (without InnoDB)
that does not support transactions, this is not possible.
.PP
If you would like to use transactions explicitly in your code, please
make sure to use the \f(CW\*(C`Alzabo::Schema\*(C'\fR class's
\&\f(CW\*(C`begin_work()\*(C'\fR,
\&\f(CW\*(C`commit()\*(C'\fR, and
\&\f(CW\*(C`rollback()\*(C'\fR methods.
.SH "EXCEPTIONS"
.IX Header "EXCEPTIONS"
Alzabo uses exceptions as its error reporting mechanism.  This means
that all calls to its methods should be wrapped in \f(CW\*(C`eval{}\*(C'\fR.  This is
less onerous than it sounds.  In general, there's no reason not to
wrap all of your calls in one large eval block.  Then at the end of
the block simply check the value of \f(CW$@\fR.
.PP
Also see the \f(CW\*(C`Alzabo::Exceptions\*(C'\fR
documentation, which lists all of the different exception used by
Alzabo.
.PP
This is similar to using \f(CW\*(C`DBI\*(C'\fR with the \f(CW\*(C`RaiseError\*(C'\fR attribute set
to a true value.
.PP
Its important to note that some methods (such as the driver's
\&\f(CW\*(C`rollback()\*(C'\fR method) may use \f(CW\*(C`eval\*(C'\fR internally.  This means that if
you intend to use them as part of the cleanup after an exception, you
may need to store the original exception in another variable, as \f(CW$@\fR
will be overwritten at the next \f(CW\*(C`eval\*(C'\fR.
.PP
In addition, some methods you might use during cleanup can throw
exceptions of their own.
.PP
This is the point where I start wishing Perl had a \fBreal\fR exception
handling mechanism built into the language.
.SH "BACKWARDS COMPATIBILITY"
.IX Header "BACKWARDS COMPATIBILITY"
Because Alzabo saves the schema objects to disk as raw data structures
using the \f(CW\*(C`Storable\*(C'\fR module, it is possible for a new version of
Alzabo to be incompatible with a saved schema.
.PP
As of Alzabo version 0.65, Alzabo can now detect older schemas and
will attempt to update them if possible.
.PP
When you attempt to load a schema, whether of the
\&\f(CW\*(C`Alzabo::Create::Schema\*(C'\fR or \f(CW\*(C`Alzabo::Runtime::Schema\*(C'\fR classes,
Alzabo will determine what version of Alzabo created that schema.
.PP
If updates are necessary, Alzabo will first back up your existing
files with the extension \fI.bak.v{version}\fR, where \*(L"{version}\*(R" is the
version of Alzabo which created the schema.
.PP
Then it will alter the schema as necessary and save it to disk.
.PP
This will all happen transparently, as long as the process which
initiated this process can write to the schema files and the directory
they are in.
.PP
Alzabo will need the \f(CW\*(C`Alzabo::Create::*\*(C'\fR classes to update the
schema.  If these have not been loaded already, Alzabo will do so and
issue a warning to say that this has happened, in case you would like
to restart the process without these classes loaded.
.SH "MULTIPLE COPIES OF THE SAME SCHEMA"
.IX Header "MULTIPLE COPIES OF THE SAME SCHEMA"
It is possible to use the same schema definition with multiple copies
of that schema in the \s-1RDBMS. \s0 This can be done by setting the
\&\*(L"schema_name\*(R" parameter whenever you call a method that connects to
the \s-1RDBMS,\s0 such as \f(CW\*(C`Alzabo::Create::Schema\->create\*(C'\fR
or \f(CW\*(C`Alzabo::Runtime::Schema\->connect\*(C'\fR.  This will override the default, the schema's name as given when
it was first created via \f(CW\*(C`Alzabo::Create::Schema\->new\*(C'\fR.
.PP
Every time you call \f(CW\*(C`create()\*(C'\fR or \f(CW\*(C`sync_backend()\*(C'\fR, the schema will
consider itself to have been instantiated.  This means that if you
call \f(CW\*(C`create()\*(C'\fR twice, each time with a different \*(L"schema_name\*(R"
parameter, then you will probably not be able to generate useful diffs
via the \f(CW\*(C`make_sql()\*(C'\fR method in the future.
.PP
This is a bug that is unlikely to be fixed.
.SH "MULTIPLE RDBMS SUPPORT"
.IX Header "MULTIPLE RDBMS SUPPORT"
Alzabo aims to be as cross-platform as possible.  To that end, \s-1RDBMS\s0
specific operations are contained in several module hierarchies.  The
goal here is to isolate RDBMS-specific behavior and try to provide
generic wrappers around it, inasmuch as is possible.
.PP
The first, the \f(CW\*(C`Alzabo::Driver::*\*(C'\fR hierarchy, is used to handle
communication with the database.  It uses \f(CW\*(C`DBI\*(C'\fR and the appropriate
\&\f(CW\*(C`DBD::*\*(C'\fR module to handle communications.  It provides a higher level
of abstraction than \f(CW\*(C`DBI\*(C'\fR, requiring that the \s-1RDBMS\s0 specific modules
implement methods to do such things as create databases or return the
next value in a sequence.
.PP
The second, the \f(CW\*(C`Alzabo::RDBMSRules::*\*(C'\fR hierarchy, is used during
schema creation in order to validate user input such as schema and
table names.  It also generates \s-1DDL SQL\s0 to create the database or turn one
schema into another (sort of a \s-1SQL\s0 diff).  Finally, it also handles
reverse engineering of an existing database.
.PP
The \f(CW\*(C`Alzabo::SQLMaker::*\*(C'\fR hierarchy is used to generate \s-1DML SQL\s0 and
handle bound parameters.
.PP
The \s-1RDBMS\s0 to be used is specified when creating the schema.
Currently, there is no easy way to convert a schema from one \s-1RDBMS\s0 to
another, though this is a future goal.
.SH "REFERENTIAL INTEGRITY"
.IX Header "REFERENTIAL INTEGRITY"
Alzabo can maintain referential integrity in your database based on
the relationships you have defined.  This can be toggled via the
\&\f(CW\*(C`Alzabo::Runtime::Schema\->set_referential_integrity()\*(C'\fR
method.
.PP
Alzabo enforces these referential integrity rules:
.IP "\(bu" 4
Inserts
.Sp
An attempt to insert a value into a table's foreign key column(s) will
fail if the value does not exist in the foreign table.
.Sp
If a table is dependent on another table, any columns from the
dependent table involved in the relationship will be treated as not
nullable.
.Sp
If the relationship is one-to-one, all columns involved in the foreign
key will be treated as if they had a unique constraint on them (as a
group if there is more than one) unless any of the columns being
inserted are \s-1NULL.\s0
.Sp
The exception to this rule is that no attempt is made to enforce
constraints on a table's primary key, as that could conceivably make
it impossible to insert a row into the table.
.IP "\(bu" 4
Updates
.Sp
Updates follow the same rules as inserts.
.IP "\(bu" 4
Deletes
.Sp
When a row is deleted, foreign tables which are dependent on the one
being deleted will have the relevant rows deleted.  Otherwise, the
foreign table's related column(s) will simply be set to \s-1NULL.\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, <autarch@urth.org>