The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
DBM-Deep-Manager-0.03
River stage zero No dependents
/ dbmdeep

NAME

dbmdeep - manage DBM::Deep databases via command line

SYNOPSIS

 Usage: dbmdeep [-ceiVhv] [<dbfile>]
 Manage a DBM::Deep database. Options:
 
   --config=<config>   | -c <config>    yaml config containing connect params
   --export=<file>     | -e <file>      export db to <file>
   --import=<file>     | -i <file>      import db from <file>
   --verbose           | -V             enable debug output
   --help              | -h             this help message
   --version           | -v             print program version
 
 If - is specified as <file>, STDIN or STDOUT is used respectively.
 Interactive commands can be piped into dbmdeep as well, e.g.:
 echo "drop users" | dbmdeep my.db.

DESCRIPTION

dbmdeep is a command line utility which can be used to maintain DBM::Deep databases. It is possible to view, modify or delete contents of the database and you can export to a YAML file or import from one.

The utility presents an interactive prompt where you enter commands to maintain the database, see section INTERACTIVE COMMANDS for more details. Commands can also be piped into the tool via STDIN. Example:

 dbmdeep my.db
 my.db> show

is the same as:

 echo "show" | dbmdeep my.db

OPTIONS

--config

Specify a config file in YAML format. The config may contain special customizations for the DBM::Deep instanziation. See section CONFIG for more details.

--export

Export the contents of the database to a YAML file. If the specified file name is -, STDOUT will be used to print the export.

--import

Import data from a YAML file. If the database already exists, the contents of the import file will be merged with the existing contents, otherwise the database will be created.

--verbose

Enable debugging output.

--help

Print a usage message to STDERR.

--version

Print the software version to STDERR.

CONFIG

A config file is optional. If no config file is specified, dbmdeep makes a couple of assumptions about the database: it opens it with the DBM::Deep::Storage::File backend with transactions enabled.

Since DBM::Deep allows for a range of options about the storage backend, the dbmtree utility supports complete customization using the config file (parameter --config).

Here are couple of examples:

 ---
 perl: |
   use Compress::Zlib;
   %params = (
       filter_store_key => \&my_compress,
       filter_store_value => \&my_compress,
       filter_fetch_key => \&my_decompress,
       filter_fetch_value => \&my_decompress,
   );
   sub my_compress {
       my $s = shift;
       utf8::encode($s);
       return Compress::Zlib::memGzip( $s ) ;
   }
   sub my_decompress {
       my $s = Compress::Zlib::memGunzip( shift ) ;
       utf8::decode($s);
       return $s;
   }

This config implements the sample in DBM::Deep::Cookbook#Real-time-Compression-Example. It uses the standard File backend but compresses everything using Compress::Zlib. Note that this config only contains one entry: perl, with a multiline value which contains perl code. This perl code will be evaluated by dbmdeep at runtime.

Please note, that the hash %params is predefined by dbmdeep, so it must exist and must not be local (e.g. don't use: 'my %params'!). The hash may contain anything allowed by DBM::Deep::new().

Also note, that this config doesn't specify a database, so the file name of the database must be specified on the command line, eg:

 dbmdeep -c zip.yaml my.db

Another example:

 ---
 dbi:
   dsn: dbi:SQLite:dbname=sb.sqlite
   username:
   password:
   connect_args:

Here we use the DBM::Deep::Storage::DBI backend with a sqlite database. You don't need to speficy a database file name on the command line in such a case, eg:

 dbmdeep -c sqlite.yaml

Other supported config parameters are: editor which will be used by the interactive edit command and more which will be used by interactive commands which display large amounts of data.

INTERACTIVE COMMANDS

DISPLAY COMMANDS

list

Lists the keys of the current level of the database hash.

Shortcut: l.

show

Does nearly the same as list but also shows the content of the keys. If a key points to a structure (like a hash or an array), show whill not display anything of it, but instead indicate, that there'e more behind that key.

Shortcut: sh.

dump

Dumps out everything of the current level of the database hash.

Shortcut: d.

get key | /regex>

Displays the value of key. If you specify a regex, the values of all matching keys will be shown.

enter key

You can use this command to enter a sub hash of the current hash. It works like browsing a directory structure. You can only enter keys which point to sub hashes.

Shortcuts: cd

If the key you want to enter doesn't collide with a command, then you can also just directly enter the key without 'enter' or 'cd' in front of it, eg:

 my.db> list
 subhash
 my.db> subhash
 my.db subhash> dump
 my.db subhash> ..
 my.db>^D

If you specify .. as parameter (or as its own command like in the example below), you go one level up and leave the current sub hash.

EDIT COMMANDS

set key value

Use the set command to add a new key or to modify the value of a key. value may be a valid perl structure, which you can use to create sub hashes or arrays. Example:

 my.db> set users [ { name => 'max'}, { name => 'joe' } ]
 ok
 mydb> get users
 users =>
 {
   'name' => 'max'
 },
 {
   'name' => 'joe'
 }

Please note that the set command overwrites existing values without asking.

edit key

You can edit a whole structure pointed at by key with the edit command. It opens an editor with the structure converted to YAML. Modify whatever you wish, save, and the structure will be saved to the database.

append key value

This command can be used to append a value to an array. As with the set command, value can be any valid perl structure.

drop key

Delete a key.

Again, note that all commands are executed without further asking or warning!

pop key

Remove the last element of the array pointed at by key.

shift key

Remove the first element of the array pointed at by key.

TRANSACTION COMMANDS

See DBM::Deep#TRANSACTIONS.

begin

Start a transaction.

commit

Save all changes made since the transaction began to the database.

rollback

Discard all changes of the transaction.

MISC COMMANDS

help

Display a short command help.

Shortcuts: h or ?.

CTRL-D

Quit dbmdeep

Shortcuts: quit.

AUTHOR

T.v.Dein <tlinden@cpan.org>

BUGS

Report bugs to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBM::Deep::Manager

SEE ALSO

DBM::Deep

COPYRIGHT

Copyright (c) 2015 by T.v.Dein <tlinden@cpan.org>. All rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This is the manual page for dbmdeep Version 0.01.