unpack
------

.. versionadded:: 2.1.0

Unpack a datadir archive for MySQL.

This expects a .tar or .xb based file archive of a MySQL datadir, whose paths
are relative to the MySQL datadir.  Such archives might be generated by
Percona XtraBackup or other LVM based backup utilities.

Usage
.....

.. code-block:: bash

   Usage: dbsake unpack [options] <path>
   
     Unpack a MySQL backup archive.
   
     This command will unpack tar or Percona XtraBackup xbstream archives with
     support for filtering and extracting only a subset of tables.
   
   Options:
     -l, --list-contents             List the contents of the archive, but don't
                                     extract.
     --progress / --no-progress      Enable/disable progress bar when unpacking.
     -C, --directory <path>          Directory to output to (default: $PWD)
     -t, --table <db.table>          Only extract table datafiles matching
                                     specified database.table glob patterns.
     -T, --exclude-table <db.table>  Exclude table data files matching specified
                                     databsae.table glob patterns.
     -?, --help                      Show this message and exit.

Example
.......

.. code-block:: bash

   $ dbsake unpack -C /data/mysql/ < backup.xb.gz
   ...

Options
.......

.. program:: unpack

.. option:: -l, --list-contents

   List the contents of the archive but do not extract any file contents.
   Each file path will be output to stdout.  Table inclusion/exclusion
   options are honored and any excluded table will not output.

.. option:: --progress / --no-progress

   Enable or disable (respectively) progress bar output. This outputs
   a bar on stderr indicating how much data has been read thus far,
   and, if known, an estimated ETA until completion.

   If stderr appears to be a TTY (i.e. isatty(3) is true for stderr),
   progress wil be enabled by default.

.. option:: -C, --directory <path>

   Output all archived files relative to <path>.

   <path> defaults to the current working directory.

.. option:: -t, --table <glob>

   Restricted extracted table data files to those who
   match a database.tablename glob.  This matching is
   done against the decoded tablename so paths like
   foo@002dbar/foo@002dbaz would be filtered with
   a pattern like 'foo-bar.foo-baz'.

   This option may be specified multiple times. A table
   is included if it matches at least one include pattern
   and does not match any exclude patterns.

   Note: mysql.* is always enabled regardless of this
   option. To exclude the mysql schema, a specified
   --exclude-table option should be used.

.. option:: -T, --table <glob>

   Restricted extracted table data files to those who
   do NOT match a database.tablename glob.  This matching
   is done against the decoded tablename after processing
   the MySQL filename encoding and after removing any
   relative extensions or partitioning information from
   the filename.

   This option may be specified multiple times.  A table
   is extracted if it matches at least one include option
   (if any are specified) and does not match any exclude
   options.

.. option:: [path]

   Path to the archive to process. This defaults to stdin
   but the unpack command will refuse to process input
   from a tty.  You must redirect stdin with a valid
   archive file or specify a path to a valid archive.

   Unpack supports both xbstream format files (as generated
   by Percona XtraBackup) and tar format files. All paths
   are assumed to be relative to the datadir (similar to
   archives generated by Percona XtraBackup or various Holland
   Backup Manager plugins).  dbsake will transparently
   decompress input archives - currently gzip, bzip2,
   lzop and xz extension are supported, provided the
   decompression utilities are available on $PATH.
