Tangram::Relational (3pm)

   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);

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

More backends could be added in the future; they might implement persistence in \s-1XML\s0 documents, pure object databases, using C database libraries to bypass the need for an \s-1RDBMS\s0, etc.

schema

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

Returns a new Schema object. See Tangram::Schema.

deploy

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

Writes \s-1SQL\s0 statements for preparing a database for use with the given $schema.

Called with a single argument, writes \s-1SQL\s0 statements to \s-1STDOUT\s0.

Called with two arguments, writes \s-1SQL\s0 statements to \s-1HANDLE\s0. \s-1HANDLE\s0 may be a \s-1DBI\s0 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 \s-1DBI\s0 handle, which is automatically closed.

The \s-1SQL\s0 code is only guaranteed to work on newly created databases.

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 Tangram::Storage for a description of available options.

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 deploy.

Like Charles Moore (inventor of Forth) used to say, \*(L"standards are great, everybody should have one!\*(R".

Tangram can take advantage of extensions available in some \s-1SQL\s0 dialects.

To create a vendor-specific driver, call it \*(C`Tangram::Foo\*(C' (where \*(C`Foo\*(C' is the name of the \s-1DBI\s0 driver, as would be selected with the \s-1DBI\s0 connection string \*(C`dbi:Foo:\*(C'), and derive \*(C`Tangram::Relational\*(C'.

For now, the existing back-ends should be used as examples of how to extend Tangram to support different databases or utilise some of their more exotic features.