]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-xcpdb.pod
doc: add some notes around -xcpdb / -edit / -purge
[public-inbox.git] / 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 --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 =back
56
57 =head1 ENVIRONMENT
58
59 =over 8
60
61 =item PI_CONFIG
62
63 The default config file, normally "~/.public-inbox/config".
64 See L<public-inbox-config(5)>
65
66 =item XAPIAN_FLUSH_THRESHOLD
67
68 The number of documents to update before committing changes to
69 disk.  This environment is handled directly by Xapian, refer to
70 Xapian API documentation for more details.
71
72 Default: 10000
73
74 =back
75
76 =head1 UPGRADING
77
78 This tool is intended for admins upgrading Xapian search databases
79 used by public-inbox, NOT users upgrading public-inbox itself.
80
81 In particular, it DOES NOT upgrade the schema used by the
82 PSGI search interface (see L<public-inbox-index(1)>).
83
84 =head1 LIMITATIONS
85
86 Do not use L<public-inbox-purge(1)> or L<public-inbox-edit(1)>
87 while this is running; old (purged or edited data) may show up.
88
89 Normal invocations L<public-inbox-index(1)> can safely run
90 while this is running, too.  However, reindexing via the
91 L<public-inbox-index(1)/--reindex> switch will be a waste of
92 computing resources.
93
94 =head1 CONTACT
95
96 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
97
98 The mail archives are hosted at L<https://public-inbox.org/meta/>
99 and L<http://hjrcffqmbrq6wope.onion/meta/>
100
101 =head1 COPYRIGHT
102
103 Copyright 2019-2020 all contributors L<mailto:meta@public-inbox.org>
104
105 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
106
107 =head1 SEE ALSO
108
109 L<copydatabase(1)>, L<xapian-compact(1)>, L<public-inbox-index(1)>