Server management

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

More details about the syntax descriptions can be found here.

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

(see SERVER MANAGEMENT privileges)

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

(see SERVER MANAGEMENT privileges)

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

(see SERVER MANAGEMENT privileges)

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

(see SERVER MANAGEMENT privileges)

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

(see SERVER MANAGEMENT privileges)

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

(see SERVER MANAGEMENT privileges)

Command

SHOW SERVERS

Syntax

 
SHOW SERVER[S]
  [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

(see SERVER MANAGEMENT privileges)

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 Type Default output Full output

name

Name of the server.

STRING

serverId

Id of the server.

STRING

address

Bolt address of the server (if enabled).

STRING

httpAddress

Http address of the server (if enabled).

STRING

httpsAddress

Https address of the server (if enabled).

STRING

state

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

STRING

health

The availability of the server: available or unavailable.

STRING

hosting

A list of databases currently hosted on the server.

LIST OF STRING

requestedHosting

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

LIST OF STRING

tags

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

LIST OF STRING

allowedDatabases

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

LIST OF STRING

deniedDatabases

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

LIST OF STRING

modeConstraint

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

STRING

version

Neo4j version the server is running.

STRING

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.

tags

list of server tags

List of server tags used during database allocation and for load balancing and routing policies. Introduced in 5.6

Composite databases are ignored by both allowedDatabases and deniedDatabases. The composite databases are available everywhere and hold no data on their own.

When a server is enabled, if tags are not provided in OPTIONS, the default server tags are taken from the setting initial.server.tags.

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.

tags

list of server tags

List of server tags used during database allocation and for load balancing and routing policies. Introduced in 5.6

Composite databases are ignored by both allowedDatabases and deniedDatabases. The composite databases are available everywhere and hold no data on their own.

Input provided to SET OPTIONS {…​} replaces all existing options, rather than being combined with them. For instance, if SET OPTIONS {modeConstraint:'SECONDARY'} is run followed by SET OPTIONS {allowedDatabases:['foo']}, the second ALTER removes the mode constraint.

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

The DRYRUN feature was introduced in Neo4j 5.2.

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.