Persist Data Access Library
===============================

Persist is a tool for easily managing data in a database, for managing
database schemas, and for even managing database instances. It is meant
to make table management and filtering unified across database backends.
That is, you write one statement and the backend driver makes sure that
the statement is handled properly on the back-end--in some cases,
emulating database features to get the correct functionality.

The emphasis has been upon developing an easy-to-program API that is
uniform across backends. The back-ends make certain that certain
features are available, but do not guarantee that all aspects are fully
enforced--for example, creating a UNIQUE index under the PostgreSQL
driver is fully enforced by the PostgreSQL database, but the Memory
driver does not explicitly enforce this constraint.

The primary goal of this library is ease of use. High performance is not
of primary interest. If performance is what you are looking for, you
should probably use DBI or DBM database interfaces directly. This
library was originally designed for use supporting web-based tools where
performance is important--particularly for queries--but ultra-high
performance isn't generally required.

RELEASE NOTES (0.3.2)

At this point, the API has pretty well stabilized. There have been some
additions, but few changes. Some changes are coming--particularly with
connection methods and schema management, but these should be minor. A
major interest of the 0.3.x series is stabilizing the API.  Another
major goal of the 0.3.1 series is stabilize the system to minimize bugs.

As of this writing, there are two back-ends and one abstract support
driver. The memory back-end is now fully functional--to my
knowledge--and supports ``temporary'' persistence. Each memory database
is fresh and all data is lost upon destruction. This is primarily
intended for testing purposes. It is likely to be very slow as all data
is stored in Perl hashes. There is one notable bug involving TIMESTAMP
types at this time, see Bugs for details. This shouldn't affect very
many users.

The DBI abstract back-end is used to create other DBI back-ends. It
features pre-built queries for most of the common operations and support
for table and column lookups through the new DBI calls for table_info
and column_info. Drivers extending the DBI driver still need to
implement DDL and DBA calls as those are nearly always dependent upon
the database system being used.

The other concrete driver is the PostgreSQL driver. This is the only
driver that has really been built with the intent of actual use.  It
supports all functionality of Persist via a PostgreSQL system including
DBA calls, if a DBA user is available. It is still a little unreliable
and also requires version 7.3 or later of PostgreSQL.

The 0.3.2 is an very small increment from 0.3.1 mostly because of a show
stopping bug in the Memory driver that effects the new Contentment test
system.

INSTALLATION

The simplest way to install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

If you intend to use the PostgreSQL driver, you probably will want to
make sure Persist is working properly. The PostgreSQL driver tests are
not enabled by default because they require additional configuration. To
configure these tests. Do something like this:

   perl Makefile.PL PGTESTCONN=dbname=sterling PGTESTUSER=sterling \
                    PGTESTPASS=somepass
   make && make test && make install

This will tell the PostgreSQL tests to use a database named "sterling"
with a user named "sterling" with password "somepass" during testing.
The tests will create and drop a couple tables several times (named
"folks" and "favorites"). You should probably use a blank database owned
by a user with the ability to create databases and users--to test the
DBA features of the PostgreSQL driver.

For any other help, you can see http://contentment.sourceforge.net/ or
contact hanenkamp@users.sourceforge.net.

DEPENDENCIES

This module requires these other modules and libraries:

  * Carp
  * Date::Calc
  * DBD::Pg
  * DBI
  * PostgreSQL 7.3 or greater

COPYRIGHT AND LICENCE

Copyright (c) 2003, Andrew Sterling Hanenkamp
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met:

  * Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright 
    notice, this list of conditions and the following disclaimer in 
	the documentation and/or other materials provided with the 
	distribution.
  * Neither the name of the Persist project nor the names of its 
    contributors may be used to endorse or promote products derived 
	from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.
