arangodb/Documentation/Books/Users/ReleaseNotes/UpgradingChanges30.mdpp

!CHAPTER Incompatible changes in ArangoDB 3.0

It is recommended to check the following list of incompatible changes **before**
upgrading to ArangoDB 3.0, and adjust any client programs if necessary.

!SECTION Build system

Building ArangoDB 3.0 from source now requires CMake. 

The pre-3.0 build system used a configure-based approach. The steps to build 
ArangoDB from source code in 2.8 were:

```
make setup
./configure <options>
make
```

These steps will not work anymore, as ArangoDB 3.0 does not come with a 
configure script.

To build 3.0 on Linux, create a separate build directory first:

```
mkdir -p build
```

and then create the initial build scripts once using CMake:

```
(cd build && cmake <options> ..)
```

The above command will configure the build and check for the required 
dependencies. If everything works well the actual build can be started with

```
(cd build && make)
```

The binaries for the ArangoDB server and all client tools will then be created
inside the `build` directory. To start ArangoDB locally from the `build` directory,
use

```
build/bin/arangod <options>
```

!SECTION Datafiles and datafile names

ArangoDB 3.0 uses a new VelocyPack-based format for storing data in WAL logfiles
and collection datafiles. The file format is not compatible with the files used
in prior versions of ArangoDB. That means datafiles written by ArangoDB 3.0 cannot be
used in earlier versions and vice versa.

The pattern for collection directory names was changed in 3.0 to include a random 
id component at the end. The new pattern is `collection-<id>-<random>`, where `<id>` 
is the collection id and `<random>` is a random number. Previous versions of ArangoDB 
used a pattern `collection-<id>` without the random number.

!SECTION Edges and edges attributes

In ArangoDB prior to 3.0 the attributes `_from` and `_to` of edges were treated 
specially when loading or storing edges. That special handling led to these attributes
being not as flexible as regular document attributes. For example, the `_from` and 
`_to` attribute values of an existing edge could not be updated once the edge was
created. Additionally, the `_from` and `_to` attributes could not be indexed in
user-defined indexes, e.g. to make each combination of `_from` and `_to` unique.
Finally, as `_from` and `_to` referenced the linked collections by collection id
and not by collection name, their meaning became unclear once a referenced collection 
was dropped. The collection id stored in edges then became unusable, and when
accessing such edge the collection name part of it was always translated to `_undefined`.

In ArangoDB 3.0, the `_from` and `_to` values of edges are saved as regular strings.
This allows using `_from` and `_to` in user-defined indexes. Additionally this allows
updating the `_from` and `_to` values of existing edges. Furthermore, collections
referenced by `_from` and `_to` values may be dropped and re-created later. Any
`_from` and `_to` values of edges pointing to such dropped collection are unaffected
by the drop operation now. 

!SECTION Documents

Documents (in contrast to edges) cannot contain the attributes `_from` or `_to` on the
main level in ArangoDB 3.0. These attributes will be automatically removed when saving
documents (i.e. non-edges). `_from` and `_to` can be still used in sub-objects inside
documents.

The `_from` and `_to` attributes will of course be preserved and are still required when 
saving edges.


!SECTION AQL

!SUBSECTION Edges handling

When updating or replacing edges via AQL, any modifications to the `_from` and `_to`
attributes of edges were ignored by previous versions of ArangoDB, without signaling
any errors. This was due to the `_from` and `_to` attributes being immutable in earlier
versions of ArangoDB.

From 3.0 on, the `_from` and `_to` attributes of edges are mutable, so any AQL queries that
modify the `_from` or `_to` attribute values of edges will attempt to actually change these
attributes. Clients should be aware of this change and should review their queries that
modify edges to rule out unintended side-effects.

Additionally, when completely replacing the data of existing edges via the AQL `REPLACE`
operation, it is now required to specify values for the `_from` and `_to` attributes,
as `REPLACE` requires the entire new document to be specified. If either `_from` or `_to`
are missing from the replacement document, an `REPLACE` operation will fail.

!SUBSECTION Typecasting functions

The type casting applied by the `TO_NUMBER()` AQL function has changed as follows:
- string values that do not contain a valid numeric value are now converted to the number
  `0`. In previous versions of ArangoDB such string values were converted to the value
  `null`.
- array values with more than 1 member are now converted to the number `0`. In previous
  versions of ArangoDB such arrays were converted to the value `null`.
