Documentation/public-inbox-xcpdb.pod

   1 =head1 NAME
   2
   3 public-inbox-xcpdb - upgrade Xapian DB formats
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-xcpdb [OPTIONS] INBOX_DIR
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-xcpdb is similar to L<copydatabase(1)> for
  12 upgrading to the latest database format supported by Xapian
  13 (e.g. "glass" or "honey"), but is designed to tolerate and
  14 accept parallel Xapian database modifications from
  15 L<public-inbox-watch(1)>, L<public-inbox-mda(1)>,
  16 L<public-inbox-learn(1)>, and L<public-inbox-index(1)>.
  17
  18 =head1 OPTIONS
  19
  20 =over
  21
  22 =item -c, --compact
  23
  24 In addition to performing the copy operation, run L<xapian-compact(1)>
  25 on each Xapian shard after copying but before finalizing it.
  26 Compared to the cost of copying a Xapian database, compacting a
  27 Xapian database takes only around 5% of the time required to copy.
  28
  29 Compared to L<public-inbox-compact(1)>, use of this option is
  30 preferable for gigantic inboxes where the coarse-grained lock
  31 currently required for L<public-inbox-compact(1)> can cause
  32 the compaction to take hours at-a-time.
  33
  34 =item --reshard=N / -R N
  35
  36 Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
  37 inbox to C<N> shards .  Since L<xapian-compact(1)> is not suitable
  38 for merging, users can rely on this switch to reshard the
  39 existing Xapian database(s) to any positive value of C<N>.
  40
  41 This is useful in case the Xapian DB was created with too few or
  42 too many shards given the capabilities of the current hardware.
  43
  44 =item --blocksize / --no-full / --fuller
  45
  46 These options are passed directly to L<xapian-compact(1)> when
  47 used with C<--compact>.
  48
  49 =item --no-fsync
  50
  51 Disable L<fsync(2)> and L<fdatasync(2)>.
  52
  53 Available in public-inbox 1.6.0 (PENDING).
  54
  55 =item --sequential-shard
  56
  57 Copy each shard sequentially, ignoring C<--jobs>.  This also
  58 affects indexing done at the end of a run.
  59
  60 =item --batch-size=BYTES
  61
  62 =item --max-size=BYTES
  63
  64 See L<public-inbox-index(1)> for a description of these options.
  65
  66 These indexing options indexing at the end of a run.
  67 C<public-inbox-xcpdb> may run in parallel with with
  68 L<public-inbox-index(1)>, and C<public-inbox-xcpdb> needs to
  69 reindex changes made to the old Xapian DBs by
  70 L<public-inbox-index(1)> while it was running.
  71
  72 =back
  73
  74 =head1 ENVIRONMENT
  75
  76 =over 8
  77
  78 =item PI_CONFIG
  79
  80 The default config file, normally "~/.public-inbox/config".
  81 See L<public-inbox-config(5)>
  82
  83 =item XAPIAN_FLUSH_THRESHOLD
  84
  85 The number of documents to update before committing changes to
  86 disk.  This environment is handled directly by Xapian, refer to
  87 Xapian API documentation for more details.
  88
  89 Default: 10000
  90
  91 =back
  92
  93 =head1 UPGRADING
  94
  95 This tool is intended for admins upgrading Xapian search databases
  96 used by public-inbox, NOT users upgrading public-inbox itself.
  97
  98 In particular, it DOES NOT upgrade the schema used by the
  99 PSGI search interface (see L<public-inbox-index(1)>).
 100
 101 =head1 LIMITATIONS
 102
 103 Do not use L<public-inbox-purge(1)> or L<public-inbox-edit(1)>
 104 while this is running; old (purged or edited data) may show up.
 105
 106 Normal invocations L<public-inbox-index(1)> can safely run
 107 while this is running, too.  However, reindexing via the
 108 L<public-inbox-index(1)/--reindex> switch will be a waste of
 109 computing resources.
 110
 111 =head1 CONTACT
 112
 113 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 114
 115 The mail archives are hosted at L<https://public-inbox.org/meta/>
 116 and L<http://hjrcffqmbrq6wope.onion/meta/>
 117
 118 =head1 COPYRIGHT
 119
 120 Copyright 2019-2020 all contributors L<mailto:meta@public-inbox.org>
 121
 122 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 123
 124 =head1 SEE ALSO
 125
 126 L<copydatabase(1)>, L<xapian-compact(1)>, L<public-inbox-index(1)>