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. Both local and remote database aliases can be created as part of a composite database.

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 ALIAS[ES] [name] FOR DATABASE[S]
[WHERE expression]
SHOW ALIAS[ES] [name] 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, optionally filtered on the alias name.

Create Local Alias

CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName
[PROPERTIES "{" key: value[, ...] "}"]
CREATE OR REPLACE ALIAS name FOR DATABASE targetName
[PROPERTIES "{" key: value[, ...] "}"]

Create Remote Alias

CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName
AT 'url' USER username PASSSWORD 'password'
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: value[, ...] "}"]
CREATE OR REPLACE ALIAS name FOR DATABASE targetName
AT 'url' USER username PASSSWORD 'password'
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: value[, ...] "}"]

Alter Local Alias

ALTER ALIAS name [IF EXISTS] SET DATABASE
[TARGET targetName]
[PROPERTIES "{" key: value[, ...] "}"]

Alter Remote Alias

ALTER ALIAS name [IF EXISTS] SET DATABASE
[TARGET targetName AT 'url']
[USER username]
[PASSWORD 'password']
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: 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.

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 fully qualified name of the database alias.

database

The name 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.

properties

Any properties set on the alias.

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>

"library.romance"

"romance-books"

"remote"

"neo4j+s://location:7687"

"alice"

"library.sci-fi"

"sci-fi-books"

"local"

<null>

<null>

"motion pictures"

"movies"

"local"

<null>

<null>

"movie scripts"

"scripts"

"remote"

"neo4j+s://location:7687"

"alice"

Rows: 5

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 properties

"films"

"movies"

"local"

<null>

<null>

<null>

{}

"library.romance"

"romance-books"

"remote"

"neo4j+s://location:7687"

"alice"

{}

{}

"library.sci-fi"

"sci-fi-books"

"local"

<null>

<null>

<null>

{}

"motion pictures"

"movies"

"local"

<null>

<null>

<null>

{namecontainsspace -> true}

"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, connection_timeout -> PT5S, logging_level -> "INFO", ssl_enforced -> true}

{}

Rows: 5

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

5

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"

"library.romance"

"neo4j+s://location:7687"

"romance-books"

"movie scripts"

"neo4j+s://location:7687"

"scripts"

Rows: 3

To list just one database alias, the SHOW ALIASES command takes an alias name:

Query
SHOW ALIAS films FOR DATABASES
Table 12. Result
name database location url user

"films"

"movies"

"local"

<null>

<null>

Rows: 1

Query
SHOW ALIAS library.romance FOR DATABASES
Table 13. Result
name database location url user

"library.romance"

"romance-books"

"remote"

"neo4j+s://location:7687"

"alice"

Rows: 1

Creating database aliases

Aliases can be created using CREATE ALIAS. The required privileges are described here.

Table 14. Create alias command syntax
Syntax Comment
CREATE [OR REPLACE] ALIAS [compositeDatabaseName.]aliasName [IF NOT EXISTS] FOR DATABASE targetName
[PROPERTIES "{" key: value[, ...] "}"]

Create a local alias.

CREATE [OR REPLACE] ALIAS [compositeDatabaseName.]aliasName [IF NOT EXISTS] FOR DATABASE targetName
AT 'url' USER username PASSSWORD 'password'
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: value[, ...] "}"]

Create a remote alias.

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.

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

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 15. Result
name type aliases access address role writer requestedStatus currentStatus statusMessage default home constituents

"northwind-graph-2021"

"standard"

["northwind"]

"read-write"

"localhost:7687"

"primary"

true

"online"

"online"

""

false

false

[]

Rows: 1

Query
SHOW ALIAS `northwind` FOR DATABASE
Table 16. Result
name database location url user

"northwind"

"northwind-graph-2021"

"local"

<null>

<null>

Rows: 1

Local database aliases can also be given properties.

Query
CREATE ALIAS `northwind-2022`
FOR DATABASE `northwind-graph-2022`
PROPERTIES { newestNorthwind: true, index: 3 }

0 rows, System updates: 1

The properties are then shown in the SHOW ALIASES FOR DATABASE YIELD …​ command.

Query
SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties
Table 17. Result
name properties

"northwind-2022"

{index -> 3, newestnorthwind -> true}

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 .

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 ALIAS `remote-northwind` FOR DATABASE
Table 18. Result
name database location url user

"remote-northwind"

"northwind-graph-2020"

"remote"

"neo4j+s://location:7687"

"alice"

Rows: 1

Query
SHOW ALIAS `remote-with-driver-settings` FOR DATABASE YIELD *
Table 19. Result
name database location url user driver properties

"remote-with-driver-settings"

"northwind-graph-2020"

"remote"

"neo4j+s://location:7687"

"alice"

{connection_pool_max_size -> 10, connection_timeout -> PT1M}

{}

Rows: 1

Just as the local aliases, the remote database aliases can be given properties.

Query
CREATE ALIAS `remote-northwind-2021`
FOR DATABASE `northwind-graph-2021` AT 'neo4j+s://location:7687'
USER alice PASSWORD 'password'
PROPERTIES { newestNorthwind: false, index: 6 }

