Database alias management

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

There are two kinds of database aliases: local and remote. A local database alias can only target a database within the same DBMS. A remote database alias may target a database from another Neo4j DBMS. When a query is run against a database 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 database alias can be used in all other Cypher commands in place of the target database. Please note that the local database alias will be resolved while executing the command. Privileges are defined on the database, and not the local database alias.

A remote database 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 database aliases require 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 database 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 database 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 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 PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [PROPERTIES "{" key: value[, ...] "}"]` `CREATE OR REPLACE ALIAS name FOR DATABASE targetName AT 'url' USER username PASSWORD '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 database aliases.

Table 2. ssl_enforced
Description	SSL for remote database 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 a database 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 Type

Column	Description	Type
`name`	The fully qualified name of the database alias. Default Output	`STRING`
`composite`	The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. Default Output	`STRING`
`database`	The name of the target database. Default Output This column is filtered according to the `ACCESS` privileges of the user. However, some privileges enable users to see additional databases regardless of their `ACCESS` privileges: Users with the `CREATE DATABASE`, `DROP DATABASE`, `ALTER DATABASE`, or `SET DATABASE ACCESS` privileges can see all standard databases. Users with the `CREATE COMPOSITE DATABASE`, `DROP COMPOSITE DATABASE`, or `COMPOSITE DATABASE MANAGEMENT` privileges can see all composite databases. Users with the `DATABASE MANAGEMENT` privilege can see all databases. Users can always see the `system` database. If a user has not been granted the `ACCESS` privilege to the target database and none of the above special cases apply, then it is not visible to the user and this column will be `null`.	`STRING`
`location`	The location of the database, either `local` or `remote`. Default Output	`STRING`
`url`	Target location or `null` if the target is local. Default Output	`STRING`
`user`	User connecting to the remote database or `null` if the target database is local. Default Output	`STRING`
`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 fully qualified name of the database alias. Default Output

STRING

composite

The name of the composite database this alias belongs to, or null if the alias does not belong to a composite database. Default Output

STRING

database

The name of the target database. Default Output

This column is filtered according to the ACCESS privileges of the user. However, some privileges enable users to see additional databases regardless of their ACCESS privileges:

Users with the CREATE DATABASE, DROP DATABASE, ALTER DATABASE, or SET DATABASE ACCESS privileges can see all standard databases.
Users with the CREATE COMPOSITE DATABASE, DROP COMPOSITE DATABASE, or COMPOSITE DATABASE MANAGEMENT privileges can see all composite databases.
Users with the DATABASE MANAGEMENT privilege can see all databases.
Users can always see the system database.

If a user has not been granted the ACCESS privilege to the target database and none of the above special cases apply, then it is not visible to the user and this column will be null.

STRING

location

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

STRING

url

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

STRING

user

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

STRING

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 all aliases for a database

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

Query

SHOW ALIASES FOR DATABASE

Table 8. Result
name	composite	database	location	url	user
`"films"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`
`"library.romance"`	`"library"`	`"romance-books""`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
`"library.sci-fi"`	`"library"`	`"sci-fi-books"`	`"local"`	`<null>`	`<null>`
`"motion pictures"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`
`"movie scripts"`	`null`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 5

Example 2. Show specific aliases for databases

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

Query

SHOW ALIAS films FOR DATABASES

Table 9. Result
name	composite	database	location	url	user
`"films"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`
Rows: 1

Query

SHOW ALIAS library.romance FOR DATABASES

