Database alias management

This section explains how to use Cypher^® to manage database aliases in Neo4j.

There are two kinds of aliases, local database aliases and remote database aliases. A local database alias can only target a database within the same DBMS. A remote alias may target a database from another Neo4j DBMS. When a query is run against an alias, it will be redirected to the target database. The home database for users can be set to an alias, which will be resolved to the target database on use.

A local alias can be used in all other Cypher commands in place of the target database. Please note that the local alias will be resolved while executing the command. Privileges are defined on the database, and not the local alias.

A remote alias can be used for connecting to a database of a remote Neo4j DBMS, use clauses, setting a user’s home database and defining the access privileges to the remote database. Remote aliases requires configuration to safely connect to the remote target, which is described in Connecting remote databases. It is not possible to impersonate a user on the remote database or to execute an administration command on the remote database via a remote alias.

Database aliases can be created and managed using a set of Cypher administration commands executed against the system database. The required privileges are described here. When connected to the DBMS over Bolt, administration commands are automatically routed to the system database.

The syntax of the alias management commands is as follows:

More details about the syntax descriptions can be found here.

Table 1. Alias management command syntax
Command	Syntax
`SHOW ALIASES`	Lists both local and remote database aliases. `SHOW ALIASES FOR DATABASE[S] [WHERE expression]` `SHOW ALIASES FOR DATABASE[S] YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] [WHERE expression] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]`
`CREATE ALIAS`	Create a local database alias. `CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName` `CREATE OR REPLACE ALIAS name FOR DATABASE targetName`
`CREATE ALIAS ... AT`	Create a remote database alias. `CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName AT 'url' USER username PASSSWORD 'password' [DRIVER "{" setting: value[, ...] "}"]` `CREATE OR REPLACE ALIAS name FOR DATABASE targetName AT 'url' USER username PASSSWORD 'password' [DRIVER "{" setting: value[, ...] "}"]`
`ALTER ALIAS`	Alter a local database alias. `ALTER ALIAS name [IF EXISTS] SET DATABASE TARGET targetName`
`ALTER ALIAS ...`	Alter a remote database alias. `ALTER ALIAS name [IF EXISTS] SET DATABASE [TARGET targetName AT 'url'] [USER username] [PASSWORD 'password'] [DRIVER "{" setting: value[, ...] "}"]`
`DROP ALIAS`	Drop either a local or remote database alias. `DROP ALIAS name [IF EXISTS] FOR DATABASE`

This is the list of the allowed driver settings for remote aliases.

Table 2. ssl_enforced
Description	SSL for remote alias drivers is configured through the target url scheme. If `ssl_enforced` is set to true, a secure url scheme is enforced. This will be validated when the command is executed.
Valid values	Boolean
Default value	true

Table 3. connection_timeout
Description	Socket connection timeout. A timeout of zero is treated as an infinite timeout and will be bound by the timeout configured on the operating system level.
Valid values	Duration
Default value	dbms.routing.driver.connection.connect_timeout

Table 4. connection_max_lifetime
Description	Pooled connections older than this threshold will be closed and removed from the pool. Setting this option to a low value will cause a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, etc. can also limit maximum connection lifetime).
Valid values	Duration. Zero and negative values result in lifetime not being checked.
Default value	dbms.routing.driver.connection.max_lifetime

Table 5. connection_pool_acquisition_timeout
Description	Maximum amount of time spent attempting to acquire a connection from the connection pool. This timeout only kicks in when all existing connections are being used and no new connections can be created because maximum connection pool size has been reached. Error is raised when connection can’t be acquired within configured time.
Valid values	Duration. Negative values are allowed and result in unlimited acquisition timeout. Value of `0` is allowed and results in no timeout and immediate failure when connection is unavailable.
Default value	dbms.routing.driver.connection.pool.acquisition_timeout

Table 6. connection_pool_max_size
Description	Maximum total number of connections to be managed by a connection pool. The limit is enforced for a combination of a host and user.
Valid values	Integer. Negative values are allowed and result in unlimited pool. Value of `0` is not allowed.
Default value	dbms.routing.driver.connection.pool.max_size

