view release on metacpan or  search on metacpan

lib/Alzabo/Intro.pod  view on Meta::CPAN

schema as defined in Alzabo.

=head1 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.

If you would like to use transactions explicitly in your code, please
make sure to use the L<C<Alzabo::Schema>|Alzabo::Schema> class's
L<C<begin_work()>|Alzabo::Schema/begin_work>,
L<C<commit()>|Alzabo::Schema/commit>, and
L<C<rollback()>|Alzabo::Schema/rollback> methods.

=head1 EXCEPTIONS

Alzabo uses exceptions as its error reporting mechanism.  This means
that all calls to its methods should be wrapped in C<eval{}>.  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 C<$@>.

Also see the L<C<Alzabo::Exceptions>|Alzabo::Exceptions>
documentation, which lists all of the different exception used by
Alzabo.

This is similar to using C<DBI> with the C<RaiseError> attribute set
to a true value.

Its important to note that some methods (such as the driver's
C<rollback()> method) may use C<eval> 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 C<$@>
will be overwritten at the next C<eval>.

In addition, some methods you might use during cleanup can throw
exceptions of their own.

This is the point where I start wishing Perl had a B<real> exception
handling mechanism built into the language.

=head1 BACKWARDS COMPATIBILITY

Because Alzabo saves the schema objects to disk as raw data structures
using the C<Storable> module, it is possible for a new version of
Alzabo to be incompatible with a saved schema.

As of Alzabo version 0.65, Alzabo can now detect older schemas and
will attempt to update them if possible.

When you attempt to load a schema, whether of the
C<Alzabo::Create::Schema> or C<Alzabo::Runtime::Schema> classes,
Alzabo will determine what version of Alzabo created that schema.

If updates are necessary, Alzabo will first back up your existing
files with the extension F<.bak.v{version}>, where "{version}" is the
version of Alzabo which created the schema.

Then it will alter the schema as necessary and save it to disk.

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.

Alzabo will need the C<Alzabo::Create::*> 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.

=head1 MULTIPLE COPIES OF THE SAME SCHEMA

It is possible to use the same schema definition with multiple copies
of that schema in the RDBMS.  This can be done by setting the
"schema_name" parameter whenever you call a method that connects to
the RDBMS, such as L<<
C<Alzabo::Create::Schema-E<gt>create>|Alzabo::Create::Schema/create >>
or L<<
C<Alzabo::Runtime::Schema-E<gt>connect>|Alzabo::Runtime::Schema/connect
>>.  This will override the default, the schema's name as given when
it was first created via L<<
C<Alzabo::Create::Schema-E<gt>new>|Alzabo::Create::Schema/new >>.

Every time you call C<create()> or C<sync_backend()>, the schema will
consider itself to have been instantiated.  This means that if you
call C<create()> twice, each time with a different "schema_name"
parameter, then you will probably not be able to generate useful diffs
via the C<make_sql()> method in the future.

This is a bug that is unlikely to be fixed.

=head1 MULTIPLE RDBMS SUPPORT

Alzabo aims to be as cross-platform as possible.  To that end, RDBMS
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.

The first, the C<Alzabo::Driver::*> hierarchy, is used to handle
communication with the database.  It uses C<DBI> and the appropriate
C<DBD::*> module to handle communications.  It provides a higher level
of abstraction than C<DBI>, requiring that the RDBMS specific modules
implement methods to do such things as create databases or return the
next value in a sequence.

The second, the C<Alzabo::RDBMSRules::*> hierarchy, is used during
schema creation in order to validate user input such as schema and
table names.  It also generates DDL SQL to create the database or turn one
schema into another (sort of a SQL diff).  Finally, it also handles
reverse engineering of an existing database.

The C<Alzabo::SQLMaker::*> hierarchy is used to generate DML SQL and
handle bound parameters.

The RDBMS to be used is specified when creating the schema.
Currently, there is no easy way to convert a schema from one RDBMS to
another, though this is a future goal.

=head1 REFERENTIAL INTEGRITY

Alzabo can maintain referential integrity in your database based on
the relationships you have defined.  This can be toggled via L<< the