- objects / documents are now converted to the number `0`. In previous versions of ArangoDB
  objects / documents were converted to the value `null`.

Additionally, the `TO_STRING()` AQL function now converts `null` values into an empty string
(`""`) instead of the string `"null"`, which is more in line with `LENGTH(null)` returning
`0` and not `4` since v2.6.

!SUBSECTION Arithmetic operators

As the arithmetic operations in AQL implicitly convert their operands to numeric values using 
`TO_NUMBER()`, their casting behavior has also changed as described above.

Some examples of the changed behavior:

- `"foo" + 1` produces `1` now. In previous versions this produced `null`.
- `[ 1, 2 ] + 1` produces `1`. In previous versions this produced `null`.
- `1 + "foo" + 1´ produces `2` now. In previous version this produced `1`.

!SUBSECTION Attribute names and parameters

Previous versions of ArangoDB had some trouble with attribute names that contained the dot
symbol (`.`). Some code parts in AQL used the dot symbol to split an attribute name into
sub-components, so an attribute named `a.b` was not completely distinguishable from an
attribute `a` with a sub-attribute `b`. This inconsistent behavior sometimes allowed "hacks"
to work such as passing sub-attributes in a bind parameter as follows:

```
FOR doc IN collection
  FILTER doc.@name == 1
  RETURN doc
```

If the bind parameter `@name` contained the dot symbol (e.g. `@bind` = `a.b`, it was unclear 
whether this should trigger sub-attribute access (i.e. `doc.a.b`) or a access to an attribute 
with exactly the specified name (i.e. `doc["a.b"]`).

ArangoDB 3.0 now handles attribute names containing the dot symbol properly, and sending a
bind parameter `@name` = `a.b` will now always trigger an access to the attribute `doc["a.b"]`,
not the sub-attribute `b` of `a` in `doc`. 

For users that used the "hack" of passing bind parameters containing dot symbol to access
sub-attributes, ArangoDB 3.0 allows specifying the attribute name parts as an array of strings,
e.g. `@name` = `[ "a", "b" ]`, which will be resolved to the sub-attribute access `doc.a.b` 
when the query is executed.

!SUBSECTION Keywords

`LIKE` is now a keyword in AQL. Using `LIKE` in either case as an attribute or collection 
name in AQL queries now requires quoting.

!SUBSECTION Subqueries

Queries that contain subqueries that contain data-modification operations such as `INSERT`, 
`UPDATE`, `REPLACE`, `UPSERT` or `REMOVE` will now refuse to execute if the collection
affected by the subquery's data-modification operation is read-accessed in an outer scope 
of the query.

For example, the following query will refuse to execute as the collection `myCollection`
is modified in the subquery but also read-accessed in the outer scope:

```
FOR doc IN myCollection
  LET changes = (
    FOR what IN myCollection 
      FILTER what.value == 1 
      REMOVE what IN myCollection
  )
  RETURN doc
```

It is still possible to write to collections from which data is read in the same query,
e.g.

```
FOR doc IN myCollection
  FILTER doc.value == 1 
  REMOVE doc IN myCollection
