Database alias management

This chapter 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.

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:

Table 1. Alias management command syntax
Command Syntax

Show Database Alias

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]]

Lists both local and remote database aliases.

Create Local Alias

CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName
CREATE OR REPLACE ALIAS name FOR DATABASE targetName

Create Remote 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 Local Alias

ALTER ALIAS name [IF EXISTS] SET DATABASE TARGET targetName

Alter Remote Alias

ALTER ALIAS name [IF EXISTS] SET DATABASE
[TARGET targetName AT 'url']
[USER username]
[PASSWORD 'password']
[DRIVER "{" setting: value[, ...] "}"]

Drop Alias

DROP ALIAS name [IF EXISTS] FOR DATABASE

Drop either a local or remote database alias.

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

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

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

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

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

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.

1. 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 Default Output Full Output Notes
name

The name of the database alias.

database

The names of the target database.

location

The location of the database, either local or remote.

url

Target location or null if the target is local.

user

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

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.

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

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.

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

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

It is also 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

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.

2.1. Creating local database aliases

Local aliases are created with a target database.

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

0 rows, System updates: 1

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

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

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`

0 rows

It is also 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`

0 rows, System updates: 2

This is equivalent to running DROP ALIAS northwind IF EXISTS FOR DATABASE followed by CREATE ALIAS northwind FOR DATABASE northwind-graph-2020 .

2.2. 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.

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

0 rows, System updates: 1

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 'password'
DRIVER { connection_timeout: duration({ minutes: 1 }), connection_pool_max_size: 10 }

0 rows, System updates: 1

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

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

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

3. 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 of altering a local alias target.

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

0 rows, System updates: 1

Example of altering a remote alias target.

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

0 rows, System updates: 1

Example of altering a remote alias credentials and driver settings.

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

0 rows, System updates: 1

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 of altering a remote alias to remove all custom driver settings.

Query
ALTER ALIAS `movie scripts` SET DATABASE DRIVER { }

0 rows, System updates: 1

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

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

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`

0 rows

4. Deleting database aliases

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

Query
DROP ALIAS `northwind` FOR DATABASE

0 rows, System updates: 1

Query
DROP ALIAS `remote-northwind` FOR DATABASE

0 rows, System updates: 1

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

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

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

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

0 rows