Esmith::DB::db

From SME Server
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

NAME

esmith::DB::db - interface to esmith::db databases

In a root terminal you can do the command below if you want to display the up-to-date content

perldoc -U esmith::DB::db

SYNOPSIS

Works just like an esmith::DB class except where noted

DESCRIPTION

This module provides an abstracted interface to esmith::db flat-file databases. It will read from and write to esmith::db files and can be safely used right along side esmith::db. This follows the esmith::DB interface and will work as documented there unless otherwise stated.

You should use this instead of esmith::db, and replace any existing esmith::db code with this.

Note for esmith::db users the old concept of a ’type’ is now simply another property.

          my $type = $record->prop(’type’);

replaces db_get_type().

The $record returned by esmith::DB::db subclass is an esmith::DB::db::Record subclass object. See the esmith::DB::db manpage for details on how it is used.

Methods

create

Puts its error on esmith::DB::db->error

      open
      open_local
      as_hash
      reload
      file
      new_record
      get
      get_all
      get_all_by_prop

EXAMPLE

The full docs can be found in esmith::DB and esmith::DB::Record, but here’s a cheat sheet for esmith::config and esmith::db users.

opening the default config

              use esmith::config
              my %config;
              tie %config, ’esmith::config;

Now:

              use esmith::ConfigDB;
              my $config = esmith::ConfigDB->open;

opening a specific config database

              my %config;
              tie %config, ’esmith::config’, $config_file;

Now:

              my $config = esmith::ConfigDB->open($config_file);

creating a new config database

This one’s important. Before you could just tie esmith::config to any file and it would create it for you. Now you have to explicitly create it.

              my %config;
              tie %config, ’esmith::config’, $new_config_file;

Now:

              my $config = esmith::ConfigDB->create($new_config_file);

example for creating and using a custom database in one line:

my $customDB = esmith::ConfigDB->open('YOUR_DATABASE_NAME') || esmith::ConfigDB->create('YOUR_DATABASE_NAME');

checking if a record exists

              print "Yep" if exists $config{foo};

now:

              print "Yep" if $config->get(’foo’); # unless of course, ’foo’ is zero

creating a new record

Previously you could just create records on the fly:

              # single value
              $config{foo} = ’whatever’;
              # with properties
              db_set(\%config, ’whatever’, ’sometype’, { with => ’properties’ });

Now you have to explicitly create them:

              # single value
              my $foo = $config->new_record(’foo’);
              $foo->set_value(’foo’);

              # with properties
              my %defaults = ( ’type’    => ’sometype’,
                               ’linux’   => ’stable’,
                               ’windows’ => ’stable?’ );
              my $foo = $config->new_record(’foo’, \%defaults);

Note that ’type’ is now just another property.

Here’s a handy "create this if it doesn’t already exist" idiom.

              my $rec = $config->get($key) ││
                        $config->new_record($key);

for example (if it doesn't exist we create it)

    my $rec = $DB->get('roundcube') || $DB->new_record('roundcube', {type => 'service'});

getting a value

Entries in a database should no longer be thought of as values, but as records.

              my $val = $config{foo};

Now this only works with entries with single value. Things with multiple properties are dealt with differently.

              my $record = $config->get(’foo’);
              my $val = $record->value;

setting a value

              $config{foo} = ’something’;

now

              my $record = $config->get(’foo’);
              $record->set_value(’something’);

getting a property

              my $this = db_get_prop(\%config, ’foo’, ’this’);

now:

              my $foo = $config->get(’foo’);
              my $this = $foo->prop(’this’);

getting & setting properties

              my $val = db_get_prop(\%config, ’foo’, ’some prop’);
              db_set_prop(\%config, ’foo’, ’some prop’ => $new_val);

now:

              my $val = $record->prop(’some prop’);
              $record->set_prop(’some prop’ => $new_val);

get/setting the type

              my $type = db_get_type(\%config, ’foo’);
              db_set_type(\%config, ’foo’, $new_type);

type is now just a property

              my $record = $db->get(’foo’);
              my $type = $record->prop(’type’);
              $record->set_prop(’type’, $new_type);

getting all the properties

              my %props = db_get_prop(\%config, ’foo’);

now

              my %props = $record->props;

AUTHOR

      SME Server Developers <bugs@e-smith.com>