```

and to modify data in different collection via subqueries.

!SUBSECTION Other changes

The AQL optimizer rule "merge-traversal-filter" that already existed in 3.0 was renamed to 
"optimize-traversals". This should be of no relevance to client applications except if 
they programatically look for applied optimizer rules in the explain out of AQL queries.

The order of results created by the AQL functions `VALUES()` and `ATTRIBUTES()` was never 
guaranteed and it only had the "correct" ordering by accident when iterating over objects 
that were not loaded from the database. As some of the function internals have changed, the
"correct" ordering will not appear anymore, and still no result order is guaranteed by
these functions unless the `sort` parameter is specified (for the `ATTRIBUTES()` function).

!SECTION Upgraded V8 version

The V8 engine that is used inside ArangoDB to execute JavaScript code has been upgraded from
version 4.3.61 to 5.0.71.39. The new version should be mostly compatible to the old version,
but there may be subtle differences, including changes of error message texts thrown by the
engine. 
Furthermore, some V8 startup parameters have changed their meaning or have been removed in
the new version. This is only relevant when ArangoDB or ArangoShell are started with a custom
value for the `--javascript.v8-options` startup option.

Among others, the following V8 options change in the new version of ArangoDB:

- `--es_staging`: in 2.8 it had the meaning `enable all completed harmony features`, in 3.0 
  the option means `enable test-worthy harmony features (for internal use only)`

- `--strong_this`: this option wasn't present in 2.8. In 3.0 it means `don't allow 'this' to
  escape from constructors` and defaults to true.

- `--harmony_regexps`: this options means `enable "harmony regular expression extensions"` 
  and changes its default value from false to true

- `--harmony_proxies`: this options means `enable "harmony proxies"` and changes its default 
   value from false to true

- `--harmony_reflect`: this options means `enable "harmony Reflect API"` and changes its default 
   value from false to true

- `--harmony_sloppy`: this options means `enable "harmony features in sloppy mode"` and changes 
   its default value from false to true

- `--harmony_tostring`: this options means `enable "harmony toString"` and changes its default 
   value from false to true

- `--harmony_unicode_regexps`: this options means `enable "harmony unicode regexps"` and changes 
   its default value from false to true
  
- `--harmony_arrays`, `--harmony_array_includes`, `--harmony_computed_property_names`, 
  `--harmony_arrow_functions`, `--harmony_rest_parameters`, `--harmony_classes`, 
  `--harmony_object_literals`, `--harmony_numeric_literals`, `--harmony_unicode`:
   these option have been removed in V8 5.

!SECTION JavaScript API changes

The following incompatible changes have been made to the JavaScript API in ArangoDB 3.0:

!SUBSECTION Foxx

The Foxx framework has been completely rewritten for 3.0 with a new, simpler and more 
familiar API. To make Foxx services developed for 2.8 or earlier ArangoDB versions run in 3.0, the service's manifest file needs to be edited.

To enable the legacy mode for a Foxx service, add `"engines": {"arangodb": "^2.8.0"}` 
(or similar version ranges that exclude 3.0 and up) to the service manifest file
(named "manifest.json", located in the service's base directory).

!SUBSECTION Require

Modules shipped with ArangoDB can now be required using the pattern `@arangodb/<module>`
instead of `org/arangodb/<module>`, e.g.

```js
var cluster = require("@arangodb/cluster"); 
```

The old format can still be used for compatibility:

```js
var cluster = require("org/arangodb/cluster"); 
```

ArangoDB prior to version 3.0 allowed a transparent use of CoffeeScript
source files with the `require()` function. Files with a file name extension
of `coffee` were automatically sent through a CoffeeScript parser and 
transpiled into JavaScript on-the-fly. This support is gone with ArangoDB
3.0. To run any CoffeeScript source files, they must be converted to JavaScript
by the client application.

!SUBSECTION Response object

The `@arangodb/request` response object now stores the parsed JSON response
body in a property `json` instead of `body` when the request was made using the
`json` option. The `body` instead contains the response body as a string.

!SUBSECTION Edges API

When completely replacing an edge via a collection's `replace()` function the replacing 
edge data now needs to contain the `_from` and `_to` attributes for the new edge. Previous
versions of ArangoDB did not require the edge data to contain `_from` and `_to` attributes
when replacing an edge, since `_from` and `_to` values were immutable for existing edges.

For example, the following call worked in ArangoDB 2.8 but will fail in 3.0:

```js
db.edgeCollection.replace("myKey", { value: "test" });
```

To make this work in ArangoDB 3.0, `_from` and `_to` need to be added to the replacement
data:

```js
db.edgeCollection.replace("myKey", { _from: "myVertexCollection/1", _to: "myVertexCollection/2", value: "test" });
```

Note that this only affects the `replace()` function but not `update()`, which will
only update the specified attributes of the edge and leave all others intact.

Additionally, the functions `edges()`, `outEdges()` and `inEdges()` with an array of edge 
ids will now make the edge ids unique before returning the connected edges. This is probably 
desired anyway, as results will be returned only once per distinct input edge id. However, 
it may break client applications that rely on the old behavior.

!SUBSECTION Collection API

!SUBSUBSECTION Example matching

The collection function `byExampleHash()` and `byExampleSkiplist()` have been removed in 3.0.
Their functionality is provided by collection's `byExample()` function, which will automatically
use a suitable index if present.

The collection function `byConditionSkiplist()` has been removed in 3.0. The same functionality
can be achieved by issuing an AQL query with the target condition, which will automatically use
a suitable index if present.

!SUBSUBSECTION Revision id handling

The `exists()` method of a collection now throws an exception when the specified document
exists but its revision id does not match the revision id specified. Previous versions of
ArangoDB simply returned `false` if either no document existed with the specified key or
when the revision id did not match. It was therefore impossible to distinguish these two
cases from the return value alone. 3.0 corrects this. Additionally, `exists()` in previous
versions always returned a boolean if only the document key was given. 3.0 now returns the
document's meta-data, which includes the document's current revision id.

Given there is a document with key `test` in collection `myCollection`, then the behavior
of 3.0 is as follows:

```js
/* test if document exists. this returned true in 2.8 */
db.myCollection.exists("test");
{ 
  "_key" : "test", 
  "_id" : "myCollection/test", 
  "_rev" : "9758059" 
}

