=head1 NAME

Tangram::Relational - Orthogonal Object Persistence in Relational Databases

=head1 SYNOPSIS

   use Tangram;

   $schema = Tangram::Relational->schema( $hashref );

   Tangram::Relational->deploy($schema, $dbh);
      
   $storage = Tangram::Relational->connect( $schema,
      $data_source, $username, $password );

   $storage->disconnect();

   Tangram::Relational->retreat($schema, $dbh);

=head1 DESCRIPTION

This is the entry point in the vanilla object-relational persistence
backend. Vendor-specific backends should be used when they
exist. Currently Mysql and Sybase have such backends; see
L<Tangram::mysql> and L<Tangram::Sybase>.

More backends will be added in the future; they will
implement persistence in XML documents, pure object databases etc.

=head1 CLASS METHODS

=head2 schema

   $schema = Tangram::Relational->schema( $hashref );

Returns a new Schema object. See L<Tangram::Schema>. 

=head2 deploy

   Tangram::Relational->deploy($schema);
   Tangram::Relational->deploy($schema, HANDLE);
   Tangram::Relational->deploy($schema, @dbi_args);

Writes SQL statements for preparing a database for use with the given
$schema.

Called with a single argument, writes SQL statements to STDOUT.

Called with two arguments, writes SQL statements to HANDLE. HANDLE may
be a DBI connection handle or a file handle.

Called with more than two arguments, passes all but the first to
DBI::connect() and writes statements to the resulting DBI handle,
which is automatically closed.

The SQL code is only guaranteed to work on newly created databases.

=head2 connect

   $storage = Tangram::Relational->connect( $schema,
      $data_source, $user, $password, \%options )

Connects to a storage and return a handle object. Dies in case of
failure.

$schema is a Schema object describing the system of
classes stored in the database.

$data_source, $user and $password are passed directly to
DBI::connect().

\%options is a reference to a hash containing connection options. See
L<Tangram::Storage> for a description of available options.

=head2 retreat

   Tangram::Relational->retreat($schema);
   Tangram::Relational->retreat($schema, HANDLE);
   Tangram::Relational->retreat($schema, @dbi_args);

Remove the tables created by deploy(). Only guaranteed to work against
a database that was deployed using exactly the same schema.

For an explanation of the possible argument lists, see L<deploy>.