Table 7. logging_level
Description	Sets level for driver internal logging.
Valid values	org.neo4j.logging.Level. One of `DEBUG`, `INFO`, `WARN`, `ERROR`, or `NONE`.
Default value	dbms.routing.driver.logging.level

If transaction modifies an alias, other transactions concurrently executing against that alias may be aborted and rolled back for safety. This prevents issues such as a transaction executing against multiple target databases for the same alias.

Listing database aliases

Available database aliases can be seen using SHOW ALIASES FOR DATABASE. The required privileges are described here.

SHOW ALIASES FOR DATABASE will produce a table of database aliases with the following columns:

Column Description

Column	Description
`name`	The name of the database alias. Default Output
`database`	The names of the target database. Default Output
`location`	The location of the database, either `local` or `remote`. Default Output
`url`	Target location or `null` if the target is local. Default Output
`user`	User connecting to the remote database or `null` if the target database is local. Default Output
`driver`	The driver options for connection to the remote database or `null` if the target database is local or if no driver settings are added. List of driver settings allowed for remote database aliases.
`MAP`	properties
`Any properties set on the database alias.`	MAP

name

The name of the database alias. Default Output

database

The names of the target database. Default Output

location

The location of the database, either local or remote. Default Output

url

Target location or null if the target is local. Default Output

user

User connecting to the remote database or null if the target database is local. Default Output

driver

The driver options for connection to the remote database or null if the target database is local or if no driver settings are added. List of driver settings allowed for remote database aliases.

MAP

properties

Any properties set on the database alias.

MAP

The detailed information for a particular database alias can be displayed using the command SHOW ALIASES FOR DATABASE YIELD *. When a YIELD * clause is provided, the full set of columns is returned.

Example 1. SHOW ALIASES FOR DATABASE

A summary of all available databases alias can be displayed using the command SHOW ALIASES FOR DATABASE.

Query

SHOW ALIASES FOR DATABASE

Table 8. Result
name	database	location	url	user
`"films"`	`"movies"`	`"local"`	`<null>`	`<null>`
`"motion pictures"`	`"movies"`	`"local"`	`<null>`	`<null>`
`"movie scripts"`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 3

Example 2. SHOW ALIASES FOR DATABASE

Query

SHOW ALIASES FOR DATABASE YIELD *

Table 9. Result
name	database	location	url	user	driver
`"films"`	`"movies"`	`"local"`	`<null>`	`<null>`	`<null>`
`"motion pictures"`	`"movies"`	`"local"`	`<null>`	`<null>`	`<null>`
`"movie scripts"`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{connection_pool_max_size -> 10, connection_pool_idle_test -> PT2M, connection_pool_acquisition_timeout -> PT1M, connection_max_lifetime -> PT1H, logging_level -> "INFO", ssl_enforced -> true, connection_timeout -> PT5S}`
Rows: 3

Example 3. SHOW ALIASES FOR DATABASE

The number of database aliases can be seen using a count() aggregation with YIELD and RETURN.

Query

SHOW ALIASES FOR DATABASE YIELD *
RETURN count(*) as count

Table 10. Result
count
`3`
Rows: 1

Example 4. SHOW ALIASES FOR DATABASE

It is possible to filter and sort the results by using YIELD, ORDER BY and WHERE.

Query

SHOW ALIASES FOR DATABASE YIELD name, url, database
ORDER BY database
WHERE name CONTAINS 'e'

In this example:

The number of columns returned has been reduced with the YIELD clause.
The order of the returned columns has been changed.
The results have been filtered to only show database alias names containing 'e'.
The results are ordered by the database column using ORDER BY.

It is also possible to use SKIP and LIMIT to paginate the results.

Table 11. Result
name	url	database
`"motion pictures"`	`<null>`	`"movies"`
`"movie scripts"`	`"neo4j+s://location:7687"`	`"scripts"`
Rows: 2

Creating database aliases

Aliases can be created using CREATE ALIAS.

The required privileges are described here.

This command is optionally idempotent, with the default behavior to fail with an error if the database alias already exists. Inserting IF NOT EXISTS after the alias name ensures that no error is returned and nothing happens should a database alias with that name already exist. Adding OR REPLACE to the command will result in any existing database alias being deleted and a new one created. CREATE OR REPLACE ALIAS will fail if there is an existing database with the same name.

The IF NOT EXISTS and OR REPLACE parts of this command cannot be used together.

Alias names are subject to the standard Cypher restrictions on valid identifiers.

The following naming rules apply:

A name is a valid identifier, additionally allowing dots e.g. main.alias for local aliases.
Name length can be up to 65534 characters.
Names cannot end with dots.
Names that begin with an underscore or with the prefix system are reserved for internal use.
Non-alphabetic characters, including numbers, symbols and whitespace characters, can be used in names, but must be escaped using backticks.

Creating local database aliases

Local aliases are created with a target database.

Example 5. CREATE ALIAS

Query

CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2021`