/* test if document exists. this returned true in 2.8 */
db.myCollection.exists({ _key: "test" });
{ 
  "_key" : "test", 
  "_id" : "myCollection/test", 
  "_rev" : "9758059" 
}

/* test if document exists. this also returned false in 2.8 */
db.myCollection.exists("foo");
false

/* test if document with a given revision id exists. this returned true in 2.8 */
db.myCollection.exists({ _key: "test", _rev: "9758059" });
{ 
  "_key" : "test", 
  "_id" : "myCollection/test", 
  "_rev" : "9758059" 
}

/* test if document with a given revision id exists. this returned false in 2.8 */
db.myCollection.exists({ _key: "test", _rev: "1234" });
JavaScript exception: ArangoError 1200: conflict
```

!SUBSUBSECTION Cap constraints

The cap constraints feature has been removed. This change has led to the removal of the
collection operations `first()` and `last()`, which were internally based on data from 
cap constraints.

As cap constraints have been removed in ArangoDB 3.0 it is not possible to create an
index of type "cap" with a collection's `ensureIndex()` function. The dedicated function
`ensureCapConstraint()` has also been removed from the collection API.

!SUBSUBSECTION Undocumented APIs

The undocumented functions `BY_EXAMPLE_HASH()` and `BY_EXAMPLE_SKIPLIST()` and 
`BY_CONDITION_SKIPLIST` have been removed. These functions were always hidden and not 
intended to be part of the public JavaScript API for collections.

!SECTION HTTP API changes

!SUBSECTION CRUD operations

The following incompatible changes have been made to the HTTP API in ArangoDB 3.0:

!SUBSUBSECTION General

The HTTP insert operations for single documents and edges (POST `/_api/document`) do 
not support the URL parameter "createCollection" anymore. In previous versions of
ArangoDB this parameter could be used to automatically create a collection upon 
insertion of the first document. It is now required that the target collection already
exists when using this API, otherwise it will return an HTTP 404 error.

Collections can still be created easily via a separate call to POST `/_api/collection`
as before.

The "location" HTTP header returned by ArangoDB when inserting a new document or edge
now always contains the database name. This was also the default behavior in previous
versions of ArangoDB, but it could be overridden by clients sending the HTTP header
`x-arango-version: 1.4` in the request. Clients can continue to send this header to
ArangoDB 3.0, but the header will not influence the location response headers produced 
by ArangoDB 3.0 anymore.

Additionally the CRUD operations APIs do not return an attribute "error" in the
response body with an attribute value of "false" in case an operation succeeded.

!SUBSUBSECTION Revision id handling

The operations for updating, replacing and removing documents can optionally check the
revision number of the document to be updated, replaced or removed so the caller can
ensure the operation works on a specific version of the document and there are no
lost updates.

Previous versions of ArangoDB allowed passing the revision id of the previous document
either in the HTTP header `If-Match` or in the URL parameter `rev`. For example, 
removing a document with a specific revision id could be achieved as follows:

```
curl -X DELETE \
     "http://127.0.0.1:8529/_api/document/myCollection/myKey?rev=123" 
```

ArangoDB 3.0 does not support passing the revision id via the "rev" URL parameter
anymore. Instead the previous revision id must be passed in the HTTP header `If-Match`,
e.g.

```
curl -X DELETE \
     --header "If-Match: '123'" \
     "http://127.0.0.1:8529/_api/document/myCollection/myKey" 
