Skip to content

Commit b6275ee

Browse files
wolfgangmmwolfgangmm
authored
Merge pull request #144 from eXist-db/DP-upgrade-upgrade
further tweaks to upgrading
2 parents 2a52c75 + 64dc987 commit b6275ee

File tree

4 files changed

+321
-192
lines changed

4 files changed

+321
-192
lines changed

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
<groupId>org.exist-db</groupId>
1414
<artifactId>exist-documentation</artifactId>
15-
<version>0.6.0-SNAPSHOT</version>
15+
<version>3.0.0-SNAPSHOT</version>
1616

1717
<name>eXist-db Documentation</name>
1818
<description>Documentation package for eXist-db</description>

‎src/main/xar-resources/data/backup.xml‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<bookinfo>
44
<productname>eXist-db – Open Source Native XML Database</productname>
55
<title>Database Backup and Restore</title>
6-
<date>August 2012</date>
6+
<date>27-11-2017</date>
77
<author>
88
<firstname>Wolfgang M.</firstname>
99
<surname>Meier</surname>
@@ -28,7 +28,10 @@
2828
<title>Backup Format</title>
2929
<para>During backup, eXist-db exports the contents of its database (as standard XML files)
3030
to a hierarchy of directories on the hard drive. This hierarchy is organized
31-
according to the organization of collections in the database.</para>
31+
according to the organization of collections in the database.</para>
32+
<para>The location of the backup files depends on backup method (s.b.). Backups via the dashboard,
33+
or via XQuery write backups into the <code>export</code> directory inside the data directory of the eXist instance.
34+
The Emergency Backup Tool writes into <code>$EXIST_HOME/export</code> unless configured otherwise.</para>
3235
<para>Other files stored during backup include index configuration files and user
3336
settings. Resource and collection metadata is exported to a special XML file, called
3437
<filename>__contents__.xml</filename>, which lists information including the
@@ -47,12 +50,19 @@
4750
all your users, you can simply edit the file <filename>users.xml</filename> by
4851
removing the <option>password</option> attribute, or set it to a default value and
4952
restore the document.</para>
53+
<para>During backups eXist first runs a consistency check on the database,
54+
trying to identify potential issues in the internal storage structure.
55+
Based on the result of the check, the backup task attempts to rescue as much data as possible, working around any detected issues.</para>
5056
<note>
5157
<para> When migrating to a new eXist-db version, take care to use a version of the
5258
client corresponding to your server version. Usually, the backup process is
5359
backwards compatible. However, using a newer client version to create the backup
5460
from a server running an older version may sometimes lead to unexpected
5561
problems.</para>
62+
<para>The backup files include a report. Normally this just contains the list of collections which were backed up.If you notice any warnings or errors,
63+
it is especially important that you perform a “full restore” of your backed-up data onto the new installation of eXist,
64+
as described in the <ulink url="backup.xml#restore">following steps.</ulink>
65+
</para>
5666
</note>
5767
<important>
5868
<para>Due to limitations of the ZIP format, please make sure the size of your zipped backup does
@@ -393,7 +403,7 @@
393403
</step>
394404
<step>
395405
<para>Change into directory <filename>EXIST_HOME/webapp/WEB-INF/data</filename> or another directory you
396-
specified as data directory in the configuration (conf.xml). </para>
406+
specified as data directory in the configuration (conf.xml).</para> <!--new users don't know what or where (conf.xml) DP-->
397407
</step>
398408
<step>
399409
<para>Remove all <filename>.dbx</filename>, <filename>.lck</filename> and

