NAME Database::Schema::Config - Perl extension for storing generic config strings with revision control in a table SYNOPSIS This is an interface module to our database. All SQL queries should be done at this level and only leave the actual config parsing to the upper level modules. *Note: All references to timestamp or date/time are usually stored as Time::Timestamp objects, see Time::Timestamp for output options. DESCRIPTION An API for storing and manipulating configuration files RCS-style using a database backend. This allows the author to utilize any Config module they wish (config::General, Config::Simple, etc...). SQL Table [mysql] -- -- Table structure for table `config` -- CREATE TABLE `config` ( `rev` int(11) NOT NULL auto_increment, `xlock` tinyint(4) NOT NULL default '0', `dt` int(11) NOT NULL default '0', `user` varchar(32) NOT NULL default '', `config` text NOT NULL, `log` text, PRIMARY KEY (`rev`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=2 ; OBJECT METHODS new() Constructor my $cfg = Database::Schema::Config->new( -dbh => $myDBI_handler, -str => $configString, -user => $user, -table => 'myConfigTable', ); listConfigs() Fetch a listing of all of the stored configs. The listing will contain the rev, timestamp, lock status, and user. If you want the log and config, use getConfig(). Returns (undef,HASHREF) on success containing keys: "rev", "timestamp", "lock", "user". Each of those point to ARRAYREFs. ('db failure',undef) something failed with the DB So the revision of the first config in the list (which should be the oldest) is $hr->{'rev'}->[0] isConfigLocked() Check to see if the config is currently locked. If it is, return information about the lock. $cfg->isConfigLocked(); Returns (undef,0) not locked (undef,HASHREF) locked. see keys for details. ('db failure',undef) something failed with the DB lockConfig() Lock the configuration so other people know we are editting it. A note will be appended to the "log" for the configuration. The latest configuration will be "locked" unless "rev" is specified. $cfg->lockConfig(-rev => $rev, -user => $username); +rev The revision to lock. Required. Pass in the revision of the currently running config. user An identifier denoting who is locking the config. Required Returns (undef,1) on success ('lock failed',0) someone has it locked already. check the log by fetching the config. See C ('invalid parameters',undef) the routine was called improperly ('db failure',undef) something failed with the DB unlockConfig() Unlock the configuration. Both parameters are required. $cfg->unlockConfig(-rev => $rev, -user => $username); Returns (undef,1) on success ('invalid parameters',undef) the routine was called improperly ('config not locked',0) the config is not locked ('db failure',undef) something failed with the DB appendLogToConfig() $cfg->appendLogToConfig(-rev => rev, -user => username, -log => []); Add a log entry to the given config revision. Returns (undef,1) on success (undef,0) Revision doesn't exist ('invalid parameters',undef) the routine was called improperly ('db failure',undef) something failed with the DB getConfig() Fetch the specified configuration from the database. If "rev" is not give, fetch the highest (latest) config from the database. If "lock" is "1", place an advisory lock on the configuration so that other people can't edit it without a warning. $cfg->getConfig(-rev => integer, -user => $username, -lock => [0|1]); +rev An optional integer identifying which configuration to retrieve from the database. Default is to fetch the latest. user This parameter is required of lock is "1". lock 0 = get the config, I don't plan on editting it. (DEFAULT) 1 = get the config, I plan on editting it, so warning anyone else who tries to edit the config. Returns (undef,HASHREF) containing keys: { 'config' => ARRAYREF, 'log' => ARRAYREF, 'timestamp' => integer, 'rev' => integer, ' user' => scalar string } ('lock failed',undef) you said lock=1 but someone else already has a config locked for editting ('db failure',undef) something failed with the DB putConfig() Insert a new configuration file into the database ("config" table). It's up to the calling application to "notice" the config rev was updated. $cfg->putConfig( -config => ARRAYREF, -user => "username", -log => ARRAYREF, -autounlock => 0, # default is to unlock the config if isConfigLocked() == true ); config This is an array reference that contains the new configuration file (string). user A username or identifier of the person who is importing the new configuration. log An optional array reference containing some text describing what changes have been made. Returns (undef,1) on success. ('db failure',undef) something failed with the DB ('invalid parameters',undef) the routine was called improperly. resetLocks() This function resets all xLocks in the event that something screws up. $cfg->resetLocks( -rev => $rev, # defaults to $cfg->rev() ); dbh() Sets and returns the Database handle table() Sets and returns the base config table string() Sets and returns the config string user() Sets and returns the user rev() Sets and returns the rev SEE ALSO Time::Timestamp sourceforge://netpass AUTHOR'S Original Author - Jeff Murphy - Stolen By - Wes Young - LICENSE (c) 2006 University at Buffalo. Available under the "Artistic License" http://www.gnu.org/licenses/license-list.html#ArtisticLicense