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