‎src/main/xar-resources/data/incompatibilities.xml‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
<!-- $Id$ -->
2+
<book>
3+
<bookinfo>
4+
<productname>eXist-db – Open Source Native XML Database</productname>
5+
<title>Incompatibilties</title>
6+
<date>27-11-2017</date>
7+
<author>
8+
<firstname>Duncan</firstname>
9+
<surname>Paterson</surname>
10+
</author>
11+
</bookinfo>
12+
<chapter>
13+
<title>Known Issues for Binary Non-compatible Upgrades</title>
14+
<section id="v3.0.0">
15+
<title>Upgrading to 3.0 stable</title>
16+
<para>eXist-db v3.0 is not binary compatible with previous versions of eXist-db; the on-disk database file format has been updated, users should perform a full backup and restore to migrate their data.</para>
17+
<para>eXist.db v3.0 and subsequent versions now require <emphasis>Java 8</emphasis>; Users must update to Java 8!</para>
18+
<para>3.0 removes the the legacy Full Text Index and the text (http://exist-db.org/xquery/text) XQuery module. Users should now look toward <code>fn:analyze-string</code>, e.g.
19+
<orderedlist>
20+
<listitem>
21+
<para>instead of using <code>text:groups()</code> use <code>analyze-string()//fn:group</code>,</para>
22+
</listitem>
23+
<listitem>
24+
<para>instead of <code>text:filter("apparat", "([pr])")</code> use <code>analyze-string("apparat", "([pr])")//fn:match/string())</code>.</para>
25+
</listitem>
26+
</orderedlist>
27+
</para>
28+
<para>Furthermore, the SOAP APi, SOAP server, and XACML Security features were removed.</para>
29+
<para>The versioning extension is now available as a separate <ulink url="https://github.com/eXist-db/xquery-versioning-module">EXPATH package</ulink>
30+
</para>
31+
<para>XQueryService has been moved from <code>DBBroker</code> to <code>BrokerPool</code>.</para>
32+
<para>EXPath packages that incorporate Java libraries may no longer work with eXist-db v3.0 and may need to be recompiled for our API changes; packages should now explicitly specify the eXist-db versions that they are compatible with.</para>
33+
<para>eXist-db v3.0 is the culmination of almost 1,500 changes. For more information on new features head to the <ulink url="http://exist-db.org/exist/apps/wiki/blogs/eXist//eXist-db-v3">blog</ulink>.</para>
34+
</section>
35+
<section id="v2.2">
36+
<title>Upgrading to 2.2 final</title>
37+
<para>The 2.2 release is not binary compatible with the 1.4.x series. You need to
38+
backup/restore. If you experience problems with user logins after the restore, please restart eXist-db.</para>
39+
<para>2.2 introduces a <emphasis>new range index module</emphasis>. Old index definitions will still work though as we made sure to keep backwards
40+
compatible. If you would like to upgrade to the new index, check its <ulink url="newrangeindex.xml">documentation</ulink>.</para>
41+
<para>The XQuery engine has been updated to support the changed syntax for <emphasis>maps in XQuery 3.1</emphasis>. The query parser will still accept the
42+
old syntax for map constructors though (<code>map { x:= "y"}</code> instead of <code>map { x: "y" }</code> in XQuery 3.1), so old
43+
code should run without modifications. All map module functions from XQuery 3.1 are
44+
<ulink url="{fundocs}/view.html?uri=http://www.w3.org/2005/xpath-functions/map&amp;location=java:org.exist.xquery.functions.map.MapModule">available</ulink>.</para>
45+
<para>The signatures for some <emphasis>higher-order utility functions</emphasis> like fn:filter, fn:fold-left and fn:fold-right have changed as well. Please review your
46+
use of those functions. Also, fn:map is now called fn:for-each, though the old name is still accepted.</para>
47+
<para>The bundled Lucene has been upgraded from 3.6.1
48+
to 4.4 with this release. Depending on what Lucene
49+
analyzers you are using you need to change the
50+
classnames in your
51+
<filename>collection.xconf</filename>s. E.g. KeywordAnalyzer
52+
and WhitespaceAnalyzer has moved into package
53+
<filename>org.apache.lucene.analysis.core</filename>. Thus
54+
change, any occurrence of
55+
<filename>org.apache.lucene.analysis.WhitespaceAnalyzer</filename>
56+
into
57+
<filename>org.apache.lucene.analysis.core.WhitespaceAnalyzer</filename>
58+
and all other moved classes in the collection
59+
configurations and make sure you reindex your data
60+
before use. You get an error notice in the
61+
<filename>exist.log</filename> if you overlooked any
62+
occurrences.</para>
63+
</section>
64+
<section id="v2.1">
65+
<title>Upgrading to 2.1</title>
66+
<para>The 2.1 release is not binary compatible with the 1.4.x series. You need to
67+
backup/restore. 2.1 is binary compatible with 2.0 though.</para>
68+
</section>
69+
<section id="v2.0">
70+
<title>Upgrading to 2.0</title>
71+
<para>The 2.0 release is not binary compatible with the 1.4.x series. You need to
72+
backup/restore.</para>
73+
<section>
74+
<title>Special Notes</title>
75+
<variablelist>
76+
<varlistentry>
77+
<term>Permissions</term>
78+
<listitem>
79+
<para>eXist-db 2.0 closely follows the Unix security model (plus ACLs). Permissions have thus
80+
changed between 1.4.x and 2.0. In particular, there's now an execute permission, which is
81+
required to</para>
82+
<orderedlist>
83+
<listitem>
84+
<para>execute an XQuery via any of eXist-db's interfaces</para>
85+
</listitem>
86+
<listitem>
87+
<para>change into a collection to view or modify its contents</para>
88+
</listitem>
89+
</orderedlist>
90+
<para>eXist-db had an update permission instead of the execute permission. Support for the update permission
91+
has been dropped because it was not used widely.</para>
92+
<para>When restoring data from 1.4.x, you thus need to make sure that:</para>
93+
<orderedlist>
94+
<listitem>
95+
<para>collections have the appropriate execute permission</para>
96+
</listitem>
97+
<listitem>
98+
<para>XQueries are executable</para>
99+
</listitem>
100+
</orderedlist>
101+
<para>You can use an XQuery to automatically apply a default permission to every collection and XQuery, and
102+
then change them manually for some collections or resources.</para>
103+
<programlisting language="xquery">xquery version "3.0";
104+
105+
import module namespace dbutil="http://exist-db.org/xquery/dbutil";
106+
107+
dbutil:find-by-mimetype(xs:anyURI("/db"), "application/xquery", function($resource) {
108+
sm:chmod($resource, "rwxr-xr-x")
109+
}),
110+
dbutil:scan-collections(xs:anyURI("/db"), function($collection) {
111+
sm:chmod($collection, "rwxr-xr-x")
112+
})</programlisting>
113+
</listitem>
114+
</varlistentry>
115+
<varlistentry>
116+
<term>Webapp Directory</term>
117+
<listitem>
118+
<para>Contrary to 1.4.x, eXist-db 2.0 stores most web applications into the database. The webapp
119+
directory is thus nearly empty. It is still possible to put your web application there and it should
120+
be accessible via the browser in the same way as before.</para>
121+
</listitem>
122+
</varlistentry>
123+
</variablelist>
124+
</section>
125+
</section>
126+
<section id="v1.4">
127+
<title>Upgrading to 1.4.0</title>
128+
<para>The 1.4 release is not binary compatible with the 1.2.x series. You need to
129+
backup/restore.</para>
130+
<section>
131+
<title>Special Notes</title>
132+
<variablelist>
133+
<varlistentry>
134+
<term>Indexing</term>
135+
<listitem>
136+
<para>eXist-db 1.2.x used to create a default full text index on all
137+
elements in the db. This has been <emphasis>disabled</emphasis>. The
138+
main reasons for this are:</para>
139+
<orderedlist>
140+
<listitem>
141+
<para>maintaining the default index costs performance and
142+
memory, which could be better used for other indexes. The
143+
index may grow very fast, which can be a destabilizing
144+
factor.</para>
145+
</listitem>
146+
<listitem>
147+
<para>the index is unspecific. The query engine cannot use it as
148+
efficiently as a dedicated index on a set of named elements
149+
or attributes. Carefully creating your indexes by hand will
150+
result in much better performance.</para>
151+
</listitem>
152+
</orderedlist>
153+
<para>Please consider using the new Lucene-based full text index.
154+
However, if you need to switch back to the old behaviour to ensure
155+
backwards compatibility, just edit the system-wide defaults in
156+
conf.xml:</para>
157+
<programlisting>
158+
<markup>&lt;index&gt;
159+
&lt;fulltext attributes="false" default="none"&gt;
160+
&lt;exclude path="/auth"/&gt;
161+
&lt;/fulltext&gt;
162+
&lt;/index&gt;</markup>
163+
</programlisting>
164+
</listitem>
165+
</varlistentry>
166+
<varlistentry>
167+
<term>Document Validation</term>
168+
<listitem>
169+
<para>Validation of XML documents during storage is now <emphasis>turned
170+
off by default</emphasis> in <filename>conf.xml</filename>:</para>
171+
<synopsis language="xml">&lt;validation mode="no"&gt;</synopsis>
172+
<para>The previous <option>auto</option> setting was apparently too
173+
confusing for new users who did not know what to do if eXist-db refused
174+
to store a document due to failing validation. If you are familiar
175+
with <ulink url="validation.xml">validation</ulink>, the use of
176+
catalog files and the like, feel free to set the default back to
177+
<option>auto</option> or <option>yes</option>.</para>
178+
</listitem>
179+
</varlistentry>
180+
<varlistentry>
181+
<term>Cocoon</term>
182+
<listitem>
183+
<para>eXist-db does no longer require Cocoon for viewing documentation and
184+
samples. Cocoon has been largely replaced by eXist-db's own <ulink url="urlrewrite.xml">URL rewriting and MVC
185+
framework</ulink>.</para>
186+
<para>Consequently, we now limit Cocoon to one directory of the web
187+
application (<filename>webapp/cocoon</filename>) and moved all the
188+
Cocoon samples in there. For the 1.5 version we completely
189+
removed Cocoon support.</para>
190+
</listitem>
191+
</varlistentry>
192+
</variablelist>
193+
</section>
194+
</section>
195+
</chapter>
196+
</book>

0 commit comments

Comments
 (0)