From 9a306f74f45794b931a2938e101f1399bd10ac2c Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Tue, 20 Nov 2012 16:45:22 +0100 Subject: [PATCH] added UPGRADING file --- CHANGELOG | 3 ++ UPGRADING | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 UPGRADING diff --git a/CHANGELOG b/CHANGELOG index 668207c948..099b7af8e0 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,4 +1,7 @@ v1.1.beta3 (XXXX-XX-XX) +----------------------- + +* added UPGRADE file * WARNING: arangod now performs a database version check at startup. It will look for a file diff --git a/UPGRADING b/UPGRADING new file mode 100644 index 0000000000..210464af94 --- /dev/null +++ b/UPGRADING @@ -0,0 +1,130 @@ +Changes that should be considered when installing or upgrading ArangoDB +----------------------------------------------------------------------- + +* Starting the server + + Starting with ArangoDB 1.1, arangod will perform a database version check at startup. + It will look for a file named "VERSION" in its database directory. If the file is not + present (it will not be present in an ArangoDB 1.0 database), arangod in version 1.1 + will refuse to start and ask the user to run the script "arango-upgrade" first. + If the VERSION file is present but is from a non-matching version of ArangoDB, arangod + will also refuse to start and ask the user to run the upgrade script first. + This procedure shall ensure that users have full control over when they perform any + updates/upgrades of their data, and do not risk running an incompatible server/database + state tandem. + + ArangoDB users are asked to run arango-upgrade when upgrading from one version of + ArangoDB to a higher version (e.g. from 1.0 to 1.1), but also after pulling the latest + ArangoDB source code while staying in the same minor version (e.g. when updating from + 1.1-beta1 to 1.1-beta2). + + When installing ArangoDB from scratch, users should also run arango-upgrade once to + initialise their database directory with some system collections that ArangoDB requires. + When not run, arangod will refuse to start as mentioned before. + + + The startup options "--port", "--server.port", "--server.http-port", and + "--server.admin-port" have all been removed for arangod in version 1.1. + All these options have been replaced by the new "--server.endpoint" option. + This option allows to specify protocol, hostname and port the server should use for + incoming connections. + The "--server.endpoint" option must be specified on server start, otherwise arangod + will refuse to start. + + The server can be bound to one or multiple endpoints at once. The following endpoint + specification sytnax is currently supported: + - tcp://host:port or http@tcp://host:port (HTTP over IPv4) + - tcp://[host]:port or http@tcp://[host]:port (HTTP over IPv6) + - ssl://host:port or http@tcp://host:port (HTTP over SSL-encrypted IPv4) + - ssl://[host]:port or http@tcp://[host]:port (HTTP over SSL-encrypted IPv6) + - unix://path/to/socket or http@unix:///path/to/socket (HTTP over UNIX socket) + + An example value for the option is --server.endpoint tcp://127.0.0.1:8529. This will + make the server listen to request coming in on IP address 127.0.0.1 on port 8529, and + that use HTTP over TCP/IPv4. + + + The arangod startup options "--server.require-keep-alive" and + "--server.secure-require-keep-alive" have been removed in 1.1. The server will now + behave as follows which should be more conforming to the HTTP standard: + * if a client sends a "Connection: close" header, the server will close the + connection as request + * if a client sends a "Connection: keep-alive" header, the server will not + close the connection but keep it alive as requested + * if a client does not send any "Connection" header, the server will assume + "keep-alive" if the request was an HTTP/1.1 request, and "close" if the + request was an HTTP/1.0 request + * dangling keep-alive connections will be closed automatically by the server after + a configurable amount of seconds. To adjust the value, use the new server option + "--server.keep-alive-timeout" + + +* Start / stop scripts + + The user has changed from "arango" to "arangodb", the start script name has changed from + "arangod" to "arangodb", the database directory has changed from "/var/arangodb" to + "/var/lib/arangodb" to be compliant with various Linux policies. + + +* Collection types + + In 1.1, we have introduced types for collections: regular documents go into document + collections, and edges go into edge collections. The prefixing (db.xxx vs. edges.xxx) + works slightly different in 1.1: edges.xxx can still be used to access collections, + however, it will not determine the type of existing collections anymore. In 1.0, you + could write edges.xxx.something and xxx was automatically treated as an edge collection. + As collections know and save their type in ArangoDB 1.1, this might work slightly + differently. + + In 1.1, edge collections can still be created via edges._create() as in 1.0, but + a new method was also introduced that uses the db object: db._createEdgeCollection(). + To create document collections, the following methods are available: db._create() + as in 1.0, and additionally there is now db._createDocumentCollection(). + + Collections in 1.1 are now either document or edge collections, but the two concepts + can not be mixed in the same collection. arango-upgrade will determine the types of + existing collections from 1.0 once on upgrade, based on the inspection of the first 50 + documents in the collection. If one of them contains either a _from or a _to attribute, + the collection is made an edge collection, otherwise, the colleciton is marked as a + document collection. + This distinction is important because edges can only be created in edge collections + starting with 1.1. Client code may need to be adjusted for 1.1 to insert edges only + into "pure" edge collections in 1.1. + + +* Authorization + + Starting from 1.1, arangod may be started with authentication turned on. + When turned on, all requests incoming to arangod via the HTTP interface must carry an + HTTP authorization header with a valid username and password in order to be processed. + Clients sending requests without HTTP autorization headers or with invalid usernames/ + passwords will be rejected by arangod with an HTTP 401 error. + + arango-upgrade will create a default user "root" with an empty password when run + initially. + + To turn authorization off, the server can be started with the command line option + --server.disable-authentication true. Of course this configuration can also be stored + in a configuration file. + + +* arangoimp / arangosh + + The parameters "connect-timeout" and "request-timeout" for arangosh and arangoimp have + been renamed to "--server.connect-timeout" and "--server.request-timeout". + + The parameter "--server" has been removed for both arangoimp and arangosh. + To specify a server to connect to, the client tools now provide an option + "--server.endpoint". This option can be used to specify the protocol, hostname and port + for the connection. The default endpoint that is used when none is specified is + tcp://127.0.0.1:8529. For more information on the endpoint specification syntax, see + above. + + The options "--server.username" and "--server.password" have been added for arangoimp + and arangosh in order to use authorization from these client tools, too. + These options can be used to specify the username and password when connectiong via + client tools to the arangod server. If no password is given on the command line, + arangoimp and arangosh will interactively prompt for a password. + If no username is specified on the command line, the default user "root" will be + used but there will still be a password prompt. +