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

Persist is a tool for easily managing data in a database, for managing database
tables, 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 back-ends. The back-ends make certain that certain features are
available, but do not guarantee that all aspects are fully enforced.

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.

The new Persist::Overview document is a good place to start.

RELEASE NOTES for 0.5.3

This is a bug fix release. The changes are extremely important as the testing
system was broke during the last release. (I forgot to completely remove the
previous version, so 0.5.2 was still using an obsolete 0.5.1 file for testing,
which a typically user isn't likely to have.) The problem is now fixed and the
testing system should run again.

The other change is that I added support for the $bytable option to the next
and first methods of Persist::Join. This should have been added in 0.5.2, but
it slipped my mind.

The new testing system has been revised slightly and is now known to run since
it is used to test the front-end of Persist.

These changes and others have been made to begin paving the way for the
inclusion of a MySQL driver, which I hope to make part of the 0.5.4 release.

The API of this library is mostly stabilized. I see the 0.5.x series to be a
chance to expand the horizons of what Persist is able to do. With the new
parameter passing syntax, it should be easier to add new features to the system
without changing anything that has passed. This series will probably see the
addition of a lot of new usability features. I also hope to include one and
maybe two new back-end drivers.

STORAGE SYSTEM DRIVERS of 0.5.3

There are only two back-ends and one abstract support driver. The memory
back-end is fully functional and supports "transient persistence." Each memory
database is fresh and all data is lost upon destruction. This is primarily
intended for testing purposes. It is very slow since all data is stored in
B+ Trees via another package of mine, Tree::BPTree. That package is documented
to be many times slower than hashes for most operations, but are reliable
for testing purposes--see the documentation for Tree::BPTree for benchmarks.

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

At this time the DBI driver is in a kind of weird state that needs to be fixed.
It may be hard to develop new DBI-based drivers with it because it is so tightly
bound with PostgreSQL. This should be changing soon with the introduction of a
second DBI driver.

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

INSTALLATION

Installation follows the typical pattern for Perl modules:

   perl Makefile.PL
   make
   make test
   make install

Running "make" will ask some questions about how to test the PostgreSQL driver.
These will allow you to test the driver to make sure it is working properly
prior to installation. If you plan on using the PostgreSQL driver, I highly
recommend configuring this.

If you want to avoid these questions, you may set the PG_DATABASE, PG_HOST,
PG_PORT, PG_USERNAME, and PG_PASSWORD environment variables to appropriate
values prior to running make for the first time. If you need to reconfigure
these settings after running make, you must first run:

  make clean

to clear the current settings.

The tests will create and drop a couple tables several times (named "folks" and
"favorites"). You should probably use a blank database for this. (I use a scratch
database that I use for a variety of tests on my own machine.)

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

DEPENDENCIES

This module requires these other modules and libraries:

  * Perl 5.8.0
  * DateTime
  * DateTime::Format::ISO8601
  * DateTime::Format::Pg (if you test the PostgreSQL driver)
  * DBD::Pg (if you test the PostgreSQL driver)
  * DBI
  * Getargs::Mixed
  * 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.
