view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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',
      );

    Returns:

      (undef,$obj) on success

  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:

     (errstr,undef) something failed with the DB
     (undef,HASHREF) on success containing keys: "rev", "timestamp","lock", "user". Each of those point to ARRAYREFs.

    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 latest config is currently locked. If it is, return
    information about the lock.

      $cfg->isConfigLocked();

    Returns

      (errstr,undef) on failure
      (undef,HASHREF) locked. see keys for details.
      (undef,0) not locked

  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. This should be
    called from the getConfig() method, not directly.

    Accepts:

      -rev => [int], defaults to 0
      -user => [string],

      $cfg->lockConfig(-rev => $rev, -user => $username);

    Returns:

      (errstr,undef) on failure
      ('lock failed',0) if already locked
      (undef,$rev) on success

  unlockConfig()
    Unlock the configuration. Both parameters are required. Should be called
    by the getConfig() method, not directly.

    Accepts:

      -rev => [int], defaults to 0
      -user => [string],

      $cfg->unlockConfig(-rev => $rev, -user => $username);

    Returns:

      (errstr,undef) on failure
      (undef,1) on success

  appendLogToConfig()
    Accepts:

      # required
      -user => undef,
      -rev => 0,
      -log => [],

      $cfg->appendLogToConfig(-rev => rev, -user => username, -log => ['myLogEntry']);

    Add a log entry to the given config revision.

    Returns

      (errstr,undef) on failure
      (undef,1) on success

  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]);

    Accepts:

      # required
      -rev => [int], defaults to 0
      -user => [string],

      # legal
      -lock => [0|1], default is 0 # lock for editing?

    Returns:

      (errstr,undef) on failure
      (undef,HASHREF) containing keys:

            {
                    'config'    => ARRAYREF,
                    'log'       => ARRAYREF,