tangram::relational(3pm) [debian man page]

Tangram::Relational(3pm)				User Contributed Perl Documentation				  Tangram::Relational(3pm)

NAME

       Tangram::Relational - Orthogonal Object Persistence in Relational Databases

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

DESCRIPTION

       This is the entry point in the vanilla object-relational persistence backend. Vendor-specific backends should be used when they exist. Cur-
       rently 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 XML documents, pure object databases, using C database
       libraries to bypass the need for an RDBMS, etc.

CLASS METHODS

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

       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.

WRITING A VENDOR DRIVER

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

       Tangram can take advantage of extensions available in some SQL dialects.

       To create a vendor-specific driver, call it "Tangram::Foo" (where "Foo" is the name of the DBI driver, as would be selected with the DBI
       connection string "dbi:Foo:"), and derive "Tangram::Relational".

       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.

perl v5.8.8							    2006-03-29						  Tangram::Relational(3pm)

Tangram::Intro(3pm)					User Contributed Perl Documentation				       Tangram::Intro(3pm)

NAME

       Tangram::Intro - an introduction to Tangram

SYNOPSIS

	# http://www.faqs.org/rfcs/rfc2324.html
	perl -MNet::HTCPCP -le 'Net::HTCPCP->new("BREW")->send'

	perldoc Tangram::Intro

YIN AND YANG OF OBJECT PERSISTENCE

       There are yin and yang approaches to object persistence.  Are you a yin programmer or a yang programmer?

       yin (without, empty) - "I just want to store my objects"

       yang
	   (with, full) - "I want my database to represent my object structure"

       Please skip to the introduction that suits you.

       YIN OBJECT PERSISTENCE (A LA PIXIE)

       One yin approach is to have a single table of objects -

	 +----+------------------+
	 | ID | DATA		 |
	 +----+------------------+

       This is the raw technique used by modules like MLDBM.  Stick objects in, get a tag (or, insert with a tag), and later present that tag to
       get the objects out.

       Modules like Pixie extend this concept, to allow you to have objects that are persistent (ie, have been stored and could be retrieved again
       by ID or name), inside other structures that are also persistent.  This is achieved without storing the same structure twice, without hav-
       ing to fetch all objects that are in a single persistent structure, and without requiring that the objects being stored even know that they
       are being stored.

       Fantastic.  This method is fine for any application that doesn't mind single threading data manipulation on objects.

       Enough banter, let's see some code; here's a project schema:

	package MyProject::Tangram;

	use Heritable::Types;
	use Tangram::Core;
	use Tangram::Type::Dump::Any;

	our $schema =
	    Tangram::Schema->new
		( { classes =>
		     [ HASH => {
			   fields => {
			       idbif => # poof!
				  undef
			   },
		       },
		     ],
		  } );

	 sub db { Tangram::Storage->new($schema, @_) }

       This defines a sort of "store anything" schema.	You could deploy your database like this:

	my $dbh = DBI->connect
	     ("dbi:mysql:tangram", "user", "pass");
	Tangram::Relational->deploy ( $MyProject::Tangram::schema,
				      $dbh );

       And then shove objects in and out like this:

	 use MyProject::Tangram;
	 my $storage = MyProject::Tangram::db
	     ("dbi:mysql:tangram", "user", "pass");

	 my $object = bless { first_name => "Homer",
			      last_lame => "Simpson",
			     }, "NaturalPerson";
	 my $oid = $storage->insert($object);

	 my $homer = $storage->load($oid);

       If this Pixie-like functionality is all you're after, then you can stop there, and isn't much slower than Pixie.  You also get the choice
       of whether you want to freeze data structures in your database via "Data::Dumper", "Storable" or "YAML".

       YANG OBJECT PERSISTENCE

       If you wish to enable concurrency without paying a large performance penalty for most standard types of data access, then you may need to
       extract single parts of your objects into columns.  That way, you can make the most use of your database's (hopefully) highly tuned and
       refined ability to cache and manipulate data indices.

       In that case, you may choose to start with mapping all of your object's properties to database columns (as was the only option before Tan-
       gram 2.08):

	package MyProject::Tangram;

	use Tangram::Core;

	our $schema =
	    Tangram::Schema->new
		( { classes =>
		     [ NaturalPerson => {
			   fields => {
			       string => {
			       },
			       integer => {
					   }
			   },
		       },
		     ],
		  } );

	 sub db { Tangram::Storage->new($schema, @_) }

       Tangram has been transaction-savvy since version 1.  So long as you are careful to flush Tangram's object cache, before you start doing
       selects that lock rows for update, then you can easily write transaction protected programs.

perl v5.8.8							    2006-03-29						       Tangram::Intro(3pm)