<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2012  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
    <date>June 20, 2012</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-dbutil</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-dbutil</refname>
    <refpurpose>Zone Database Maintenance Utility</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2012</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-dbutil --check</command>
        <arg>--verbose</arg>
        <arg>--quiet</arg>
        <arg><replaceable choice='req'>dbfile</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>b10-dbutil --upgrade</command>
        <arg>--noconfirm</arg>
        <arg>--verbose</arg>
        <arg>--quiet</arg>
        <arg><replaceable choice='req'>dbfile</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      The <command>b10-dbutil</command> utility is a general
      administration utility for SQL databases for BIND 10. (Currently
      only SQLite is supported by BIND 10.)  It can report the
      current verion of the schema, and upgrade an existing database
      to the latest version of the schema.
    </para>

    <para>
      <command>b10-dbutil</command> operates in one of two modesr: check mode
      or upgrade mode.
    </para>

    <para>
      In check mode (<command>b10-dbutil --check</command>), the
      utility reads the version of the database schema from the database
      and prints it.  It will tell you whether the schema is at the latest
      version supported by BIND 10. Exit status is 0 if the schema is at
      the correct version, 1 if the schema is at an older version, or 2 if
      the schema is at a version not yet supported by this version of
      <command>b10-dbutil</command>.
      Any higher value indicates an error during command-line
      parsing or execution.
    </para>

    <para>
      When the upgrade function is selected
      (<command>b10-dbutil --upgrade</command>), the
      utility takes a copy of the database, then upgrades it to the latest
      version of the schema.  The contents of the database remain intact.
      (The backup file is a file in the same directory as the database
      file.  It has the same name, with ".backup" appended to it.  If a
      file of that name already exists, the file will have the suffix
      ".backup-1".  If that exists, the file will be suffixed ".backup-2",
      and so on). Exit status is 0 if the upgrade is either succesful or
      aborted by the user, and non-zero if there is an error.
    </para>

    <para>
    When upgrading the database, it is <emphasis>strongly</emphasis>
    recommended that BIND 10 not be running while the upgrade is in
    progress.
    </para>

  </refsect1>

  <refsect1>
    <title>ARGUMENTS</title>

    <para>The arguments are as follows:</para>

    <variablelist>
      <varlistentry>
        <term>
         <option>--check</option>
        </term>
        <listitem>
          <para>Selects the version check function, which reports the
          current version of the database.  This is mutually exclusive
          with the <option>--upgrade</option> option.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
         <option>--noconfirm</option>
        </term>
        <listitem>
          <para>Only valid with <option>--upgrade</option>, this disables
          the prompt.
          Normally the utility will print a warning that an upgrade is
          about to take place and request that you type "Yes" to continue.
          If this switch is given on the command line, no prompt will
          be issued and the utility will just perform the upgrade.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
         <option>--upgrade</option>
        </term>
        <listitem>
          <para>Selects the upgrade function, which upgrades the database
          to the latest version of the schema.  This is mutually exclusive
          with the <option>--check</option> option.
          </para>
          <para>
          The upgrade function will upgrade a BIND 10 database &mdash;
          no matter how old the schema &mdash; preserving all data.
	  A backup file is created before the upgrade (with the
	  same name as the database, but with ".backup" suffixed
	  to it).  If the upgrade fails, this file can be copied
	  back to restore the original database.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
         <option>--verbose</option>
        </term>
        <listitem>
          <para>Enable verbose mode.  Each SQL command issued by the
          utility will be printed to STDERR before it is executed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
         <option>--quiet</option>
        </term>
        <listitem>
          <para>Enable quiet mode. No output is printed, except errors during
            command-line argument parsing, or the user confirmation dialog.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
        <option><replaceable choice='req'>dbfile</replaceable></option>
        </term>
        <listitem>
          <para>
          Name of the database file to check or upgrade.
          </para>
        </listitem>
      </varlistentry>


    </variablelist>
  </refsect1>
</refentry>
