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.