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.