```

The URL parameter "policy" was also usable in previous versions of ArangoDB to
control revision handling. Using it was redundant to specifying the expected revision
id via the "rev" parameter or "If-Match" HTTP header and therefore support for the "policy"
parameter was removed in 3.0.

In order to check for a previous revision id when updating, replacing or removing 
documents please use the `If-Match` HTTP header as described above. When no revision
check if required the HTTP header can be omitted, and the operations will work on the
current revision of the document, regardless of its revision id.

!SUBSECTION All documents API

The HTTP API for retrieving the ids, keys or URLs of all documents from a collection
was previously located at GET `/_api/document?collection=...`. This API was moved to
PUT `/_api/simple/all-keys` and is now executed as an AQL query. 
The name of the collection must now be passed in the HTTP request body instead of in
the request URL. The same is true for the "type" parameter, which controls the type of
the result to be created.

Calls to the previous API can be translated as follows:

- old: GET `/_api/document?collection=<collection>&type=<type>` without HTTP request body
- 3.0: PUT `/_api/simple/all-keys` with HTTP request body `{"name":"<collection>","type":"id"}`

The result format of this API has also changed slightly. In previous versions calls to
the API returned a JSON object with a `documents` attribute. As the functionality is
based on AQL internally in 3.0, the API now returns a JSON object with a `result` attribute:

!SUBSECTION Edges API

!SUBSUBSECTION CRUD operations

The API for documents and edges have been unified in ArangoDB 3.0. The CRUD operations 
for documents and edges are now handled by the same endpoint at `/_api/document`. For 
CRUD operations there is no distinction anymore between documents and edges API-wise.

That means CRUD operations concerning edges need to be sent to the HTTP endpoint 
`/_api/document` instead of `/_api/edge`. Sending requests to `/_api/edge` will
result in an HTTP 404 error in 3.0. The following methods are available at 
`/_api/document` for documents and edge:

- HTTP POST: insert new document or edge
- HTTP GET: fetch an existing document or edge
- HTTP PUT: replace an existing document or edge
- HTTP PATCH: partially update an existing document or edge
- HTTP DELETE: remove an existing document or edge

When completely replacing an edge via HTTP PUT please note that the replacing edge
data now needs to contain the `_from` and `_to` attributes for the edge. Previous
versions of ArangoDB did not require sending `_from` and `_to` when replacing edges, 
as `_from` and `_to` values were immutable for existing edges.

The `_from` and `_to` attributes of edges now also need to be present inside the
edges objects sent to the server:

```
curl -X POST \
     --data '{"value":1,"_from":"myVertexCollection/1","_to":"myVertexCollection/2"}' \
     "http://127.0.0.1:8529/_api/document?collection=myEdgeCollection" 
```

Previous versions of ArangoDB required the `_from` and `_to` attributes of edges be 
sent separately in URL parameter `from` and `to`:

```
curl -X POST \
     --data '{"value":1}' \
     "http://127.0.0.1:8529/_api/edge?collection=e&from=myVertexCollection/1&to=myVertexCollection/2" 
