Managing servers

Servers can be added and managed using a set of Cypher administration commands executed against the system database.

When connected to the DBMS over bolt, administration commands are automatically routed to the system database.

Server management command syntax

Command

ENABLE SERVER

Syntax

ENABLE SERVER 'serverId' [OPTIONS "{" option: value[,...] "}"]

Description

Adds a server that has been discovered to the cluster. For more information see Enabling servers.

Required privilege

GRANT SERVER MANAGEMENT

Command

ALTER SERVER

Syntax

ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"

Description

Changes the constraints for a server. For more information see Modifying servers.

Required privilege

GRANT SERVER MANAGEMENT

Command

RENAME SERVER

Syntax

RENAME SERVER 'name' TO 'newName'

Description

Changes the name of a server. For more information see Renaming servers.

Required privilege

GRANT SERVER MANAGEMENT

Command

REALLOCATE DATABASES

Syntax

[DRYRUN] REALLOCATE DATABASE[S]

Description

Re-balances databases among the servers in the cluster. For more information see Reallocate databases.

Required privilege

GRANT SERVER MANAGEMENT

Command

DEALLOCATE DATABASES

Syntax

[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]

Description

Removes all databases from the given servers. For more information see Deallocate databases.

Required privilege

GRANT SERVER MANAGEMENT

Command

DROP SERVER

Syntax

DROP SERVER 'name'

Description

Removes a server not hosting any databases from the cluster. For more information see Drop server.

Required privilege

GRANT SERVER MANAGEMENT

Command

SHOW SERVERS

Syntax

SHOW SERVERS
  [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
  [WHERE expression]
  [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

Lists all servers visible to the cluster. For more information see Listing servers.

Required privilege

GRANT SHOW SERVERS

Listing servers

SHOW SERVERS displays all servers running in the cluster, including servers that have yet to be enabled as well as dropped servers.

The table of results shows information about the servers:

Column Description Default output Full output

name

Name of the server.

serverId

Id of the server.

address

Bolt address of the server (if enabled).

httpAddress

Http address of the server (if enabled).

httpsAddress

Https address of the server (if enabled).

state

Information of the state of the server: free, enabled, deallocating, or dropped.

health

The availability of the server: available or unavailable.

hosting

A list of databases currently hosted on the server.

requestedHosting

A list of databases that should be hosted on the server, decided by the allocator.

tags

Tags are user provided strings that can be used while allocating databases.

allowedDatabases

A list of databases allowed to be hosted on the server.

deniedDatabases

A list of databases not allowed to be hosted on the server.

modeConstraint

Constraint for the allocator to allocate only databases in this mode on the server.

version

Neo4j version the server is running.

A summary of all servers can be displayed using the command SHOW SERVERS.

Table 1. Result
name address state health hosting

"server1"

"localhost:20000"

"Enabled"

"Available"

["system","neo4j"]

"server2"

"localhost:20007"

"Enabled"

"Available"

["system","neo4j"]

"server3"

"localhost:20014"

"Enabled"

"Available"

["system","neo4j"]

"0c030000-267b-49a8-801f-78bd0b5c6445"

"localhost:20021"

"Free"

"Available"

["system"]

Enabling servers

A server can be added to the cluster with the ENABLE SERVER 'name' command. The servers initial name is its id. The server must be in the free state to be added to the cluster. If the server is already enabled and the command is executed with the same options specified nothing is changed. In any other case trying to enable a server fails.

The possible options allowed when enabling a server are:

Option Allowed values Description

modeConstraint

PRIMARY, SECONDARY, NONE

Databases may only be hosted on the server in the mode specified by the constraint. None means there is no constraint and any mode is allowed.

allowedDatabases

list of database names

Only databases matching the specified names may be hosted on the server. This may not be specified in combination with deniedDatabases.

deniedDatabases

list of database names

Only databases not matching the specified names may be hosted on the server. This may not be specified in combination with allowedDatabases.

Modifying servers

The constraints on a server can be changed with ALTER SERVER 'name' SET OPTIONS { option: value }. Either the name or the id of the server can be used.

The possible options allowed when altering a server are:

Option Allowed values Description

modeConstraint

PRIMARY, SECONDARY, NONE

Databases may only be hosted on the server in the mode specified by the constraint. None means there is no constraint and any mode is allowed.

allowedDatabases

list of database names

Only databases matching the specified names may be hosted on the server. This may not be specified in combination with deniedDatabases.

deniedDatabases

list of database names

Only databases not matching the specified names may be hosted on the server. This may not be specified in combination with allowedDatabases.

Renaming servers

The name of a server can be altered with RENAME SERVER 'name' TO 'newName'. Either the id or current name of the server can be used to identify the server. The new name of the server must be unique.

Reallocate databases

After enabling a server, REALLOCATE DATABASES can be used to make the cluster re-balance databases across all servers that are part of the cluster. Using DRYRUN REALLOCATE DATABASE returns a view of how the databases would have been re-balanced if the command was executed without DRYRUN:

Table 2. Result
database fromServerName fromServerId toServerName toServerId mode

"db1"

"server-1"

"00000000-94ff-4ede-87be-3d741b795480"

"server-4"

"00000002-25a9-4984-9ad2-dc39024c9238"

"primary"

"db3"

"server-1"

"00000000-94ff-4ede-87be-3d741b795480"

"server-5"

"00000003-0df7-4057-81fd-1cf43c9ef5f7"

"primary"

Deallocate databases

A server can be set to not host any databases with DEALLOCATE DATABASES FROM SERVER 'name', in preparation for removing the server from the cluster. Either the id or name of the server can be used. All databases that the server is hosting are moved to other servers. The server changes state to deallocating. A deallocated server cannot readily be enabled again.

Multiple servers can be deallocated at the same time, DEALLOCATE DATABASES FROM SERVER 'server-1', 'server-2'. The command fails if there aren’t enough servers available to move the databases to.

Using DRYRUN DEALLOCATE DATABASES FROM 'server-1', 'server-2' returns a view of how the databases would have been re-balanced if the command was executed without DRYRUN:

Table 3. Result
database fromServerName fromServerId toServerName toServerId mode

"db1"

"server-1"

"00000001-8c04-4731-a2fd-7b0289c511ce"

"server-4"

"00000002-5b91-43c1-8b25-5289f674563e"

"primary"

"db1"

"server-2"

"00000000-7e53-427c-a987-24634c4745f3"

"server-5"

"00000003-0e98-44c8-9844-f0a4eb95b0d8"

"primary"

Drop server

When a server has been deallocated and is no longer hosting any databases it can be removed from the cluster with DROP SERVER 'name'. Either the id or name of the server can be used. As long as the server is running, it is listed when showing servers with the state dropped.