mirror of https://gitee.com/bigwinds/arangodb
added Chapters for Upgrading to 2.6. Contains information about breaking changes in AQL Graph functions. Also contains information about V8 which has to be updated
This commit is contained in:
Michael Hackstein
parent
0b8e9eb59c
commit
969c89fd4c
|
|
@ -0,0 +1,109 @@
|
|||
!CHAPTER Upgrading to ArangoDB 2.5
|
||||
|
||||
Please read the following sections if you upgrade from a previous version to
|
||||
ArangoDB 2.5. Please be sure that you have checked the list of [changes in 2.5](../Upgrading/UpgradingChanges25.html)
|
||||
before upgrading.
|
||||
|
||||
Please note first that a database directory used with ArangoDB 2.5
|
||||
cannot be used with earlier versions (e.g. ArangoDB 2.4) any
|
||||
more. Upgrading a database directory cannot be reverted. Therefore
|
||||
please make sure to create a full backup of your existing ArangoDB
|
||||
installation before performing an upgrade.
|
||||
|
||||
!SECTION Database Directory Version Check and Upgrade
|
||||
|
||||
ArangoDB will perform a database version check at startup. When ArangoDB 2.6
|
||||
encounters a database created with earlier versions of ArangoDB, it will refuse
|
||||
to start. This is intentional.
|
||||
|
||||
The output will then look like this:
|
||||
|
||||
```
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': Database directory version (20501) is lower than current version (20600).
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': ----------------------------------------------------------------------
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': It seems like you have upgraded the ArangoDB binary.
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': If this is what you wanted to do, please restart with the
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': --upgrade
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': option to upgrade the data in the database directory.
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': Normally you can use the control script to upgrade your database
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': /etc/init.d/arangodb stop
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': /etc/init.d/arangodb upgrade
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': /etc/init.d/arangodb start
|
||||
2015-02-17T09:43:11Z [8302] ERROR In database '_system': ----------------------------------------------------------------------
|
||||
2015-02-17T09:43:11Z [8302] FATAL Database '_system' needs upgrade. Please start the server with the --upgrade option
|
||||
```
|
||||
|
||||
To make ArangoDB 2.6 start with a database directory created with an earlier
|
||||
ArangoDB version, you may need to invoke the upgrade procedure once. This can
|
||||
be done by running ArangoDB from the command line and supplying the `--upgrade`
|
||||
option.
|
||||
|
||||
Note: here the same database should be specified that is also specified when
|
||||
arangod is started regularly. Please do not run the `--upgrade` command on each
|
||||
individual database subfolder (named `database-<some number>`).
|
||||
|
||||
For example, if you regularly start your ArangoDB server with
|
||||
|
||||
unix> arangod mydatabasefolder
|
||||
|
||||
then running
|
||||
|
||||
unix> arangod mydatabasefolder --upgrade
|
||||
|
||||
will perform the upgrade for the whole ArangoDB instance, including all of its
|
||||
databases.
|
||||
|
||||
Starting with `--upgrade` will run a database version check and perform any
|
||||
necessary migrations. As usual, you should create a backup of your database
|
||||
directory before performing the upgrade.
|
||||
|
||||
The last line of the output should look like this:
|
||||
```
|
||||
2014-12-22T12:03:31Z [12026] INFO database upgrade passed
|
||||
```
|
||||
|
||||
Please check the full output the `--upgrade` run. Upgrading may produce errors, which need
|
||||
to be fixed before ArangoDB can be used properly. If no errors are present or
|
||||
they have been resolved manually, you can start ArangoDB 2.5 regularly.
|
||||
|
||||
!SECTION Upgrading a cluster planned in the web interface
|
||||
|
||||
A cluster of ArangoDB instances has to be upgraded as well. This
|
||||
involves upgrading all ArangoDB instances in the cluster, as well as
|
||||
running the version check on the whole running cluster in the end.
|
||||
|
||||
We have tried to make this procedure as painless and convenient for you.
|
||||
We assume that you planned, launched and administrated a cluster using the
|
||||
graphical front end in your browser. The upgrade procedure is then as
|
||||
follows:
|
||||
|
||||
1. First shut down your cluster using the graphical front end as
|
||||
usual.
|
||||
|
||||
2. Then upgrade all dispatcher instances on all machines in your
|
||||
cluster using the version check as described above and restart them.
|
||||
|
||||
3. Now open the cluster dash board in your browser by pointing it to
|
||||
the same dispatcher that you used to plan and launch the cluster in
|
||||
the graphical front end. In addition to the usual buttons
|
||||
"Relaunch", "Edit cluster plan" and "Delete cluster plan" you will
|
||||
see another button marked "Upgrade and relaunch cluster".
|
||||
|
||||
4. Hit this button, your cluster will be upgraded and launched and
|
||||
all is done for you behind the scenes. If all goes well, you will
|
||||
see the usual cluster dash board after a few seconds. If there is
|
||||
an error, you have to inspect the log files of your cluster
|
||||
ArangoDB instances. Please let us know if you run into problems.
|
||||
|
||||
There is an alternative way using the `ArangoDB` shell. Instead of
|
||||
steps 3. and 4. above you can launch `arangosh`, point it to the dispatcher
|
||||
that you have used to plan and launch the cluster using the option
|
||||
``--server.endpoint``, and execute
|
||||
|
||||
arangosh> require("org/arangodb/cluster").Upgrade("root","");
|
||||
|
||||
This upgrades the cluster and launches it, exactly as with the button
|
||||
above in the graphical front end. You have to replace `"root"` with
|
||||
a user name and `""` with a password that is valid for authentication
|
||||
with the cluster.
|
||||
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
!CHAPTER Incompatible changes in ArangoDB 2.6
|
||||
|
||||
It is recommended to check the following list of incompatible changes **before**
|
||||
upgrading to ArangoDB 2.6, and adjust any client programs if necessary.
|
||||
|
||||
|
||||
!SECTION Changed behavior
|
||||
|
||||
!SUBSECTION AQL Graphs
|
||||
|
||||
In 2.6 the graph functions did undergo a performance lifting.
|
||||
During this process we had to adopt the result format and the options for some of them.
|
||||
In general all graph functions now have an option `includeData` which allows to trigger
|
||||
if the result of this function should contain fully extracted documents `includeData: true`
|
||||
or only the `_id` values `includeData: false`.
|
||||
In most use cases the `_id` is sufficient to continue and the extraction of data is an unnecessary
|
||||
operation.
|
||||
Furthermore the result `SHORTEST_PATH` has changed. The old format returned a list of all vertices on the path.
|
||||
Optionally it could include each sub-path for these vertices.
|
||||
All of the documents were fully extracted.
|
||||
Example:
|
||||
```
|
||||
[
|
||||
{
|
||||
vertex: {
|
||||
_id: "vertex/1",
|
||||
_key: "1",
|
||||
_rev: "1234"
|
||||
name: "Alice"
|
||||
},
|
||||
path: {
|
||||
vertices: [
|
||||
{
|
||||
_id: "vertex/1",
|
||||
_key: "1",
|
||||
_rev: "1234"
|
||||
name: "Alice"
|
||||
}
|
||||
],
|
||||
edges: []
|
||||
}
|
||||
},
|
||||
{
|
||||
vertex: {
|
||||
_id: "vertex/2",
|
||||
_key: "2",
|
||||
_rev: "5678"
|
||||
name: "Bob"
|
||||
},
|
||||
path: {
|
||||
vertices: [
|
||||
{
|
||||
_id: "vertex/1",
|
||||
_key: "1",
|
||||
_rev: "1234"
|
||||
name: "Alice"
|
||||
}, {
|
||||
_id: "vertex/2",
|
||||
_key: "2",
|
||||
_rev: "5678"
|
||||
name: "Bob"
|
||||
}
|
||||
],
|
||||
edges: [
|
||||
{
|
||||
_id: "edge/1",
|
||||
_key: "1",
|
||||
_rev: "9876",
|
||||
type: "loves"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
The new version is more compact.
|
||||
Each `SHORTEST_PATH` will only return one document having the attributes `vertices`, `edges`, `distance`.
|
||||
The `distance` is computed taking into account the given weight.
|
||||
Optionally the documents can be extracted with `includeData: true`
|
||||
Example:
|
||||
```
|
||||
{
|
||||
vertices: [
|
||||
"vertex/1",
|
||||
"vertex/2"
|
||||
],
|
||||
edges: [
|
||||
"edge/1"
|
||||
],
|
||||
distance: 1
|
||||
}
|
||||
```
|
||||
|
||||
The next function that returns a different format is `NEIGHBORS`.
|
||||
Since 2.5 it returned an object with `edge` and `vertex` for each connected edge.
|
||||
Example:
|
||||
```
|
||||
[
|
||||
{
|
||||
vertex: {
|
||||
_id: "vertex/2",
|
||||
_key: "2",
|
||||
_rev: "5678"
|
||||
name: "Bob"
|
||||
},
|
||||
edge: {
|
||||
_id: "edge/1",
|
||||
_key: "1",
|
||||
_rev: "9876",
|
||||
type: "loves"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
With 2.6 it will only return the vertex directly, again using `includeData: true`.
|
||||
By default it will return a distinct set of neighbors, using the option `distinct: false` will include the same vertex for each edge pointing to it.
|
||||
Example:
|
||||
```
|
||||
[
|
||||
"vertex/2"
|
||||
]
|
||||
```
|
||||
|
||||
!SUBSECTION V8
|
||||
|
||||
The V8 version shipped with ArangoDB was upgraded from 3.29.59 to 3.31.74.1.
|
||||
This leads to additional ECMAScript 6 (ES6 or "harmony") features being enabled by
|
||||
default in ArangoDB's scripting environment.
|
||||
|
||||
Apart from that, a change in the interpretation of command-line options by V8 may
|
||||
affect users. ArangoDB passes the value of the command-line option `--javascript.v8-options`
|
||||
to V8 and leaves interpretation of the contents to V8. For example, the ArangoDB option
|
||||
`--javascript.v8-options="--harmony"` could be used to tell V8 to enable its harmony
|
||||
features.
|
||||
|
||||
In ArangoDB 2.4, the following harmony options were made available by V8:
|
||||
|
||||
* --harmony_scoping (enable harmony block scoping)
|
||||
* --harmony_modules (enable harmony modules (implies block scoping))
|
||||
* --harmony_proxies (enable harmony proxies)
|
||||
* --harmony_generators (enable harmony generators)
|
||||
* --harmony_numeric_literals (enable harmony numeric literals (0o77, 0b11))
|
||||
* --harmony_strings (enable harmony string)
|
||||
* --harmony_arrays (enable harmony arrays)
|
||||
* --harmony_arrow_functions (enable harmony arrow functions)
|
||||
* --harmony_classes (enable harmony classes)
|
||||
* --harmony_object_literals (enable harmony object literal extensions)
|
||||
* --harmony (enable all harmony features (except proxies))
|
||||
|
||||
There was the option `--harmony`, which turned on almost all harmony features.
|
||||
|
||||
In ArangoDB 2.5, V8 provides the following harmony-related options:
|
||||
|
||||
* --harmony (enable all completed harmony features)
|
||||
* --harmony_shipping (enable all shipped harmony fetaures)
|
||||
* --harmony_modules (enable "harmony modules (implies block scoping)" (in progress))
|
||||
* --harmony_arrays (enable "harmony array methods" (in progress))
|
||||
* --harmony_array_includes (enable "harmony Array.prototype.includes" (in progress))
|
||||
* --harmony_regexps (enable "harmony regular expression extensions" (in progress))
|
||||
* --harmony_arrow_functions (enable "harmony arrow functions" (in progress))
|
||||
* --harmony_proxies (enable "harmony proxies" (in progress))
|
||||
* --harmony_sloppy (enable "harmony features in sloppy mode" (in progress))
|
||||
* --harmony_unicode (enable "harmony unicode escapes" (in progress))
|
||||
* --harmony_tostring (enable "harmony toString")
|
||||
* --harmony_numeric_literals (enable "harmony numeric literals")
|
||||
* --harmony_strings (enable "harmony string methods")
|
||||
* --harmony_scoping (enable "harmony block scoping")
|
||||
* --harmony_classes (enable "harmony classes (implies block scoping & object literal extension)")
|
||||
* --harmony_object_literals (enable "harmony object literal extensions")
|
||||
* --harmony_templates (enable "harmony template literals")
|
||||
|
||||
Note that there are extra options for better controlling the dedicated features,
|
||||
and especially that the meaning of the `--harmony` option has changed from enabling
|
||||
**all** harmony features to **all completed** harmony features!
|
||||
|
||||
Users should adjust the value of `--javascript.v8-options` accordingly.
|
||||
|
||||
Please note that incomplete harmony features are subject to change in future V8 releases.
|
||||
Loading…
Reference in New Issue