```

!SUBSUBSECTION Querying connected edges

The REST API for querying connected edges at GET `/_api/edges/<collection>` will now
make the edge ids unique before returning the connected edges. This is probably desired anyway
as results will now be returned only once per distinct input edge id. However, it may break 
client applications that rely on the old behavior.

!SUBSUBSECTION Graph API

Some data-modification operations in the named graphs API at `/_api/gharial` now return either
HTTP 202 (Accepted) or HTTP 201 (Created) if the operation succeeds. Which status code is returned
depends on the `waitForSync` attribute of the affected collection. In previous versions some
of these operations return HTTP 200 regardless of the `waitForSync` value.

!SUBSECTION Simple queries API

The REST routes PUT `/_api/simple/first` and `/_api/simple/last` have been removed
entirely. These APIs were responsible for returning the first-inserted and 
least-inserted documents in a collection. This feature was built on cap constraints
internally, which have been removed in 3.0.

Calling one of these endpoints in 3.0 will result in an HTTP 404 error.

!SUBSECTION Indexes API

It is not supported in 3.0 to create an index with type `cap` (cap constraint) in 
3.0 as the cap constraints feature has bee removed. Calling the index creation
endpoint HTTP API POST `/_api/index?collection=...` with an index type `cap` will 
therefore result in an HTTP 400 error.

!SUBSECTION Log entries API

The REST route HTTP GET `/_admin/log` is now accessible from within all databases. In
previous versions of ArangoDB, this route was accessible from within the `_system`
database only, and an HTTP 403 (Forbidden) was thrown by the server for any access
from within another database.

!SUBSECTION Figures API

The REST route HTTP GET `/_api/collection/<collection>/figures` will not return the 
following result attributes as they became meaningless in 3.0:

- shapefiles.count
- shapes.fileSize
- shapes.count
- shapes.size
- attributes.count
- attributes.size

!SUBSECTION Databases and Collections APIs

When creating a database via the API POST `/_api/database`, ArangoDB will now always
return the HTTP status code 202 (created) if the operation succeeds. Previous versions
of ArangoDB returned HTTP 202 as well, but this behavior was changable by sending an
HTTP header `x-arango-version: 1.4`. When sending this header, previous versions of
ArangoDB returned an HTTP status code 200 (ok). Clients can still send this header to
ArangoDB 3.0 but this will not influence the HTTP status code produced by ArangoDB.

The "location" header produced by ArangoDB 3.0 will now always contain the database 
name. This was also the default in previous versions of ArangoDB, but the behaviour
could be overridden by sending the HTTP header `x-arango-version: 1.4`. Clients can
still send the header, but this will not make the database name in the "location"
response header disappear.

!SUBSECTION Replication APIs

The URL parameter "failOnUnknown" was removed from the REST API GET `/_api/replication/dump`.
This parameter controlled whether dumping or replicating edges should fail if one
of the vertex collections linked in the edge's `_from` or `_to` attributes was not
present anymore. In this case the `_from` and `_to` values could not be translated into
meaningful ids anymore. 

There were two ways for handling this:
- setting `failOnUnknown` to `true` caused the HTTP request to fail, leaving error 
  handling to the user
- setting `failOnUnknown` to `false` caused the HTTP request to continue, translating
  the collection name part in the `_from` or `_to` value to `_unknown`.

In ArangoDB 3.0 this parameter is obsolete, as `_from` and `_to` are stored as self-contained
string values all the time, so they cannot get invalid when referenced collections are
dropped.

!SUBSECTION Undocumented APIs

The following undocumented HTTP REST endpoints have been removed from ArangoDB's REST
API:

- `/_open/cerberus` and `/_system/cerberus`: these endpoints were intended for some 
  ArangoDB-internal applications only
- PUT /_api/simple/by-example-hash`, PUT `/_api/simple/by-example-skiplist` and
  PUT `/_api/simple/by-condition-skiplist`: these methods were documented in early
  versions of ArangoDB but have been marked as not intended to be called by end
  users since ArangoDB version 2.3. These methods should not have been part of any
  ArangoDB manual since version 2.4.
- `/_api/structure`: an unfinished API for data format and type checks, superseded
  by Foxx.

!SECTION Command-line options

Quite a few startup options in ArangoDB 2 were double negations (like
`--server.disable-authentication false`). In ArangoDB 3 these are now expressed as 
positives (e. g. `--server.authentication`). Also the options between the ArangoDB
server and its client tools have being unified. For example, the logger options are 
now the same for the server and the client tools. Additionally many options have
been moved into more appropriate topic sections.

!SUBSECTION Renamed options

The following options have been available before 3.0 and have changed their name 
in 3.0:

- `--server.disable-authentication` was renamed to `--server.authentication`. 
  Note that the meaning of the option `--server.authentication` is the opposite of 
  the previous `--server.disable-authentication`.
- `--server.disable-authentication-unix-sockets` was renamed to 
  `--server.authentication-unix-sockets`. Note that the meaning of the option 
  `--server.authentication-unix-sockets` is the opposite of the previous 
  `--server.disable-authentication-unix-sockets`.
- `--server.disable-statistics` was renamed to `--server.statistics`. Note that the
  meaning of the option `--server.statistics` is the opposite of the previous
  `--server.disable-statistics`.
- `--server.keyfile` was renamed to `--ssl.keyfile`. The meaning of the option is
  unchanged.
- `--server.foxx-queues` was renamed to `--foxx.queues`. The meaning of the option
  is unchanged.
- `--server.foxx-queues-poll-interval` was renamed to `--foxx.queues-poll-interval`.
  The meaning of the option is unchanged.
- `--log.tty` was renamed to `--log.foreground-tty`. The meaning of the option is
  unchanged.
- `--upgrade` has been renamed to `--database.auto-upgrade`. In contrast to 2.8 this
  option now requires a boolean parameter. To actually perform an automatic database 
  upgrade at startup use `--database.auto-upgrade true`. To not perform it, use
  `--database.auto-upgrade false`.
