5,576
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + + + + + + Line 41:
Line 46: − + Line 55:
Line 60: + + + + Line 91:
Line 100: + + + + + + + Line 98:
Line 114: + + + + Line 103:
Line 123: + + + + + + + + + + + + + + + + Line 134:
Line 170: − + Line 159:
Line 195: − + − + − + − + Line 183:
Line 219: + + + + + + + + + + + + + + Line 196:
Line 246: − + Line 216:
Line 266: − + Line 229:
Line 279: − + − + Line 237:
Line 287: − + − + − + Line 257:
Line 307: − [[Category:SME Server]] − [[Category:Howto]]
→create
===NAME===
===NAME===
esmith::DB - virtual interface to E-Smith databases
'''esmith::DB''' - virtual interface to E-Smith databases<br />
In a root terminal you can do the command below if you want to display the up-to-date content
perldoc -U esmith::DB
found on this side of the web, thanks to [http://smeserver.fr/perldoc.php?module=esmith::DB GranPa]
===SYNOPSIS===
===SYNOPSIS===
For example, there is esmith::DB::db to interface with esmith::db flatfile databases. There could also be esmith::DB::Berkeley to use Berkeley database files, or even esmith::DB::DBI.
For example, there is esmith::DB::db to interface with esmith::db flatfile databases. There could also be esmith::DB::Berkeley to use Berkeley database files, or even esmith::DB::DBI.
Most of the methods herein are ``virtual''. They don't exist. The subclass is responsible for impelmenting them. There are a handful of concrete methods that have been implemented for you that should work with any subclass.
Most of the methods herein are ''virtual''. They don't exist. The subclass is responsible for impelmenting them. There are a handful of concrete methods that have been implemented for you that should work with any subclass.
====Virtual Methods====
====Virtual Methods====
Should the $new_config_file already exist or for some reason you can't write to it, esmith::DB->error will return the reason and create() will return false.
Should the $new_config_file already exist or for some reason you can't write to it, esmith::DB->error will return the reason and create() will return false.
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');
===== open =====
===== open =====
If a record already exists for the $key it will return false.
If a record already exists for the $key it will return false.
see also [http://wiki.contribs.org/Esmith::DB::db#creating_a_new_record that page]
for example (if it doesn't exist we create it)
my $rec = $DB->get('roundcube') || $DB->new_record('roundcube', {type => 'service'});
===== get =====
===== get =====
If there's no record for the $key it will return false.
If there's no record for the $key it will return false.
for example (if it doesn't exist we create it)
my $rec = $DB->get('roundcube') || $DB->new_record('roundcube', {type => 'service'});
===== get_all =====
===== get_all =====
Gets all the records out of the given $db as a list of esmith::DB::Record objects.
Gets all the records out of the given $db as a list of esmith::DB::Record objects.
here an example
{
use esmith::HostsDB;
$DB = esmith::HostsDB->open;
# Purge quoting chars in comments to fix bug 8723 & bug 8806
foreach my $host ($DB->get_all)
{
my $comment = $host->prop('Comment');
next unless $comment;
$comment =~ s/['"]//g;
$host->merge_props(Comment => $comment);
}
}
==== Concrete methods ====
==== Concrete methods ====
my $value = 'default';
my $value = 'default';
if (my $r = $db->get("foo"))
if (my $r = $db->get("foo"))
{
{
my $status;
my $status;
if (my $s = $db->get(``foo'')) { $status = $s->prop('status'); }
if (my $s = $db->get("foo")) { $status = $s->prop('status'); }
$status ||= ``default'';
$status ||= 'default';
With this method, you can use:
With this method, you can use:
If the optional type option is passed, it will be used to create the record if it does not already exist. Otherwise, a non-existent record will cause this method to return an error.
If the optional type option is passed, it will be used to create the record if it does not already exist. Otherwise, a non-existent record will cause this method to return an error.
Returns 0 for any errors, 1 for success.
Returns 0 for any errors, 1 for success.
===== delete_prop =====
my $dbkey = $db->get("$key");
$dbkey->delete_prop("$prop");
or
db->get("$key")->delete_prop("$prop");
method to delete a propriety $prop of the key $key
===== delete =====
my $dbkey = $DB->get('$key');
$dbkey->delete;
a method to delete a key
===== keys =====
===== keys =====
The defaults are loaded from /etc/e-smith/db/<dbname>/migrate by default, but the environment variable ESMITH_DB_DEFAULTSDIR can be set to use a different hierarchy if required.
The defaults are loaded from /etc/e-smith/db/<dbname>/migrate by default, but the environment variable ESMITH_DB_DEFAULTSDIR can be set to use a different hierarchy if required.
The entries in ``migrate'' are perl fragments which will be evaluated and so can munge anything they choose to. But, please be gentle :-)
The entries in ''migrate'' are perl fragments which will be evaluated and so can munge anything they choose to. But, please be gentle :-)
So you could have
So you could have
==== _loadDefaults ($forceReset) ====
==== _loadDefaults ($forceReset) ====
This is a private method.
'''This is a private method.'''
Load the default properties for a given database. Caller can provide a flag to force resetting properties that already exist.
Load the default properties for a given database. Caller can provide a flag to force resetting properties that already exist.
Each of these directories is arranged as a set of subdirectories, with the directory name equal to the key for the given database. With these subdirectories are files, which are named by the properties of these database keys.
Each of these directories is arranged as a set of subdirectories, with the directory name equal to the key for the given database. With these subdirectories are files, which are named by the properties of these database keys.
The entries in ``defaults'' will be skipped if the existing key/property already exists (unless the $forceReset argument is provided). These are simple files, whose contents are the value to be used for that property.
The entries in ''defaults'' will be skipped if the existing key/property already exists (unless the $forceReset argument is provided). These are simple files, whose contents are the value to be used for that property.
The entries in ``force'' are always loaded into the given key/property. These are again simple files, like ``defaults''.
The entries in ''force'' are always loaded into the given key/property. These are again simple files, like ''defaults''.
To make this concrete, you might have:
To make this concrete, you might have:
/etc/e-smith/db/configuration/defaults/sshd/access
/etc/e-smith/db/configuration/defaults/sshd/access
containing the single word ``private'', which would be the default. This value would only be used if no ``access'' property existed, or the $forceReset option is passed.
containing the single word ''private'', which would be the default. This value would only be used if no ''access'' property existed, or the $forceReset option is passed.
You can override both ``defaults'' and ``migrate'' with
You can override both ''defaults'' and ''migrate'' with
/etc/e-smith/db/configuration/force/sshd/access
/etc/e-smith/db/configuration/force/sshd/access
containing the single word ``public'' to force the value of that property.
containing the single word ''public'' to force the value of that property.
==== get_value_and_delete ($key) ====
==== get_value_and_delete ($key) ====
SME Server Developers <bugs@e-smith.com>
SME Server Developers <bugs@e-smith.com>
[[Category:Developer]]
[[Category:Developer]]
[[Category:SME Server Development Framework]]
[[Category:SME Server Development Framework]]
[[Category:Development Tools]]
[[Category:Development Tools]]