System updates: 1
Rows: 0

Example 6. SHOW DATABASE

When a local database alias has been created, it will show up in the aliases column provided by the command SHOW DATABASES and in the SHOW ALIASES FOR DATABASE command.

Query

SHOW DATABASE `northwind`

Table 12. Result
name	aliases	access	address	role	requestedStatus	currentStatus	error	default	home
`"northwind-graph-2021"`	`["northwind"]`	`"read-write"`	`"localhost:7687"`	`"standalone"`	`"online"`	`"online"`	`""`	`false`	`false`
Rows: 1

Example 7. SHOW ALIASES FOR DATABASE

Query

SHOW ALIASES FOR DATABASE
WHERE name = 'northwind'

Table 13. Result
name	database	location	url	user
`"northwind"`	`"northwind-graph-2021"`	`"local"`	`<null>`	`<null>`
Rows: 1

Example 8. CREATE ALIAS

Adding a local alias with the same name as an existing local or remote alias will do nothing with the IF NOT EXISTS clause but fail without it.

Query

CREATE ALIAS `northwind` IF NOT EXISTS FOR DATABASE `northwind-graph-2020`

Rows: 0

Example 9. CREATE OR REPLACE ALIAS

It is possible to replace an alias. The old alias may be either local or remote.

Query

CREATE OR REPLACE ALIAS `northwind` FOR DATABASE `northwind-graph-2020`

System updates: 2
Rows: 0

This is equivalent to running:

Query

DROP ALIAS `northwind` IF EXISTS FOR DATABASE
CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2020`

Creating remote database aliases

Database aliases can also point to remote databases by providing an url and the credentials of a user on the remote Neo4j DBMS. See Connecting remote databases for the necessary configurations.

Creating remote aliases also allows IF NOT EXISTS and OR REPLACE clauses. Both check for any remote or local database aliases.

Example 10. CREATE ALIAS

Query

CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
USER alice
PASSWORD 'example_secret'

System updates: 1
Rows: 0

Example 11. CREATE ALIAS

It is possible to override the default driver settings per alias, which are used for connecting to the remote database. The full list of supported driver settings can be seen here.

Query

CREATE ALIAS `remote-with-driver-settings` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
USER alice
PASSWORD 'example_secret'
DRIVER {
  connection_timeout: duration({minutes: 1}),
  connection_pool_max_size: 10
}

System updates: 1
Rows: 0

Example 12. SHOW ALIASES FOR DATABASE

When a database alias pointing to a remote database has been created, its details can be shown with the SHOW ALIASES FOR DATABASE command.

Query

SHOW ALIASES FOR DATABASE
WHERE name = 'remote-northwind'

Table 14. Result
name	database	location	url	user
`"remote-northwind"`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 1

Example 13. SHOW ALIASES FOR DATABASE

Query

SHOW ALIASES FOR DATABASE YIELD *
WHERE name = 'remote-with-driver-settings'

Table 15. Result
name	database	location	url	user	driver
`"remote-with-driver-settings"`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{connection_pool_max_size -> 10, connection_timeout -> PT1M}`
Rows: 1

Altering database aliases

Aliases can be altered using ALTER ALIAS to change its database target, url, user credentials, or driver settings. The required privileges are described here. Only the clauses used will be altered.

Local aliases can not be altered to remote aliases or vice versa.

Example 14. ALTER ALIAS

Example of altering a local database alias target.

Query

ALTER ALIAS `northwind`
SET DATABASE TARGET `northwind-graph-2021`

System updates: 1
Rows: 0

Example 15. ALTER ALIAS

Example of altering a remote database alias target.

Query

