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

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

RELEASE NOTES for 0.5.0

This version of the library has resulted in a full minor version because the API
has changed slightly. For most code, this will not have any effect whatsoever. I
have tried to make the changes very minimal. However, the code required to
connect and create new database instances has changed. Code working with dates
will also have to be changed--though, this is probably a positive since the old
date handling was a load of garbage.

The API changes are three-fold. The back-end has switched to use a named-parameter
passing syntax. All parameters passed to drivers are now passed as key/value
pairs. This has altered the front-end in that the Persist::Source::new(),
Persist::Source::new_source(), and Persist::Source::delete_source() pass
arguments directly to the back-end. Because of this, creating connections has
changed slightly.

The second API change is seamless. All front-end methods now accept a mixed
positional/named argument syntax. That is, the arguments to methods can be
passed using a more traditional positional approach or by using named arguments
as are used with the back-end methods. Further, the syntax can be mixed in
certain ways. See Persist::Overview or Getargs::Mixed for details.

The third API change is quite major and involves the handling of dates.
Previously, dates were handled only as strings in a very stupid format. I do not
know what possessed me to choose such a format, but it has been abolished. Dates
may now be used as strings formatted in ISO 8601 format. Dates returned from the
database will be returned as DateTime objects, which is an excellent utility put
out by the Perl DateTime project--see http://datetime.perl.org/. Anyway, this
change ought to be welcome.

Finally, it should be noted that another minor change has been added which might
break code using an older version. The problem occurs when using the
Persist::Table::value() or Persist::Tabular::value() methods as if they were
common fields. The last version used some "magic" to try and guess when it was
being misused, but try to do the right thing anyway. I decided that this was a
too bad of an idea to keep. Further, with the new mixed argument passing syntax,
it becomes much more difficult to make it work. Therefore, attempting to misuse
the value() method this way will either result in bad results or an error--as it
should.

In addition to API changes, a few minor build system changes have been made to
make it easier to configure and install. See the section on INSTALLATION below.

The API of this library is otherwise well stabilized. In fact, these changes
were made to make it even more so. Now, new features can be added to either the
back-end or front-end without even the temptation to break older code.

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

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 likely to be very slow as all data is
stored in Perl hashes.

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 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 "perl Makefile.PL" 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.

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--the DBA tests will attempt to create a database and user
named "test" and then drop both.

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
  * DBD::Pg
  * 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.
