dbutil(1)                     Mail Avenger 0.8.1                     dbutil(1)



NAME
       dbutil - database utility

SYNOPSIS
       dbutil {-d | --dump} dbfile

       dbutil {-q | --query} [-t] dbfile key

       dbutil {-u | --update} [-n] dbfile key [value]

       dbutil {-x | --delete} dbfile key

       dbutil -t [date | [+|-]interval]

DESCRIPTION
       The dbutil program maintains a database of key-value pairs that can be
       queried and updated from the command line.  For each such pair in the
       database, it also keeps an expiration time, so that unused entries can
       be purged from the database.  dbutil must be given an option specifying
       in which mode to run the program.  The following modes are available:

       --dump (-d)
           Prints the contents of the database.  Each database entry is
           printed in one of the the following two formats, depending on
           whether the record has an expiration time:

               key value

               key value (expiration-time)

       --query (-q)
           Prints the value of a particular key in the database.  If the -t
           flag is also specified, prints the expiration time of the record.
           In addition, the --expire flag can be specified to update the
           expiration time on the record.  Exits 0 if the key was found, 1 if
           the key was not in the database, or 2 if there is a system error.

       --update (-u)
           Sets the value of a key in the database to a particular value.  If
           no value is supplied, sets the value to the empty string (which is
           not the same as deleting the record).  The --expire flag can also
           be specified to set an expiration time on the record.

           Ordinarily, this option overwrites any previous value in the
           database.  If the -n option is supplied, dbutil will not overwrite
           a previously stored value in the database (and will not update the
           expiration time on the record).  Exits 0 if the key was found, 1 if
           -n was specified and the key was already in the database, or 2 if
           there is a system error.

       --expire={date | [+|-]interval}
           This option can be specified in conjunction with --update or
           --query to set an expiration time on the record.  The option has
           two formats.  You can either specify an absolute time, as the
           number of seconds since Jan 1, 1970 GMT, or you can specify an
           offset from the current time with the format:

               [+|-]countunits

           Where + means in the future, - means in the past, count is a
           number, and units is one of the following characters:

           s - seconds
           m - minutes
           h - hours
           D - days
           W - weeks
           M - months
           Y - years

           For example --expire=+36D means the record will be deleted in 36
           days.  If you always look up key with the command:

               dbutil --query --expire=+36D key

           then the key will only expire if you do not look it up within 36
           days.

           Note that dbutil keeps a sorted list of the records by time of last
           access.  Thus, purging old records is not an inherently expensive
           operation, and happens automatically whenever you modify the
           database.

       --nosync (-N)
           Ordinarily, dbutil synchronously flushes the database file to disk
           after making any modifications, to minimize the window of
           vulnerability in which a crash could corrupt the database (if the
           --dbhome option is not supplied).  Synchronously flushing the
           database file is slow, however.  This option suppresses that
           behavior, and can be used to build lookup tables efficiently.  For
           example, you might have a script that builds a file x.db by issuing
           the following commands:

                   #!/bin/sh -e
                   rm -f x.db~
                   dbutil -Nu x.db~ key1 val1
                   dbutil -Nu x.db~ key2 val2
                   # ...
                   dbutil -Nu x.db~ keyn valn
                   dbutil -u @ @
                   mv -f x.db~ x.db

       --delete (-x)
           Deletes a particular key from the database (if the database
           contains the key).  Exits 0 if the key was found, 1 if the key was
           not in the database, or 2 if there was a system error.

       -t [date|interval]
           With no options, prints the number of seconds since Jan 1, 1970,
           GMT.  With an argument that takes the same format as --expire,
           prints the expiration time as an absolute number of seconds since
           1970.  Not really a database function, but useful hen you want to
           store a timestamp in the database.

           Note that -t can also be combined with the --query option, in which
           case it causes dbutil to print the expiration time of the key,
           rather than its value.

       dbutil attempts to minimize the damage from an inopportune crash by
       flushing the database file to disk whenever it is modified.  However,
       there is still a small window in which your database can be irrevocably
       corrupted.  This may be alright if you are just using the database to
       store "soft state".

       If you want the database to be recoverable under any circumstances, you
       must use write-ahead logging, in which case dbutil needs to keep a
       directory with database logs, not just a single database file.  The
       following option specifies where to keep the log files.  It must be
       used in conjunction with the other options for each mode except -t:

       --dbhome=dbhome
           Specifies that database log files should be kept in directory
           dbhome (which will be created if it does not already exist).  Note
           that database files with relative pathnames will also be stored in
           this directory.  It is highly recommended that you use relative
           pathnames so as to store database files and log files together.
           Otherwise, you run the risk of accessing a logged database without
           the --dbhome option and trashing its contents.

ENVIRONMENT
       DB_HOME
           When set, specifies a directory in which to keep log files, so as
           to make the database crash-recoverable.  This is equivalent to
           specifying the option --dbhome=$DB_HOME (except that any actual
           --dbhome argument will override the environment variable).

SEE ALSO
       avenger(1)

       The Mail Avenger home page: <http://www.mailavenger.org/>.

BUGS
       If you do not use the --dbhome option or DB_HOME environment variable
       and your machine crashes at the wrong time, you can lose your whole
       database.

       The --dbhome may or may not work if the directory is stored on NFS; it
       depends on the NFS implementation.

       If you access the database from multiple machines simultaneously, you
       will likely corrupt the database.  Accessing from multiple processes on
       one machine is fine, because dbutil does locking.

       If you ever access the same database file with and without the --dbhome
       option (or DB_HOME), you will probably irrevocably trash it.  For that
       reason, databases with relative pathnames are actually stored in the
       log directory.

AUTHOR
       David Mazieres



Mail Avenger 0.8.1                2010-04-12                         dbutil(1)
