Managing database aliases for standard databases

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.

This page describes managing database aliases for standard databases. Local and remote database aliases can also be created as part of a composite database. For more information, see Managing database aliases in composite databases.

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 in the The DBMS ALIAS MANAGEMENT privileges. When connected to the DBMS over Bolt, administration commands are automatically routed to the system database.

If a 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.

List database aliases

Available database aliases can be seen using SHOW ALIASES FOR DATABASE. The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges.

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

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

Show all aliases for a database

A summary of all available database aliases can be displayed using the command SHOW ALIASES FOR DATABASE. This command will show database aliases for both standard and composite databases.

Query
SHOW ALIASES FOR DATABASE
Result
+--------------------------------------------------------------------------------------------+
| name              | composite | database  | location | url                       | user    |
+--------------------------------------------------------------------------------------------+
| "films"           | NULL      | "movies"  | "local"  | NULL                      | NULL    |
| "motion pictures" | NULL      | "movies"  | "local"  | NULL                      | NULL    |
| "movie scripts"   | NULL      | "scripts" | "remote" | "neo4j+s://location:7687" | "alice" |
+--------------------------------------------------------------------------------------------+

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
Result
+---------------------------------------------------------+
| name    | composite | database | location | url  | user |
+---------------------------------------------------------+
| "films" | NULL      | "movies" | "local"  | NULL | NULL |
+---------------------------------------------------------+

Show detailed aliases information for a database

Query
SHOW ALIASES FOR DATABASE YIELD *
Result
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name              | composite | database  | location | url                       | user    | driver                                                                                                                                                                                                         | properties                |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "films"           | NULL      | "movies"  | "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, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H} | {}                        |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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
Result
+-------+
| count |
+-------+
| 3     |
+-------+

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 are ordered by the database column using ORDER BY.

  • The results have been filtered to only show database alias names containing 'e'.

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

Result
+-----------------------------------------------------------+
| name              | url                       | database  |
+-----------------------------------------------------------+
| "motion pictures" | NULL                      | "movies"  |
| "movie scripts"   | "neo4j+s://location:7687" | "scripts" |
+-----------------------------------------------------------+

Create database aliases

Database aliases can be created using CREATE ALIAS. The command supports the creation of both local and remote database aliases. For more information on local and remote database aliases as part of a composite database, see Create database aliases in composite databases.

The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges.

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

Create database aliases for local databases

A local database alias targets a database within the same DBMS.

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

When you create a local database alias, it shows up in the aliases column provided by the command SHOW DATABASES and in the SHOW ALIASES FOR DATABASE command.

Query
SHOW DATABASE `northwind`
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 | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Query
SHOW ALIAS `northwind` FOR DATABASE
Result
+---------------------------------------------------------------------------+
| name        | composite | database               | location | url  | user |
+---------------------------------------------------------------------------+
| "northwind" | NULL      | "northwind-graph-2021" | "local"  | NULL | NULL |
+---------------------------------------------------------------------------+

Use IF EXISTS or OR REPLACE when creating database aliases

The CREATE ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database alias already exists. There are two ways to circumvent this behavior.

First, appending IF NOT EXISTS to the command ensures that no error is returned and nothing happens should the database alias already exist.

Query
CREATE ALIAS `northwind` IF NOT EXISTS  FOR DATABASE `northwind-graph-2021`

Second, adding OR REPLACE to the command results in any existing database being deleted and a new one being created.

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

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

The IF NOT EXISTS and OR REPLACE parts of these commands cannot be used together.

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

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

Query
SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties
Result
+------------------------------------------------------+
| name             | properties                        |
+------------------------------------------------------+
| "northwind-2022" | {index: 3, newestnorthwind: TRUE} |
+------------------------------------------------------+

Create database aliases for remote databases

A database alias can target a remote database by providing an URL and the credentials of a user on the remote Neo4j DBMS. See Configuring remote database aliases for the necessary configurations.

As with local database aliases, creating remote database aliases allows IF NOT EXISTS and OR REPLACE clauses. Both check for any remote or local database aliases.

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

When you create a database alias targeting a remote database, its details can be shown with the SHOW ALIASES FOR DATABASE command.

Query
SHOW ALIAS `remote-northwind`
FOR DATABASE
Result
+----------------------------------------------------------------------------------------------------------+
| name               | composite | database               | location | url                       | user    |
+----------------------------------------------------------------------------------------------------------+
| "remote-northwind" | NULL      | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" |
+----------------------------------------------------------------------------------------------------------+

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

This is the list of the allowed driver settings for remote database aliases:

Table 1. dbms.routing.driver.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 2. dbms.routing.driver.connection.connect_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 3. dbms.routing.driver.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 4. dbms.routing.driver.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 5. dbms.routing.driver.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 6. dbms.routing.driver.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

The below query creates a remote database alias using driver settings:

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
}

When a database alias targeting 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 *
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} | {}         |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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

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

Query
SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties
Result
+--------------------------------------------------------------+
| name                    | properties                         |
+--------------------------------------------------------------+
| "remote-northwind-2021" | {index: 6, newestnorthwind: FALSE} |
+--------------------------------------------------------------+

Alter 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 in the The DBMS ALIAS MANAGEMENT privileges. Only the clauses used will be altered.

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

Alter local database aliases

Example of altering a local database alias target.

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

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`
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 | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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

Alter 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'
}

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 fall back to the default value.

Remove 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 {}

Alter 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' }
Query
ALTER ALIAS `movie scripts` SET DATABASE PROPERTIES { nameContainsSpace: true }

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

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

Delete database aliases

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

Delete local database aliases

Delete a local database alias.

Query
DROP ALIAS `northwind` FOR 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`
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 | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Delete remote database aliases

Delete a remote database alias.

Query
DROP ALIAS `remote-northwind` FOR DATABASE

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

Query
SHOW ALIASES `remote-northwind` FOR DATABASE
Result
+-----------------------------------------------------+
| name | composite | database | location | url | user |
+-----------------------------------------------------+
+-----------------------------------------------------+

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