NAME

dbtool - a tool for storing key/value pairs in a hash database

SYNOPSIS

dbtool -d database [DirusSfwVhtRFpP] [-k key] [-v value]

DESCRIPTION

This manual page documents the program dbtool. dbtool can be used to store and retrieve data in a key/value format in a hash database. Perl compatible regular expressions are supported both for storing and retrieving of data. It's main advantages are the ability to maintain huge amounts of data and speed.

OPTIONS

-D

Dump all key/value pairs of the database. Keys and values will be separated by whitespace or by the character specified by -F.

-f

Enable force mode, which has the following causes:

insert

Keys (and the associated value) will be overwritten if it already exists.

update

Key/value will be created if it does not exist.

-F -separator

Optional field separator. The default separator is one whitespace. Use -F in conjunction with -D to specify an alternate output field separator or with -i if data is read in from STDIN (without -k and -v).

-h

Prints out a short help message to STDERR and exits.

-i

Insert data. The -k and -v options are required. You will get an error message if the key already exists. Use -f to avoid such a message and let dbtool overwrite the key instead. If both key (-k) and value (-v) are not provided, dbtool will read in the data from STDIN. The default input separator is one whitespace. The first field (separated by whitespace) will be considered as the key and the rest of the input line will be considered as the value associated with the key. You can provide an alternate input field separator using the option -F. It is also possible to separate the key and value of an input line using a regular expression with the -t option(see below).

-k key

Use key as the key. Use -k in conjunction with -i, -u, -r, -s or -S.

-r

Remove data. Only the key to be removed (-k) is required.

-R

Reverse the meaning of the expression provided with -t. By default dbtool will use the first match as the key and the second one as the value. With -R this will be reversed.

-s

Search for a key specified by -k. The associated value will be printed to STDOUT. You can use -w to get the key too separated by whitespace or by the parameter of -F. You can only search for keys, not for values.

-S

Search for a key. The parameter to the option -k will be considered as a perl compatible regular expression. It is possible to get multiple results, which will be printed to STDOUT separated by newline. Otherwise -S behaves like -s.

-t expression

Use expression to decide which part of an input line has to be used as the key and which one as the value. The regular expression must contain two parts surrounded by round parenthesis'. See the section EXAMPLES for some uses of -t. This option can only be used in conjunction with -i without -k and -v.

-u

Update data. A key (-k) and a value (-v) is required. You will get an error message if the key does not exist. You can use the option -f to avoid such a message and to insert the data if it does not exist instead.

-p

Use encrypted database. dbtool will ask you for the passphrase, unless the environment variable DB_PASSPHRASE is set.

- passphrase

Use encrypted database. Specify the passphrase on the commandline.

-v value

Use value as the value associated with some key. Use -v in conjunction with -i, -u or -r.

-V

Print out the version of dbtool.

-w

Print search results together with the associated keys separated by whitespace or the parameter of -F.

EXPRESSIONS

Regular expressions are provided using the PCRE Library. It supports most of the features which perl provides. See the section DIFFERENCES FROM PERL in the PCRE manpage. You can also take a look to the perl regular expression man page with the following command:

perldoc perlre

(which requires perl to be installed).

ENCRYPTION

As of version 1.4 dbtool supports encrypted databases. See the descriptions of the options -p and -. The algorithm used for encryption is Rijndael block cipher encryption.

dbtool does not use the passphrase which the user supplies. It uses instead the MD5 digest of the passphrase as the encryption key.

Please note, that dbtool itself does not distinguish between encrypted or unencrypted databases. That means, you will get strange results if you try to access an encrypted database without the options -p or - being set.

dbtool by default will only encrypt the values of a database, not the keys. This might change in future versions.

EXAMPLES

dbtool -d test.db -i -k "test" -v "blah blah blah"

Insert the key "test" which is associated to the value "blah blah blah" into test.db.

dbtool -d test.db -u -f -k "test" -v "blubber"

Update the key "test" even if it does not exist with "blubber".

dbtool -d test.db -r -k "test"

Remove the entry to which the key "test" points.

dbtool -d test.db -S -k "^\d\d"

Search for all keys which start at least with two digits.

dbtool -d test.db -D | grep -i "tom"

Dump out the whole database test.db and search for "tom". This method allows you to search for values.

cat /etc/passwd | dbtool -d test.db -i -f -t "^(.+?):.*:(\d+?):$"

In this example we store the contents of the file passwd in a hash database. The username will be the key of an entry and the userid will be the associated value. The key must be any character from the beginning of a line until the first appearance of a colon. The value must be one or more digits after the 2nd colon until the next colon:

apache:x:48:48:Apache:/var/www:/bin/false ^^^^^^ ^^ | | | o--- value | o------------ key

find /home -ls | dbtool -d catalog.dbm -i -f -R -t "^(.+?) (\/.*)$"

In this example the output of the unix command 'find /home -ls' will be used as input for dbtool. The key for an entry will begin on the first appearance of a slash character until the end of the line. Everything in front of it will be the value (because of the -R):

302 12 -rw------- 1 scip scip 9734 Feb 11 2000 /home/scip/D/lrk5/README (---------------[ value ]--------------------------) (--------[ key ]-------)

I use this command in my backup script for creating a catalog of all saved files and it's attributes.

REPORTING BUGS

Report bugs on https://github.com/tlinden/dbtool/issues or mail to .

COPYRIGHT

AVAILABILITY

dbtool can be downloaded from /projects/dbtool/download/.

AUTHORS

T.L.