Table 10. Result
name	composite	database	location	url	user
`"library.romance"`	`"library"`	`"romance-books"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 1

Example 3. Show detailed aliases information for a database

Query

SHOW ALIASES FOR DATABASE YIELD *

Table 11. Result
name	composite	database	location	url	user	driver	properties
`"films"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`	`<null>`	`{}`
`"library.romance"`	`"library"`	`"romance-books"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{}`	`{}`
`"library.sci-fi"`	`"library"`	`"sci-fi-books"`	`"local"`	`<null>`	`<null>`	`<null>`	`{}`
`"motion pictures"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`	`<null>`	`{"namecontainsspace":true}`
`"movie scripts"`	`null`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`+{"connection_pool_idle_test":PT2M,"connection_pool_max_size":10,"loggi"connection_pool_idle_test":PT2M,"connection_pool_max_size":10,"logging_level":"INFO","ssl_enforced":true,"connection_pool_acquisition_timeout":PT1M,"connection_timeout":PT5S,"connection_max_lifetime":PT1H}`	`{}`
Rows: 5

Example 4. Show count of aliases for a 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 12. Result
count
`5`
Rows: 1

Example 5. Show filtered aliases information for a 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 13. 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

Creating database aliases

Database aliases can be created using CREATE ALIAS.

The required privileges are described here.

Syntax Comment

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 PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [PROPERTIES "{" key: value[, ...] "}"]`	Create a remote database alias.

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 PASSWORD 'password'
[DRIVER "{" setting: value[, ...] "}"]
[PROPERTIES "{" key: value[, ...] "}"]

Create a remote database 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.

Database alias names are subject to the rules specified in the Alias names and escaping section.

Creating local database aliases

Local aliases are created with a target database.

Example 6. Creating aliases for local databases

Query

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

System updates: 1
Rows: 0

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	composite	database	location	url	user
`"northwind"`	`null`	`"northwind-graph-2021"`	`"local"`	`<null>`	`<null>`
Rows: 1

Example 7. Setting properties for local database aliases

Local database aliases can also be given properties. These properties can then be used in queries with the graph.propertiesByName() function.

Query

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

System updates: 1
Rows: 0

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

Example 8. Creating database aliases with the same name as an existing alias

Adding a local database 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`

(no changes, no records)

Example 9. Creating or replacing database aliases

It is also possible to replace a database 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 the following two queries consecutively:

Query

DROP ALIAS `northwind` IF EXISTS FOR DATABASE

Query

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 database aliases also allows IF NOT EXISTS and OR REPLACE clauses. Both check for any remote or local database aliases.

Example 10. Creating remote database aliases

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

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	composite	database	location	url	user
`"remote-northwind"`	`null`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 1

Example 11. Creating remote database aliases with driver settings

It is possible to override the default driver settings per database 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

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-with-driver-settings` FOR DATABASE YIELD *

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

Example 12. Setting properties for remote database aliases

Just as the local database aliases, the remote database aliases can be given properties. These properties can then be used in queries with the graph.propertiesByName() function.

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 }

System updates: 1
Rows: 0

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

Create database aliases in composite databases

Both local and remote database aliases can be part of a composite database.

The database alias is made of two parts, separated by a dot: the namespace and the alias name.

The namespace must be the name of the composite database.

Example 13. Creating aliases in composite databases

Query

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

System updates: 1
Rows: 0

Query

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

System updates: 1
Rows: 0

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 composite = 'garden'

Table 22. Result
name	composite	database	location	url	user
`"garden.flowers"`	`"garden"`	`"perennial-flowers"`	`"local"`	`<null>`	`<null>`
`"garden.trees"`	`"garden"`	`"trees"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
Rows: 1

Example 14. Aliases pointing to composite databases

Database aliases cannot point to a composite database.

Query

CREATE ALIAS yard FOR DATABASE garden

Error message

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

Altering database aliases

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

Local database aliases cannot be altered to remote aliases, or vice versa.

Syntax Comment

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] [PASSWORD '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.

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]
[PASSWORD '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.

Example 15. Altering local database aliases

Example of altering a local database alias target.

Query

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

System updates: 1
Rows: 0

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-graph-2021`

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

Example 16. Altering remote database aliases

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 17. Altering remote credentials and driver settings for remote database aliases

Example of altering a remote database 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 18. Removing custom driver settings from remote database aliases

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

Query

ALTER ALIAS `movie scripts` SET DATABASE
DRIVER {}

System updates: 1
Rows: 0

Example 19. Altering properties for local and remote database aliases

Examples of altering local and remote database alias properties.

Query

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

System updates: 1
Rows: 0

Query

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

System updates: 1
Rows: 0

The updated properties can then be used in queries with the graph.propertiesByName() function.

Example 20. Altering local and remote aliases in composite databases

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

Query

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

System updates: 1
Rows: 0

Query

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

System updates: 1
Rows: 0

The updated properties can then be used in queries with the graph.propertiesByName() function.

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	composite	database	location	url	user	driver	properties
`"garden.flowers"`	`"garden"`	`"perennial-flowers"`	`"local"`	`<null>`	`<null>`	`<null>`	`{"perennial":true}`
`"garden.trees"`	`"garden"`	`"updatedtrees"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{}`	`{"treeversion":2}`
`"motion pictures"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`	`<null>`	`{"namecontainsspace":true,"moreinfo":"no, not really"}`
`"movie scripts"`	`null`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`	`{connection_pool_idle_test: PT2M, connection_pool_max_size: 10, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H}`	`{"namecontainsspace":true}`
`"northwind"`	`null`	`"northwind-graph-2021"`	`"local"`	`<null>`	`<null>`	`<null>`	`[]`
`"remote-northwind"`	`null`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://other-location:7687"`	`"alice"`	`{}`	`{}`
`"remote-with-driver-settings"`	`null`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"bob"`	`{logging_level -> "DEBUG", connection_timeout -> PT1M}`	`[]`
Rows: 7

Example 21. Using IF EXISTS when altering database aliases

The ALTER ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database 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`

(no changes, no records)

Deleting database aliases

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

Example 22. Deleting local database aliases

Delete a local database alias.

Query

DROP ALIAS `northwind` FOR DATABASE

System updates: 1
Rows: 0

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

Example 23. Deleting remote database aliases

Delete a remote database alias.

Query

DROP ALIAS `remote-northwind` FOR DATABASE

System updates: 1
Rows: 0

Example 24. Deleting aliases in composite databases

Delete an alias in a composite database.

Query

DROP ALIAS garden.flowers FOR DATABASE

System updates: 1
Rows: 0

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

Query

SHOW ALIASES FOR DATABASE

Table 27. Result
name	composite	database	location	url	user
`"films"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`
`"garden.trees"`	`"garden"`	`"updatedtrees"`	`"local"`	`"neo4j+s://location:7687"`	`"alice"`
`"library.romance"`	`"library"`	`"romance-books"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
`"library.sci-fi"`	`"library"`	`"sci-fi-books"`	`"local"`	`<null>`	`<null>`
`"motion pictures"`	`null`	`"movies"`	`"local"`	`<null>`	`<null>`
`"movie scripts"`	`null`	`"scripts"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
`"northwind-2022"`	`null`	`"northwind-graph-2022"`	`"local"`	`<null>`	`<null>`
`"remote-northwind"`	`null`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://other-location:7687"`	`"alice"`
`"remote-northwind-2021"`	`null`	`"northwind-graph-2021"`	`"remote"`	`"neo4j+s://location:7687"`	`"alice"`
`"remote-with-driver-settings"`	`null`	`"northwind-graph-2020"`	`"remote"`	`"neo4j+s://location:7687"`	`"bob"`
Rows: 9

Example 25. Using IF EXISTS when deleting database aliases

The DROP ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database 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

(no changes, no records)

Alias names and escaping

Database 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.
Unescaped dots signify that the database alias belongs to a composite database, separating the composite database name and the alias name.
Names that begin with an underscore or with the prefix system are reserved for internal use.
Non-alphabetic characters, including numbers, symbols, dots, and whitespace characters, can be used in names, but must be escaped using backticks.

The name restrictions and escaping rules apply to all the different database alias commands.

Having dots (.) in the database alias names is not recommended. This is due to the difficulty of determining if a dot is part of the database alias name or a delimiter for a database alias in a composite database.

When it comes to escaping names using backticks, there are some additional things to consider around database aliases in composite databases:

Example 26. Escaping database alias and composite database names

The composite database name and the database alias name need to be escaped individually. The following example creates a database alias named my alias with spaces as a constituent in the composite database named my-composite-database-with-dashes:

Query

CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph`

System updates: 1
Rows: 0

When not escaped individually, a database alias with the full name my alias with.dots and spaces gets created instead:

Query

CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph`

System updates: 1
Rows: 0

Example 27. Handling multiple dots

Database alias names may also include dots. Though these always need to be escaped in order to avoid ambiguity with the composite database and database alias split character.

Query

CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`

System updates: 1
Rows: 0

Query

CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph`

System updates: 1
Rows: 0

Example 28. Single dots and local database aliases Deprecated

There is a special case for local database aliases with a single dot without any existing composite database. If a composite database some exists, the query below will create a database alias named alias within the composite database some. If no such database exists, however, the same query will instead create a database alias named some.alias:

Query

CREATE ALIAS some.alias FOR DATABASE `northwind-graph`

System updates: 1
Rows: 0

Example 29. Handling parameters

When using parameters, names cannot be escaped. When the given parameter includes dots, the first dot will be considered the divider for the composite database.

Consider the query with parameter:

Parameters

{
  "aliasname": "mySimpleCompositeDatabase.myAlias"
}

Query

CREATE ALIAS $aliasname FOR DATABASE `northwind-graph`

If the composite database mysimplecompositedatabase exists, then a database alias myalias will be created in that composite database. If no such composite database exists, then a database alias mysimplecompositedatabase.myalias will be created.

On the contrary, a database alias myalias cannot be created in composite mycompositedatabase.withdot using parameters. Consider the same query but with the following parameter:

Parameters

{
  "aliasname": "myCompositeDatabase.withDot.myAlias"
}

Since the first dot will be used as a divider, the command will attempt to create the database alias withdot.myalias in the composite database mycompositedatabase. If mycompositedatabase doesn’t exist, the command will create a database alias with the name mycompositedatabase.withdot.myalias, which is not part of any composite database.

In these cases, it is recommended to avoid parameters and explicitly escape the composite database name and alias name separately to avoid ambiguity.

Example 30. Handling parameters

Further special handling with parameters is needed for database aliases and similarly named composite databases.

Consider the set-up:

Query

CREATE COMPOSITE DATABASE foo
CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph`

The alias foo.bar does not belong to the composite database foo.

Dropping this alias using parameters fails with an error about a missing alias:

Parameters

{
  "aliasname": "foo.bar"
}

Query

DROP ALIAS $aliasname FOR DATABASE

Error message

Failed to delete the specified database alias 'foo.bar': Database alias does not exist.

Had the composite database foo not existed, the database alias foo.bar would have been dropped.

In these cases, it is recommended to avoid parameters and explicitly escape the composite database name and alias name separately to avoid ambiguity.

Was this page helpful?