ALTER ALIAS `remote-northwind` SET DATABASE
TARGET `northwind-graph-2020` AT "neo4j+s://other-location:7687"

System updates: 1
Rows: 0

Example 16. ALTER ALIAS

Example of altering a remote alias credentials and driver settings.

Query

ALTER ALIAS `remote-with-driver-settings` SET DATABASE
USER bob
PASSWORD 'new_example_secret'
DRIVER {
  connection_timeout: duration({ minutes: 1}),
  logging_level: 'debug'
}

System updates: 1
Rows: 0

All driver settings are replaced by the new ones. In this case, by not repeating the driver setting connection_pool_max_size the value will be deleted and fallback to the default value.

Example 17. ALTER ALIAS

Example of altering a remote alias to remove all custom driver settings.

Query

ALTER ALIAS `movie scripts` SET DATABASE
DRIVER {}

System updates: 1
Rows: 0

Example 18. SHOW DATABASE

When a local database alias has been altered, it will show up in the aliases column for the target database provided by the command SHOW DATABASES.

Query

SHOW DATABASE `northwind`

Table 16. Result
name	aliases	access	address	role	requestedStatus	currentStatus	error	default	home
`"northwind-graph-2021"`	`["northwind"]`	`"read-write"`	`"localhost:7687"`	`"standalone"`	`"online"`	`"online"`	`""`	`false`	`false`
Rows: 1

Example 19. SHOW ALIASES FOR DATABASE

The changes for all database aliases will show up in the SHOW ALIASES FOR DATABASE command.

Query

SHOW ALIASES FOR DATABASE YIELD *
WHERE name IN ['northwind', 'remote-northwind', 'remote-with-driver-settings', 'movie scripts']

Table 17. Result
name	database	location	url	user	driver
`"movie scripts"`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{}`
`"northwind"`	`"northwind-graph-2021"`	`"local"`	`<null>`	`<null>`	`<null>`
`"remote-northwind"`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://other-location:7687"`	`"alice"`	`{}`
`"remote-with-driver-settings"`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"bob"`	`{logging_level -> "DEBUG", connection_timeout -> PT1M}`
Rows: 4

Example 20. ALTER ALIAS

This command is optionally idempotent, with the default behavior to fail with an error if the alias does not exist. Appending IF EXISTS to the command ensures that no error is returned and nothing happens should the alias not exist.

Query

ALTER ALIAS `no-alias` IF EXISTS SET DATABASE TARGET `northwind-graph-2021`

Rows: 0

Deleting database aliases

Both local and remote aliases can be deleted using the DROP ALIAS command. The required privileges are described here.

Example 21. DROP ALIAS

Drop a local database alias.

Query

DROP ALIAS `northwind` FOR DATABASE

System updates: 1
Rows: 0

Example 22. DROP ALIAS

Drop a remote database alias.

Query

DROP ALIAS `remote-northwind` FOR DATABASE

System updates: 1
Rows: 0

Example 23. SHOW DATABASE

When a database alias has been deleted, it will no longer show up in the aliases column provided by the command SHOW DATABASES.

Query

SHOW DATABASE `northwind-graph-2021`

Table 18. Result
name	aliases	access	address	role	requestedStatus	currentStatus	error	default	home
`"northwind-graph-2021"`	`[]`	`"read-write"`	`"localhost:7687"`	`"standalone"`	`"online"`	`"online"`	`""`	`false`	`false`
Rows: 1

Example 24. SHOW ALIASES FOR DATABASE

When a database alias has been deleted, it will no longer show up in the aliases column provided by the command SHOW ALIASES FOR DATABASE.

List all database aliases.

Query

SHOW ALIASES FOR DATABASE

Table 19. Result
name	database	location	url	user
`"films"`	`"movies"`	`"local"`	`<null>`	`<null>`
`"motion pictures"`	`"movies"`	`"local"`	`<null>`	`<null>`
`"movie scripts"`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
`"remote-with-driver-settings"`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"bob"`
Rows: 4

Example 25. DROP ALIAS

This command is optionally idempotent, with the default behavior to fail with an error if the alias does not exist. Inserting IF EXISTS after the alias name ensures that no error is returned and nothing happens should the alias not exist.

Query

DROP ALIAS `northwind` IF EXISTS FOR DATABASE

Rows: 0