0 rows, System updates: 1

The properties are then shown in the SHOW ALIASES FOR DATABASE YIELD …​ command.

Query
SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties
Table 20. Result
name properties

"remote-northwind-2021"

{index -> 6, newestnorthwind -> false}

Rows: 1

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

Create database aliases in composite databases

Both local and remote database aliases can be part of composite databases. Create a database alias in a composite database by giving the name of the composite database as namespace for the alias.

Query
CREATE ALIAS garden.flowers
FOR DATABASE `perennial-flowers`

0 rows, System updates: 1

Query
CREATE ALIAS garden.trees
FOR DATABASE trees AT 'neo4j+s://location:7687'
USER alice PASSWORD 'password'

0 rows, System updates: 1

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

Query
SHOW DATABASE garden YIELD name, type, constituents
Table 21. Result
name type constituents

"garden"

"composite"

["garden.flowers","garden.trees"]

Rows: 1

Query
SHOW ALIASES FOR DATABASE WHERE name STARTS WITH 'garden'
Table 22. Result
name database location url user

"garden.flowers"

"perennial-flowers"

"local"

<null>

<null>

"garden.trees"

"trees"

"remote"

"neo4j+s://location:7687"

"alice"

Rows: 2

Aliases cannot point to a composite database.

Query
CREATE ALIAS yard FOR DATABASE garden

Failed to create the specified database alias 'yard': Database 'garden' is composite.

Altering database aliases

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

Table 23. Alter alias command syntax
Syntax Comment
ALTER ALIAS [compositeDatabaseName.]aliasName [IF EXISTS] SET DATABASE
[TARGET targetName]
[PROPERTIES "{" key: value[, ...] "}"]

Modify database target of a local alias.

The clauses can be applied in any order, while at least one clause needs to be set.

ALTER ALIAS [compositeDatabaseName.]aliasName [IF EXISTS] SET DATABASE
[TARGET targetName AT 'url']
[USER username]
[PASSSWORD 'password']
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: value[, ...] "}"]

Modify a remote alias.

The clauses can be applied in any order, while at least one clause needs to be set.

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

Examples of altering local and remote database alias properties.

Query
ALTER ALIAS `motion pictures` SET DATABASE PROPERTIES { nameContainsSpace: true, moreInfo: 'no, not really' }

0 rows, System updates: 1

Query
ALTER ALIAS `movie scripts` SET DATABASE PROPERTIES { nameContainsSpace: true }

0 rows, System updates: 1

Examples of altering local and remote database alias in composite databases.

Query
ALTER ALIAS garden.flowers SET DATABASE PROPERTIES { perennial: true }

0 rows, System updates: 1

Query
ALTER ALIAS garden.trees SET DATABASE TARGET updatedTrees AT 'neo4j+s://location:7687' PROPERTIES { treeVersion: 2 }

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 24. Result
name type aliases access address role writer requestedStatus currentStatus statusMessage default home constituents

"northwind-graph-2021"

"standard"

["northwind"]

"read-write"

"localhost:7687"

"primary"

true

"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', 'motion pictures', 'garden.flowers', 'garden.trees']
Table 25. Result
name database location url user driver properties

"garden.flowers"

"perennial-flowers"

"local"

<null>

<null>

<null>

{perennial -> true}

"garden.trees"

"updatedtrees"

"remote"

"neo4j+s://location:7687"

"alice"

{}

{treeversion -> 2}

"motion pictures"

"movies"

"local"

<null>

<null>

<null>

{namecontainsspace -> true, moreinfo -> "no, not really"}

"movie scripts"

"scripts"

"remote"

"neo4j+s://location:7687"

"alice"

{}

{namecontainsspace -> true}

"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: 7

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

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

Query
DROP ALIAS garden.flowers 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 ALIASES FOR DATABASE command.

Query
SHOW DATABASE `northwind-graph-2021`
Table 26. Result
name type aliases access address role writer requestedStatus currentStatus statusMessage default home constituents

"northwind-graph-2021"

"standard"

[]

"read-write"

"localhost:7687"

"primary"

true

"online"

"online"

""

false

false

[]

Rows: 1

Query
SHOW ALIASES FOR DATABASE
Table 27. Result
name database location url user

"films"

"movies"

"local"

<null>

<null>

"garden.trees"

"updatedtrees"

"remote"

"neo4j+s://location:7687"

"alice"

"library.romance"

"romance-books"

"remote"

"neo4j+s://location:7687"

"alice"

"library.sci-fi"

"sci-fi-books"

"local"

<null>

<null>

"motion pictures"

"movies"

"local"

<null>

<null>

"movie scripts"

"scripts"

"remote"

"neo4j+s://location:7687"

"alice"

"northwind-2022"

"northwind-graph-2022"

"local"

<null>

<null>

"remote-northwind-2021"

"northwind-graph-2021"

"remote"

"neo4j+s://location:7687"

"alice"

"remote-with-driver-settings"

"northwind-graph-2020"

"remote"

"neo4j+s://location:7687"

"bob"

Rows: 9

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