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. |
Command | Syntax |
---|---|
Show Database Alias |
Lists both local and remote database aliases, optionally filtered on the alias name. |
Create Local Alias |
|
Create Remote Alias |
|
Alter Local Alias |
|
Alter Remote Alias |
|
Drop Alias |
Drop either a local or remote database alias. |
This is the list of the allowed driver settings for remote database aliases.
Description |
SSL for remote database alias drivers is configured through the target url scheme.
If |
Valid values |
Boolean |
Default value |
true |
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 |
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 |
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 |
Default value |
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 |
Default value |
Description |
Sets level for driver internal logging. |
Valid values |
org.neo4j.logging.Level. One of |
Default value |
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 |
---|---|---|
|
The fully qualified name of the database alias. Default Output |
|
|
The name of the target database. Default Output |
|
|
The location of the database, either |
|
|
Target location or |
|
|
User connecting to the remote database or |
|
|
The driver options for connection to the remote database or |
|
|
Any properties set on the database alias. |
|
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.
A summary of all available database aliases can be displayed using the command SHOW ALIASES FOR DATABASE
.
SHOW ALIASES FOR DATABASE
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
To list just one database alias, the SHOW ALIASES
command takes an alias name;
SHOW ALIAS films FOR DATABASES
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
Rows: 1 |
SHOW ALIAS library.romance FOR DATABASES
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
Rows: 1 |
SHOW ALIASES FOR DATABASE YIELD *
name | database | location | url | user | driver | properties |
---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
The number of database aliases can be seen using a count()
aggregation with YIELD
and RETURN
.
SHOW ALIASES FOR DATABASE YIELD *
RETURN count(*) as count
count |
---|
|
Rows: 1 |
It is possible to filter and sort the results by using YIELD
, ORDER BY
and WHERE
.
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 usingORDER BY
.
It is also possible to use SKIP
and LIMIT
to paginate the results.
name | url | database |
---|---|---|
|
|
|
|
|
|
|
|
|
Rows: 3 |
Creating database aliases
Database aliases can be created using CREATE ALIAS
.
The required privileges are described here.
Syntax | Comment |
---|---|
|
Create a local alias. |
|
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 |
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.
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.
SHOW DATABASE `northwind`
name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents |
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 1 |
SHOW ALIAS `northwind` FOR DATABASE
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
Rows: 1 |
Local database aliases can also be given properties.
These properties can then be used in queries with the graph.propertiesByName()
function.
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.
SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties
name | properties |
---|---|
|
|
Rows: 1 |
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.
CREATE ALIAS `northwind` IF NOT EXISTS FOR DATABASE `northwind-graph-2020`
(no changes, no records)
It is also possible to replace a database alias. The old alias may be either local or remote.
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:
DROP ALIAS `northwind` IF EXISTS FOR DATABASE
CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2020`
Creating remote database aliases
Database aliases can also point to remote databases by providing an url and the credentials of a user on the remote Neo4j DBMS. See Connecting remote databases for the necessary configurations.
Creating remote database aliases also allows IF NOT EXISTS
and OR REPLACE
clauses.
Both check for any remote or local database aliases.
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.
SHOW ALIAS `remote-northwind`
FOR DATABASE
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
Rows: 1 |
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.
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.
SHOW ALIAS `remote-with-driver-settings` FOR DATABASE YIELD *
name | database | location | url | user | driver | properties |
---|---|---|---|---|---|---|
|
|
|
|
|
|
|
Rows: 1 |
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.
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.
SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties
name | properties |
---|---|
|
|
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.
CREATE ALIAS garden.flowers
FOR DATABASE `perennial-flowers`
System updates: 1
Rows: 0
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.
SHOW DATABASE garden YIELD name, type, constituents
name | type | constituents |
---|---|---|
|
|
|
Rows: 1 |
SHOW ALIASES FOR DATABASE WHERE name STARTS WITH 'garden'
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
Rows: 1 |
Database aliases cannot point to a composite database.
CREATE ALIAS yard FOR DATABASE garden
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 |
---|---|
|
Modify database target of a local alias. The clauses can be applied in any order, while at least one clause needs to be set. |
|
Modify a remote alias. The clauses can be applied in any order, while at least one clause needs to be set. |
Example of altering a local database alias target.
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
.
SHOW DATABASE `northwind-graph-2021`
name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents |
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 1 |
Example of altering a remote database alias target.
ALTER ALIAS `remote-northwind` SET DATABASE
TARGET `northwind-graph-2020` AT "neo4j+s://other-location:7687"
System updates: 1
Rows: 0
Example of altering a remote database alias credentials and driver settings.
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 |
Example of altering a remote database alias to remove all custom driver settings.
ALTER ALIAS `movie scripts` SET DATABASE
DRIVER {}
System updates: 1
Rows: 0
Examples of altering local and remote database alias properties.
ALTER ALIAS `motion pictures` SET DATABASE PROPERTIES { nameContainsSpace: true, moreInfo: 'no, not really' }
System updates: 1
Rows: 0
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.
Examples of altering local and remote database alias in composite databases.
ALTER ALIAS garden.flowers SET DATABASE PROPERTIES { perennial: true }
System updates: 1
Rows: 0
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.
SHOW ALIASES FOR DATABASE YIELD *
WHERE name IN ['northwind', 'remote-northwind', 'remote-with-driver-settings', 'movie scripts',
'motion pictures', 'garden.flowers', 'garden.trees']
name | database | location | url | user | driver | properties |
---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 7 |
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.
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.
Delete a local database alias.
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
.
SHOW DATABASE `northwind-graph-2021`
name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents |
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 1 |
Delete a remote database alias.
DROP ALIAS `remote-northwind` FOR DATABASE
System updates: 1
Rows: 0
Delete an alias in a composite database.
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.
SHOW ALIASES FOR DATABASE
name | database | location | url | user |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 9 |
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.
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 ( |
When it comes to escaping names using backticks, there are some additional things to consider around database aliases in composite databases:
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
:
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:
CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph`
System updates: 1
Rows: 0
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.
CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`
System updates: 1
Rows: 0
CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph`
System updates: 1
Rows: 0
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
:
CREATE ALIAS some.alias FOR DATABASE `northwind-graph`
System updates: 1
Rows: 0
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:
{
"aliasname": "mySimpleCompositeDatabase.myAlias"
}
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:
{
"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.
Further special handling with parameters is needed for database aliases and similarly named composite databases.
Consider the set-up:
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:
{
"aliasname": "foo.bar"
}
DROP ALIAS $aliasname FOR DATABASE
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?