- `--check-version` has been renamed to `--database.check-version`.
- `--temp-path` has been renamed to `--temp.path`.

!SUBSECTION Log verbosity, topics and output files

Logging now supports log topics. You can control these by specifying a log
topic in front of a log level or an output. For example

```
  --log.level startup=trace --log.level info
```

will log messages concerning startup at trace level, everything else at info
level. `--log.level` can be specified multiple times at startup, for as many 
topics as needed.

Some relevant log topics available in 3.0 are:

- *collector*: information about the WAL collector's state
- *compactor*: information about the collection datafile compactor
- *datafiles*: datafile-related operations
- *mmap*: information about memory-mapping operations
- *performance*: some performance-related information
- *queries*: executed AQL queries
- *replication*: replication-related info
- *requests*: HTTP requests
- *startup*: information about server startup and shutdown
- *threads*: information about threads

The new log option `--log.output <definition>` allows directing the global
or per-topic log output to different outputs. The output definition "<definition>" 
can be one of

- "-" for stdin
- "+" for stderr
- "syslog://<syslog-facility>"
- "syslog://<syslog-facility>/<application-name>"
- "file://<relative-path>"

The option can be specified multiple times in order to configure the output
for different log topics. To set up a per-topic output configuration, use
`--log.output <topic>=<definition>`, e.g.

  queries=file://queries.txt

logs all queries to the file "queries.txt".

The old option `--log.file` is still available in 3.0 for convenience reasons. In
3.0 it is a shortcut for the more general option `--log.output file://filename`.
  
The old option `--log.requests-file` is still available in 3.0. It is now a shortcut
for the more general option `--log.output requests=file://...`.

The old option `--log.performance` is still available in 3.0. It is now a shortcut
for the more general option `--log.level performance=trace`.

!SUBSECTION Removed options for logging

The options `--log.content-filter` and `--log.source-filter` have been removed. They
have most been used during ArangoDB's internal development.

The syslog-related options `--log.application` and `--log.facility` have been removed.
They are superseded by the more general `--log.output` option which can also handle 
syslog targets. 

!SUBSECTION Removed other options

The option `--server.default-api-compatibility` was present in earlier version of
ArangoDB to control various aspects of the server behavior, e.g. HTTP return codes
or the format of HTTP "location" headers. Client applications could send an HTTP
header "x-arango-version" with a version number to request the server behavior of
a certain ArangoDB version.

This option was only honored in a handful of cases (described above) and was removed
in 3.0 because the changes in server behavior controlled by this option were changed
even before ArangoDB 2.0. This should have left enough time for client applications
to adapt to the new behavior, making the option superfluous in 3.0.

!SECTION Web Admin Interface

The JavaScript shell has been removed from ArangoDB's web interface. The functionality
it provided is still fully available in the ArangoShell (arangosh) binary shipped
with ArangoDB.

!SECTION ArangoShell and client tools

The ArangoShell (arangosh) and the other client tools bundled with ArangoDB can only
connect to an ArangoDB server of version 3.0 or higher. They will not connect to an
ArangoDB 2.8. This is because the server HTTP APIs have changed between 2.8 and 3.0,
and all client tools uses these APIs.

In order to connect to earlier versions of ArangoDB with the client tools, an older
version of the client tools needs to be kept installed.

!SUBSECTION Command-line options changed

For all client tools, the option `--server.disable-authentication` was renamed to
`--server.authentication`. Note that the meaning of the option `--server.authentication` 
is the opposite of the previous `--server.disable-authentication`.

The command-line option `--quiet` was removed from all client tools except arangosh 
because it had no effect in those tools.

!SUBSECTION Arangobench

In order to make its purpose more apparent, the former `arangob` client tool has 
been renamed to `arangobench` in 3.0.

!SECTION Miscellaneous changes

The checksum calculation algorithm for the `collection.checksum()` method and its
corresponding REST API GET `/_api/collection/<collection</checksum` has changed in 3.0. 
Checksums calculated in 3.0 will differ from checksums calculated with 2.8 or before.

The ArangoDB server in 3.0 does not read a file `ENDPOINTS` containing a list of 
additional endpoints on startup. In 2.8 this file was automatically read if present
in the database directory.

The names of the sub-threads started by ArangoDB have changed in 3.0. This is relevant
on Linux only, where threads can be named and thread names may be visible to system
tools such as *top* or monitoring solutions.