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.
SHOW ALIASES FOR DATABASE
+--------------------------------------------------------------------------------------------------+ | 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.
CREATE ALIAS garden.flowers
FOR DATABASE `perennial-flowers`
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.
SHOW DATABASE garden YIELD name, type, constituents
+-------------------------------------------------------------+ | name | type | constituents | +-------------------------------------------------------------+ | "garden" | "composite" | ["garden.flowers", "garden.trees"] | +-------------------------------------------------------------+
SHOW ALIASES FOR DATABASE
WHERE composite = 'garden'
+-----------------------------------------------------------------------------------------------------+ | 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.
CREATE ALIAS yard FOR DATABASE garden
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.
ALTER ALIAS garden.flowers SET DATABASE PROPERTIES { perennial: true }
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.
SHOW ALIASES FOR DATABASE YIELD *
+-----------------------------------------------------------------------------------------------------------------------------------+ | 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.
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.
SHOW ALIASES FOR DATABASE
+--------------------------------------------------------------------------------------------------+ | 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.
SHOW DATABASE garden YIELD name, type, constituents
+-------------------------------------------+ | 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
:
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:
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.
CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`
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
:
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:
{
"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.
Handling parameters
Further special handling with parameters is needed for database aliases and similarly named composite databases.
Consider the setup:
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.