Not logged in

Artifact 7e968c1ccc18055cb25ebc5de414ea41f4af4fd7:


\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename zeptodb.info
@include version.texi
@settitle zeptodb
@c %**end of header
@copying
This manual is for zeptodb (version @value{VERSION}, updated @value{UPDATED}).

Copyright @copyright{} 2013, 2016  Brandon Invergo

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.

A copy of the license is also available from the Free Software
Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.

@end quotation

The document was typeset with
@uref{http://www.texinfo.org/, GNU Texinfo}.

@end copying

@dircategory System utilities
@direntry
* zeptodb: (zeptodb).  Tiny tools for manipulating DBM databases.
@end direntry

@titlepage
@title zeptodb
@subtitle for version @value{VERSION}, updated @value{UPDATED}
@author Brandon Invergo @email{brandon@@invergo.net}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of the contents at the beginning.
@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top zeptodb

@insertcopying
@end ifnottex

@menu
* Introduction::
* Commands::
* Copying This Manual::
* Index::

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Tutorial::
* Common Options::

Commands

* zdbc::
* zdbs::
* zdbf::
* zdbr::
* zdbi::

Copying This Manual

* GNU Free Documentation License::  License for copying this manual.

@end detailmenu
@end menu

@node Introduction, Commands, Top, Top
@chapter Introduction

zeptodb is a small collection of relatively tiny command-line tools
for interacting with @dfn{DBM databases}.  DBM databases are flat
(non-relational) a databases; in other words, they are persistent
key-value hash tables. Typically they are created via a library for C,
Python, Perl, etc. These tools fill in a gap by providing useful
command-line tools. Some DBM libraries come with really basic binaries
for manipulating the databases, but they are not designed to be very
flexible or useful in the real world.

These tools may be helpful in scripts, for example, when persistant
data storage is needed but when a full database would be overkill.
DBM databases offer a constant look-up time for any record in them, as
opposed to, say, searching through a text file, which scales linearly
with the number of lines in the file.  Thus, scripts requiring fast
data look-up would benefit greatly from them (but note that, of
course, disk access is slower than memory access, so if you really
need the performance and you can fit your table in memory, these are
not the appropriate tools).  These commands may also be useful if, for
whatever reason, one would like to manipulate, via the command-line or
scripts, DBM databases created by other programs.

@menu
* Tutorial::
* Common Options::
@end menu

@node  Tutorial, Common Options, Introduction, Introduction
@section Tutorial

The zeptodb tools are used to create small databases that are stored
to disk and then to store, fetch and remove records from those
databases.  These databases are much simpler than, say, SQL databases,
so no queries need to be constructed.  The databases follow the DBM
format as created by the GDBM library.  Each record in a DBM database
consists of a key and a value.  All keys and values are stored as
plain text, regardless of their formats.

First, you create a new database with @command{zdbc}:

@example
$ zdbc foo.db
@end example

With the database created, you may now store values to it using
@command{zdbs}.  @command{zdbs} normally takes its input from
@file{stdin}.  It expects one record per line and for each key/value
pair to be separated by a delimiter character ('|' by default).  Note
that records are unique: an attempt to store a record with a
pre-existing key will overwrite that record with a new value.

For example, let's say that you have a text file @file{emails.txt}
containing the following records:

@example
Brandon|foo@@example.com
Joe|bar@@example.com
Mary|baz@@example.com
@end example

You could store the records in @file{foo.db} like so:

@example
$ zdbs foo.db <emails.txt
@end example

Note that if you simply don't like shell redirections like this, you can
also use the @option{-i} or @option{--input} option to specify the input
file:

@example
$ zdbs -i emails.txt foo.db
@end example

Of course, it's more likely that you'll want to pipe in records from
some other process:

@example
$ fancy_pipeline.sh | zdbs foo.db
@end example

If your records are formatted differently, using, say, '-' as the
delimiter (i.e "key-value"), you would specify it using the @option{-d}
or @option{--delimiter} option.

Records can then be fetched from the database using @command{zdbf}.  In
this case, queries in the form of keys with one key per line are read
from @file{stdin}:

@example
$ zdbf foo.db
Brandon
foo@@example.com
Joe
bar@@example.com
Jon
../trunk/src/zdbf: Key does not exist in the database: Jon: Invalid argument
@end example

As with @command{zdbs}, you can also specify a file containing the
queries using the @option{-i} option or you can read them in through a
pipe.

If you would prefer the output to include the key, you must specify your
desired delimiter using the @option{-d} option:

@example
$ echo Brandon | zdbf -d':' foo.db
Brandon:foo@@example.com
@end example

Finally, you can dump out all of the contents of the database using the
@option{-a} option.  Note that the order of the records is in no way
guaranteed.

@example
$ zdbf -d'|' -a foo.db
Joe|bar@@example.com
Brandon|foo@@example.com
Mary|baz@@example.com
@end example

Records may then be removed from the database using @command{zdbr}.
@command{zdbr} operates in a very similar way to @command{zdbf}:

@example
$ zdbr foo.db <<EOF
> Brandon
> Joe
> EOF
$ zdbf -a -d'|' foo.db
Mary|baz@@example.com
@end example

Of course, these examples are not realistic.  Rather than using the
programs from the command-line, you are more likely to use them in
scripts.  For example, one script might save data to a database while
another script reads from that data.  You can even build up relations
between multiple databases, storing the keys of one database as values
in another database, allowing quite complex, but always fast, look-ups
within your scripts.

@node Common Options,  , Tutorial, Introduction
@section Common Options

The following options are available for all zeptodb commands.

@table @option
@item -b, --block-size=NUM
The block size (in bytes) to be used, representing the size of a
transfer from disk to memory.  The default value is 512.

@item -m, --mmap-size=NUM
The size (in bytes) of the memory-mapped region to be used.  With a
value greater than zero, a memory map of the database will be created;
thus the size specified must be large enough to fit the entire
database.

@item -c, --cache-size=NUM
The size (in bytes) of the bucket cache size to be used.

@item -l, --no-lock
Do not perform file locking an the database.

@item -n, --no-mmap
Do not create a memory map of the database.

@item -v, --verbose
Print more run-time information.

@item -?, --help
Show helpful information.

@item --usage
Show shorter helpful information.

@item -V, --version
Print the program version.
@end table


@node Commands, Copying This Manual, Introduction, Top
@chapter Commands

Five commands are provided with zeptodb: @command{zdbc}, for creating
databases, @command{zdbs} for storing records in them, @command{zdbf},
for fetching records, @command{zdbr}, for removing records, and
@command{zdbi} for displaying information about a database.

@menu
* zdbc::
* zdbs::
* zdbf::
* zdbr::
* zdbi::
@end menu


@node zdbc, zdbs, Commands, Commands
@section zdbc

@command{zdbc} is used to create a new database file.  It accepts all
of the common options.  Running the command on an existing database
will @emph{overwrite} the existing contents!

In addition to the database file to be used and the common options,
the @command{zdbc} command accepts the following options:

@table @option
@item -s, --sync
Automatically synchronize all database operations to the disk.
@end table

@node zdbs, zdbf, zdbc, Commands
@section zdbs

@command{zdbs} is used to store records in a database file.  Records
are entered via @file{stdin} or, optionally, they are read from an
input file, with one record per line.  Each record should consist of
one key-value pair.  The values should be separated from the keys by a
common delimiter ('|' by default), for example ``key|value''.

In addition to the database file to be used and the common options,
the @command{zdbs} command accepts the following options:

@table @option
@item -d, --delim=CHAR
Delimiter character separating keys from values (default '|').

@item -i, --input=FILE
Read new records from a file instead of from @file{stdin}.

@item -s, --sync
Automatically synchronize all database operations to the disk.
@end table

@node zdbf, zdbr, zdbs, Commands
@section zdbf

@command{zdbf} is used to fetch records from a database file.  Queries
are read from @file{stdin} or, optionally, from a text file.  Records
with key values that match the queries will be printed to
@file{stdout}.  By default, only the corresponding values will be
printed.  However, if a delimiter character is provided, both keys and
values will be printed.  Finally, an option is available to simply
print all records in the database.

In addition to the database file to be used and the common options,
the @command{zdbf} command accepts the following options:

@table @option
@item -a, --all
Fetch all the records in the database.

@item -d, --delim=CHAR
Delimiter character to separate printed keys from values (default
none; only values will be printed).

@item -i, --input=FILE
Read queries from a file instead of from @file{stdin}.
@end table

@node zdbr, zdbi, zdbf, Commands
@section zdbr

@command{zdbr} is used to remove records from a database.  The records
to be removed are specified by their keys and are entered via
@file{stdin} or, optionally, they are read from a text file.  If many
records are removed from the database, some fragmentation can occur.
In this case, it is advisable to reorganize the database, which is
possible via the @option{--reorganize} option.

In addition to the database file to be used and the common options,
the @command{zdbf} command accepts the following options:

@table @option
@item -i, --input=FILE
Read queries from a file instead of from @file{stdin}.

@item -r, --reorganize
Reorganize the database.

@item -s, --sync
Automatically synchronize all database operations to the disk.
@end table

@node zdbi,  , zdbr, Commands
@section zdbi

@command{zdbi} prints out information on a database file.  It accepts
the common options.

@node Copying This Manual, Index, Commands, Top
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@node GNU Free Documentation License,  , Copying This Manual, Copying This Manual
@section GNU Free Documentation License
@include fdl.texi

@node Index,  , Copying This Manual, Top
@unnumbered Index

@printindex cp

@bye

@c zeptodb.texi ends here