@c This file is part of the Mailfromd manual.
@c Copyright (C) 2011--2025 Sergey Poznyakoff
@c See file mailfromd.texi for copying conditions.
@c *******************************************************************
@pindex mfdbtool
The @command{mfdbtool} utility manages @command{mailfromd} databases.

@menu
* Invoking mfdbtool::
* Configuring mfdbtool::
@end menu

@node Invoking mfdbtool
@section Invoking @command{mfdbtool}

The following options request the operation to be performed on the
database.  Exactly one of them must be specified.  Each of them
implied the @option{--stderr} option (@pxref{--stderr}).

@table @option
@opsummary{list, mfdbtool}
@item  --list
List the database.  By default, @samp{cache} database is assumed.  To
list another database, use @option{--format} option
(@pxref{--format}).

@xref{Basic Database Operations}.

@opsummary{delete, mfdbtool}
@item --delete
Delete given entries from the database (@pxref{deleting from
databases}).  By default, @samp{cache} database is assumed.  To
specify another database, use @option{--format} option (@pxref{--format}).  

@xref{Basic Database Operations}.

@opsummary{expire, mfdbtool}
@item --expire
Delete all expired entries from the database (@pxref{Database
Maintenance}).  By default, @samp{cache} database is assumed.  To
specify another database, use @option{--format} option
(@pxref{--format}).  Full database name can be given in the command
line (see @option{--file} option below), if it differs from the one
specified in the script file. 

Use with the option @option{--all} (@pxref{--all}) to expire all databases.

@xref{Database Maintenance}.

@opsummary{compact, mfdbtool}
@item --compact
Compact database (@pxref{compaction}).  By default, @samp{cache}
database is compacted.  To specify another database, use
@option{--format} option (@pxref{--format}).  Full database name can
be given in the command line (see @option{--file} option below), if it
differs from the one specified in the script file.

Use with the option @option{--all} (@pxref{--all}) to compact all
databases.

@xref{compaction}.
@end table

The following options modify the behavior of @command{mfdbtool}:

@table @option
@opsummary{all, mfdbtool}
@item --all
When used with @option{--compact} or @option{--expire} option, applies
the action to all available databases.  @xref{compact cronjob}.

@opsummary{debug, mfdbtool}
@item -d @var{string}
@itemx --debug=@var{string}
Sets debugging level.  The @var{string} argument must be a valid
mailfromd debug level specification, as described in @ref{debugging
level specification}.

@opsummary{expire-interval, mfdbtool}
@item -e @var{interval}
@itemx --expire-interval=@var{interval}
Set expiration intervals for all databases to the specified interval.
@xref{time interval specification}, for a description of
@var{interval} format.  The option overrides the
@code{expire-interval} configuration statement
(@pxref{expire-interval-conf}), which you are advised to use instead.

@opsummary{file, mfdbtool}
@item -f @var{filename}
@itemx --file=@var{filename}
Set the name of the database to operate upon (for @option{--compact},
@option{--delete}, @option{--expire}, and @option{--list} options).
Useful if, for some reason, you need to operate on a database whose
file name does not match the one @command{mfdbtool} is configured to
use. 

@opsummary{format, mfdbtool}
@item -H @var{dbformat}
@itemx --format=@var{dbformat}
Use database of the given format, instead of the default
@samp{cache}.  @xref{Basic Database Operations}.

@opsummary{ignore-failed-reads, mfdbtool}
@item --ignore-failed-reads
Ignore records that cannot be retrieved while compacting the
database.  Without this option, @command{mfdbtool} will abort the
compaction if any such error is encountered.

@opsummary{predict, mfdbtool}
@item --predict=@var{rate-limit}
Used with @option{--list} enables printing of the estimated times of
sending along with the @samp{rate} database dump.  Implies
@option{--list --format=rate}.  @xref{estimated time of sending}.

@opsummary{state-directory, mfdbtool}
@item --state-directory=@var{dir}
Sets program state directory.  @xref{statedir, Local state directory}, for
the description of this directory and its purposes.  This option
overrides the @code{state-directory} configuration statement,
described in @ref{conf-base, state-directory}.

@opsummary{time-format, mfdbtool}
@item --time-format=@var{format}
Set format to be used for timestamps in listings, produced by
@option{--list}.  The @var{format} is any valid @code{strftime} format
string, see @ref{Time and Date Formats}, for a detailed description.
The default @var{format} is @samp{%c} (@pxref{%c time format}).  To
analyze @kbd{mfdbtool --list} output using text tools, such as
@code{awk} or @code{grep}, the following format might be useful:
@samp{%s} (@pxref{%s time format}).  Another format I find useful is
@samp{%Y-%m-%d_%H:%M:%S}. 

@end table

@node Configuring mfdbtool
@section Configuring @command{mfdbtool}
Configuration settings are read from the @file{/etc/mailfromd.conf}
file (@pxref{Mailfromd Configuration}).  The following statements are
understood:

@multitable @columnfractions 0.3 0.6
@headitem Statement @tab Reference
@item @code{database} @tab @xref{conf-database}.
@item @code{database-mode} @tab @xref{conf-database,database-mode}.
@item @code{database-type} @tab @xref{conf-database,database-type}.
@item @code{debug} @tab @xref{conf-calloutd-log}.
@item @code{lock-retry-count} @tab @xref{conf-database, lock-retry-count}.
@item @code{lock-retry-timeout} @tab @xref{conf-database, lock-retry-timeout}.
@item @code{state-directory} @tab @xref{conf-calloutd-setup, state-directory}.
@end multitable
