<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: upgrading.xml 18226 2013-02-05 21:29:22Z wolfgang_m $ --><book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Upgrade Guide</title><date>November 2009</date><author><firstname>Wolfgang M.</firstname><surname>Meier</surname><affiliation><address format="linespecific"><email>wolfgang at exist-db.org</email></address></affiliation></author></bookinfo><chapter><title>Upgrade Guide</title><section><title>General Information</title><para>Never install a new version of eXist-db into the same directory as an older
                version:</para><procedure><step><para>Create a <ulink url="backup.xml">backup</ulink> of your data. If the new
                        version is <emphasis>binary compatible</emphasis> with the old version, keep
                        the data directory (by default in <filename>webapp/WEB-INF/data</filename>)
                        of the old version. Note: eXist needs to be stopped before copying files
                        from the data dir.</para></step><step><para>Install the new version into a different location.</para></step><step><para>If the new version is <emphasis>binary compatible</emphasis>, replace the
                        data directory of the new install with the one from the old one.</para><para>Otherwise you need to do a full <ulink url="backup.xml#restore">restore</ulink> of the data.</para></step></procedure></section><section><title>Upgrading to 2.0</title><para>The 2.0 release is not binary compatible with the 1.4.x series. You need to
                backup/restore.</para><section><title>Special Notes</title><variablelist><varlistentry><term>Permissions</term><listitem><para>eXist-db 2.0 closely follows the Unix security model (plus ACLs). Permissions have thus
                                changed between 1.4.x and 2.0. In particular, there's now an execute permission, which is
                                required to</para><orderedlist><listitem><para>execute an XQuery via any of eXist-db's interfaces</para></listitem><listitem><para>change into a collection to view or modify its contents</para></listitem></orderedlist><para>eXist-db had an update permission instead of the execute permission. Support for the update permission
                                has been dropped because it was not used widely.</para><para>When restoring data from 1.4.x, you thus need to make sure that:</para><orderedlist><listitem><para>collections have the appropriate execute permission</para></listitem><listitem><para>XQueries are executable</para></listitem></orderedlist><para>You can use an XQuery to automatically apply a default permission to every collection and XQuery, and
                                then change them manually for some collections or resources.</para><programlisting language="xquery">xquery version "3.0";

import module namespace dbutil="http://exist-db.org/xquery/dbutil";

dbutil:find-by-mimetype(xs:anyURI("/db"), "application/xquery", function($resource) {
    sm:chmod($resource, "rwxr-xr-x")
}),
dbutil:scan-collections(xs:anyURI("/db"), function($collection) {
    sm:chmod($collection, "rwxr-xr-x")
})</programlisting></listitem></varlistentry><varlistentry><term>Webapp Directory</term><listitem><para>Contrary to 1.4.x, eXist-db 2.0 stores most web applications into the database. The webapp
                            directory is thus nearly empty. It is still possible to put your web application there and it should
                            be accessible via the browser in the same way as before.</para></listitem></varlistentry></variablelist></section></section><section><title>Upgrading to 1.4.0</title><para>The 1.4 release is not binary compatible with the 1.2.x series. You need to
                backup/restore.</para><section><title>Special Notes</title><variablelist><varlistentry><term>Indexing</term><listitem><para>eXist-db 1.2.x used to create a default full text index on all
                                elements in the db. This has been <emphasis>disabled</emphasis>. The
                                main reasons for this are:</para><orderedlist><listitem><para>maintaining the default index costs performance and
                                        memory, which could be better used for other indexes. The
                                        index may grow very fast, which can be a destabilizing
                                        factor.</para></listitem><listitem><para>the index is unspecific. The query engine cannot use it as
                                        efficiently as a dedicated index on a set of named elements
                                        or attributes. Carefully creating your indexes by hand will
                                        result in much better performance.</para></listitem></orderedlist><para>Please consider using the new Lucene-based full text index.
                                However, if you need to switch back to the old behaviour to ensure
                                backwards compatibility, just edit the system-wide defaults in
                                conf.xml:</para><programlisting><markup>&lt;index&gt;
    &lt;fulltext attributes="false" default="none"&gt;
        &lt;exclude path="/auth"/&gt;
    &lt;/fulltext&gt;
&lt;/index&gt;</markup></programlisting></listitem></varlistentry><varlistentry><term>Document Validation</term><listitem><para>Validation of XML documents during storage is now <emphasis>turned
                                    off by default</emphasis> in <filename>conf.xml</filename>:</para><synopsis language="xml">&lt;validation mode="no"&gt;</synopsis><para>The previous <option>auto</option> setting was apparently too
                                confusing for new users who did not know what to do if eXist refused
                                to store a document due to failing validation. If you are familiar
                                with <ulink url="validation.xml">validation</ulink>, the use of
                                catalog files and the like, feel free to set the default back to
                                    <option>auto</option> or <option>yes</option>.</para></listitem></varlistentry><varlistentry><term>Cocoon</term><listitem><para>eXist-db does no longer require Cocoon for viewing documentation and
                                samples. Cocoon has been largely replaced by eXist's own <ulink url="urlrewrite.xml">URL rewriting and MVC
                                framework</ulink>.</para><para>Consequently, we now limit Cocoon to one directory of the web
                                application (<filename>webapp/cocoon</filename>) and moved all the
                                Cocoon samples in there. For the 1.5 version we completely
                                removed Cocoon support.</para></listitem></varlistentry></variablelist></section></section></chapter></book>