Managing database aliases in composite databases

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

List database aliases in composite databases

Available database aliases in composite databases can be seen using SHOW ALIASES FOR DATABASE. The name of the composite database a particular database alias appears in the returned composite column.

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

Query

SHOW ALIASES FOR DATABASE

Result

+--------------------------------------------------------------------------------------------------+
| name              | composite | database        | location | url                       | user    |
+--------------------------------------------------------------------------------------------------+
| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "alice" |
| "library.sci-fi"  | "library" | "sci-fi-books"  | "local"  | NULL                      | NULL    |
+--------------------------------------------------------------------------------------------------+

For a description of all the returned columns of this command, and for ways in which the SHOW ALIASES FOR DATABASE command can be filtered for aliases, see list aliases for standard databases.

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.

Query

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

Query

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

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

Result

+-------------------------------------------------------------+
| name     | type        | constituents                       |
+-------------------------------------------------------------+
| "garden" | "composite" | ["garden.flowers", "garden.trees"] |
+-------------------------------------------------------------+

Query

SHOW ALIASES FOR DATABASE
WHERE composite = 'garden'

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

Database aliases cannot target a composite database.

Query

CREATE ALIAS yard FOR DATABASE garden

Error message

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

Alter local and remote database aliases in composite databases

Local and remote database aliases belonging to a composite database can be altered using the ALTER ALIAS command. This is the same command that is used for altering aliases that are not part of a composite database.

Query

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

Query

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

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 *

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}  |
| "library.romance" | "library" | "romance-books"     | "remote" | "neo4j+s://location:7687" | "alice" | {}     | {}                |
| "library.sci-fi"  | "library" | "sci-fi-books"      | "local"  | NULL                      | NULL    | NULL   | {}                |
+-----------------------------------------------------------------------------------------------------------------------------------+

Delete database aliases in composite databases

To delete an alias in a composite database, use the DROP ALIAS FOR DATABASE command. This is the same command that is used for deleting aliases that are not part of a composite database.

Query

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

Result

+--------------------------------------------------------------------------------------------------+
| name              | composite | database        | location | url                       | user    |
+--------------------------------------------------------------------------------------------------+
| "garden.trees"    | "garden"  | "updatedtrees"  | "remote" | "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    |
+--------------------------------------------------------------------------------------------------+

Additionally, deleted aliases will no longer appear in the constituents column for the SHOW DATABASE command.

Query

SHOW DATABASE garden YIELD name, type, constituents

Result

+-------------------------------------------+
| name     | type        | constituents     |
+-------------------------------------------+
| "garden" | "composite" | ["garden.trees"] |
+-------------------------------------------+

Database alias names and escaping

Naming database aliases in composite databases follows the same rule as naming aliases for standard databases. However, when it comes to escaping names using backticks, there are some additional things to consider:

Escaping database alias and composite database names

The composite database name and the database alias name need to be escaped individually. Backticks may be added regardless of whether the name contains special characters or not, so it is good practice to always backtick both names, e.g. `composite`.`alias`.

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`

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`

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`

Query

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

Single dots and local database aliases

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`

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.

Handling parameters

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

Consider the setup:

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.