Incompatible changes in ArangoDB 3.5

It is recommended to check the following list of incompatible changes beforeupgrading to ArangoDB 3.5, and adjust any client programs if necessary.

The following incompatible changes have been made in ArangoDB 3.5:

ID values in log messages

By default, ArangoDB and its client tools now show a 5 digit unique ID value inany of their log messages, e.g.

  1. 2019-03-25T21:23:19Z [8144] INFO [cf3f4] ArangoDB (version 3.5.0 enterprise [linux]) is ready for business. Have fun!.

In this message, the cf3f4 is the message’s unique ID value. ArangoDB users canuse this ID to build custom monitoring or alerting based on specific log ID values.

The presence of these ID values in log messages may confuse custom log message filtering or routing mechanisms that parse log messages and that rely on the old log messageformat.

This can be fixed adjusting any existing log message parsers and making them awareof the ID values. The ID values are always 5 byte strings, consisting of the characters[0-9a-f]. ID values are placed directly behind the log level (e.g. INFO) forgeneral log messages that do not contain a log topic, and directly behind the logtopic for messages that contain a topic, e.g.

  1. 2019-03-25T21:23:19Z [8144] INFO [cf3f4] ArangoDB (version 3.5.0 enterprise [linux]) is ready for business. Have fun!.
  2. 2019-03-25T21:23:16Z [8144] INFO {authentication} [3844e] Authentication is turned on (system only), authentication for unix sockets is turned on

Alternatively, the log IDs can be suppressed in all log messages by setting the startupoption —log.ids false when starting arangod or any of the client tools.

Startup options

The hidden startup option —rocksdb.delayed_write_rate was renamed to the moreconsistent —rocksdb.delayed-write-rate. When the old option name is used, the arangod startup will be aborted with a descriptive error message.

HTTP REST API

The following APIs have been added:

The following APIs have been expanded:

The following documentation has been enhanced:

Web interface

Potentially different sort order of documents

In the list of documents for a collection, the documents will now always be sortedin lexicographical order of their _key values. An exception for keys representing quasi-numerical values has been removed when doing the sorting in the web interface.

Therefore a document with a key value “10” will now be displayed before a documentwith a key value of “9”.

Removal of index types “hash” and “skiplist” from the web UI (RocksDB engine)

For the RocksDB engine, the selection of index types “hash” and “skiplist” has been removed from the web interface when creating new indexes.

The index types “hash”, “skiplist” and “persistent” are just aliases of each other when using the RocksDB engine, so there is no need to offer all of them in parallel.

We found that offering the different types of indexes while in fact they were thesame often confused end users. We opted for keeping “persistent” because from thecandidates “hash”, “skiplist” and “persistent” only “persistent” is actually a validdescription of the index capabilities/implementation.

AQL

3.5 enforces the invalidation of variables in AQL queries after usage of an AQL COLLECT statements as documented. The documentation for variable invalidation claimsthat

  1. The COLLECT statement will eliminate all local variables in the current scope. 
  2. After COLLECT only the variables introduced by COLLECT itself are available.

However, the described behavior was not enforced when a COLLECT was preceded by aFOR loop that was itself preceded by a COLLECT. In the following query the finalRETURN statement accesses variable key1 though the variable should have been invalidated by the COLLECT directly before it:

  1. FOR x1 IN 1..2 
  2.   COLLECT key1 = x1 
  3.   FOR x2 IN 1..2 
  4.     COLLECT key2 = x2 
  5.     RETURN [key2, key1]

In previous releases, this query wasparsed ok, but the contents of variable key1 in the final RETURN statement wereundefined.

This change is about making queries as the above fail with a parse error, as an unknown variable key1 is accessed here, avoiding the undefined behavior. This is also in line with what the documentation states about variable invalidation.

HTTP Replication APIs

New parameter for WAL tailing API

Tailing of recent server operations via /_api/wal/tail gets a new parametersyncerId, which helps in tracking the WAL tick of each client. If set, thissupersedes the parameter serverId for this purpose. The API stays backwardscompatible.

Miscellaneous

Index creation

In previous versions of ArangoDB, if one attempted to create an index with aspecified _id, and that _id was already in use, the server would typicallyreturn the existing index with matching _id. This is somewhat unintuitive, asit would ignore if the rest of the definition did not match. This behavior hasbeen changed so that the server will now return a duplicate identifier error.

ArangoDB 3.5 also disallows creating indexes on the _id sub-attribute of an attribute,referredTo._id or documents[*]._id. Previous versions of ArangoDB allowed creatingsuch indexes, but the indexes were non-functional.Starting with ArangoDB 3.5 such indexes cannot be created anymore, and any attempts to create them will fail.

Version details output

The attribute key openssl-version in the server/client tool version details output was renamed to openssl-version-compile-time.

This change affects the output produced when starting one of the ArangoDBexecutables (e.g. arangod, arangosh) with the —version command. It also changes the attribute name in the detailed response of the /_api/version REST API.

Overcommit settings

On Linux, ArangoDB will now show a startup warning in case the kernel setting vm.overcommit_memory is set to a value of 2 and the jemalloc memory allocator is in use. This combination does not play well together, and may lead to the kernel denying arangod’s memory allocation requests in more cases than necessary.

Usage of V8

ArangoQueryStreamCursor.id() used to return a 32 bit number, and will nowreturn a string as similar places where V8 has representations of ArangoDB IDs.