NAME

Persistence::Object::Postgres - Object Persistence with PostgreSQL.

SYNOPSIS

  use Persistence::Database::SQL;

  my $db = new Persistence::Database::SQL
    ( Engine => 'Postgres',
      Database => $database_name, 
      Table => $table_name,
      Template => $template_hashref );

  my $object1 = new Persistence::Object::Postgres
    ( __Dope => $db,
      $key => $value );

  my $object2 = new Persistence::Object::Postgres
    ( __Dope => $db, 
      __Oid => $object_id );

  $object1->{$key} = $object2->{$key};

  $object_id = $object1->commit();
  $object2->expire();

DESCRIPTION

This module provides persistence (and optionally, replication) facilities to its objects. Object definitions are stored in a PostgreSQL database as stringified perl data structures, generated with Data::Dumper. Persistence is achieved with a blessed hash container that holds the object data.

Using a template mapping object data to PostgreSQL fields, it is possible to automatically generate PostgreSQL fields out of the object data, which allows you to use poweful PostgreSQL indexing and querying facilities on your database of persistent objects.

This module is intended for use in conjunction with the object database class Persistence::Database::SQL, which provides persistent object database handling functionality for multiple DBMS back-ends. Persistence::Object::Postgres is the module that implements methods for the PostgreSQL back-end.

CONSTRUCTOR

new()

Creates a new Persistent Object.

  my $object = new Persistence::Object::Postgres 
    ( __Dope => $database );

Takes a hash argument with following possible keys:

__Dope

The Database of Persistent Entities. This attribute is required and should have as its value a Persistence::Database::SQL object corresponding to the database being used.

__Oid

An optional Object ID. If this attribute is specified, an attempt is made to load the corresponding persistent object. If no corresponding object exists, this attribute is silently ignored.

OBJECT METHODS

commit()

Commits the object to the database.

  $object->commit(); 

expire()

Irrevocably destroys the object. Removes the persistent entry from the DOPE.

  $object->expire(); 

If you want to keep a backup of the object before destroying it, use commit() to store it in a different table or database.

  $db->table('expired');
  $object->commit;
  $db->table('active');
  $object->expire(); 

Inheriting Persistence::Object::Postgres

In most cases you would want to inherit this module to provide persistence for your own classes. If you use your objects to store refs to class data, you'd need to bind and detach these refs at load() and commit(). Otherwise, you'll end up with a separate copy of class data for every object which will eventually break your code. See perlobj(1), perlbot(1), and perltoot(1), on why you should use objects to access class data.

BUGS

• Error checking needs work.

• __Oid is ignored by new() if an object of this ID doesn't already exist. That's because Postgres generates an oid for us at commit() time. This is a potential compatibility issue as many other database engines don't work like postgres in this regard.

  A more generic solution would be to ignore the Postgres oid field and create a unique identifier of our own at commit(), or use the user specified __Oid. This will probably be implemented in a future version, but code written with the assumption that __Oid is ignored should still work fine. __Oid just won't be ignored, is all.

SEE ALSO

Persistence::Database::SQL(3), Data::Dumper(3), Persistence::Object::Simple(3), DBD::Recall(3), Replication::Recall::DBServer(3), perlobj(1), perlbot(1), perltoot(1).

AUTHOR

Persistence::Object::Postgres is Copyright (c) 2000-2001, Ashish Gulhati <hash@netropolis.org>. All Rights Reserved.

ACKNOWLEDGEMENTS

Thanks to Barkha for inspiration, laughs and great times, and to Vipul for Persistence::Object::Simple, the constant use and abuse of which resulted in the writing of this module.

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER

This is free software. If it breaks, you own both parts.