Update detailed description section on 'Database alias names that contain dots'

Author: l-heemann

modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc

@@ -52,7 +52,7 @@ For a description of all the returned columns of this command, and for ways in w
 
 Both local and remote database aliases can be part of a xref::database-administration/composite-databases/concepts.adoc[composite database].
 
-The database alias is made of two parts, separated by a dot: the namespace and the alias name.
+The database alias consists of two parts, separated by a dot: the namespace and the alias name.
 
 The namespace must be the name of the composite database.
 
@@ -214,12 +214,158 @@ SHOW DATABASE garden YIELD name, type, constituents
 ----
 
 [[alias-management-escaping]]
-== Database alias names and escaping
+== Database alias names that contain dots
 
 Naming database aliases in composite databases follows the same rule as xref:database-administration/aliases/naming-aliases.adoc[naming aliases for standard databases].
 However, when it comes to escaping names using backticks, there are some additional things to consider:
 
-=== Quoting database alias and composite database names
+Dots in alias names are ambiguous.
+They could either be interpreted as part of the name itself, or as the dot that separates a composite namespace from the alias name.
+
+=== Conflicting names
+Before Neo4j 2025.06 it was possible to create conflicting aliases such as the constituent alias `flowers` within the composite database `garden` as well as the non-composite local alias `garden.flowers`.
+Both of these would be referred to by the same name `garden.flowers`.
+
+Neo4j 2025.06 ensures that no such conflicts exist and will throw an exception when attempting to create a new alias with the same name as an existing alias.
+
+[.tabbed-example]
+=====
+[role=include-with-cypher-5]
+======
+Creating a regular alias with the same name as an existing composite constituent is disallowed:
+
+.Query
+[source, cypher]
+----
+CYPHER 5 CREATE COMPOSITE DATABASE `garden`
+CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+----
+
+.Error message
+[source, output, role="noheader"]
+----
+Failed to create the specified database alias 'garden.flowers': Database name or alias already exists.
+----
+
+======
+
+[role=include-with-cypher-25 label--new-2025.06]
+======
+
+Creating a regular alias with the same name as an existing composite constituent is disallowed.
+The Cypher 25 syntax makes no distinction between the names to clarify that they are considered equivalent.
+
+.Query
+[source, cypher]
+----
+CYPHER 25 CREATE COMPOSITE DATABASE `garden`
+CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+----
+
+.Error message
+[source, output, role="noheader"]
+----
+Failed to create the specified database alias 'garden.flowers': Database name or alias already exists.
+----
+======
+=====
+
+[.tabbed-example]
+=====
+[role=include-with-cypher-5]
+======
+Creating a composite constituent with the same name as an existing non-composite alias is disallowed. This example scenario is prevented already on the second line, thus the constituent on the third line cannot be created.
+
+.Query
+[source, cypher]
+----
+CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE COMPOSITE DATABASE `garden`
+CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph`
+----
+
+.Error message
+[source, output, role="noheader"]
+----
+Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name.
+----
+
+======
+
+[role=include-with-cypher-25 label--new-2025.06]
+======
+
+Creating a composite constituent with the same name as an existing non-composite alias is disallowed.
+This example scenario is prevented already on the second line, thus the constituent on the third line cannot be created.
+The Cypher 25 syntax makes no distinction between the names to clarify that they are considered equivalent.
+
+.Query
+[source, cypher]
+----
+CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+CYPHER 25 CREATE COMPOSITE DATABASE `garden`
+CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
+----
+
+.Error message
+[source, output, role="noheader"]
+----
+Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name.
+----
+======
+=====
+
+
+Creating a composite constituent with the same name as an existing non-composite alias is disallowed:
+
+=== Cypher 25 specific behaviour
+==== Accessing an existing alias with dots
+
+Cypher 25 relies on the guarantee that no conflicting names are allowed in Neo4j 2025.06 and later.
+The following queries all act on the same alias, regardless if that alias is a composite constituent or not.
+The special quoting of separate name parts that was necessary in Cypher 5 is not necessary / permitted in Cypher 25.
+
+.Parameters
+[source, javascript]
+----
+{
+  "name": "my.garden.beautiful.flowers"
+}
+----
+.Query
+[source, cypher]
+----
+CYPHER 25 ALTER ALIAS `my.garden.beautiful.flowers` SET DATABASE PROPERTIES { perennial: true }
+CYPHER 25 ALTER ALIAS $name SET DATABASE PROPERTIES { perennial: true }
+CYPHER 25 USE `my.garden.beautiful.flowers` RETURN 1
+----
+
+==== Creating a new alias with dots
+During `CREATE`, Cypher25 will split the given name on each dot, left to right, and check if a corresponding composite database exists.
+If no composite database is found, Cypher25 will fall back to creating a regular non-composite alias instead.
+
+The following query attempts to create in order:
+
+* Constituent alias `garden.beautiful.flowers` within composite database `my`.
+* Constituent alias `beautiful.flowers` within composite database `my.garden`.
+* Constituent alias `flowers` within composite database `my.garden.beautiul`.
+* Regular non-composite alias `my.garden.beautiful.flowers`.
+
+.Query
+[source, cypher]
+----
+CYPHER 25 CREATE COMPOSITE DATABASE `my.garden`
+CYPHER 25 CREATE ALIAS `my.garden.beautiful.flowers` FOR DATABASE `northwind-graph`
+----
+Since it finds the composite database `my.garden` it will create the constituent alias `beautiful.flowers` within the found composite.
+
+
+
+=== Cypher 5 specific behaviour
+
+==== Quoting database alias and composite database names
 
 The composite database name and the database alias name need to be quoted 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`++`.
@@ -236,18 +382,18 @@ CREATE DATABASE `northwind-graph`;
 .Query
 [source, cypher]
 ----
-CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph`
 ----
 
 When not quoted individually, a database alias with the full name `my alias with.dots and spaces` gets created instead:
 
 .Query
 [source, cypher]
 ----
-CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph`
 ----
 
-=== Handling multiple dots
+==== Handling multiple dots
 
 //Examples where dots are not separators between composite name and alias name are impossible to test, because the right escaping cannot be inferred automatically.
 
@@ -257,18 +403,18 @@ Though these always need to be quoted in order to avoid ambiguity with the compo
 .Query
 [source, cypher, role=test-skip]
 ----
-CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`
 ----
 
 .Query
 [source, cypher, role=test-skip]
 ----
-CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph`
 ----
 
 
 [role=label--deprecated]
-=== Single dots and local database aliases
+==== 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`.
@@ -277,10 +423,10 @@ If no such database exists, however, the same query will instead create a databa
 .Query
 [source, cypher]
 ----
-CREATE ALIAS some.alias FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE ALIAS some.alias FOR DATABASE `northwind-graph`
 ----
 
-=== Handling parameters
+==== Handling parameters
 
 When using parameters, names cannot be quoted.
 When the given parameter includes dots, the first dot will be considered the divider for the composite database.
@@ -298,7 +444,7 @@ Consider the query with parameter:
 .Query
 [source, cypher]
 ----
-CREATE ALIAS $aliasname FOR DATABASE `northwind-graph`
+CYPHER 5 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.
@@ -320,7 +466,7 @@ If `mycompositedatabase` does not exist, the command will create a database alia
 
 In these cases, it is recommended to avoid parameters and explicitly quote the composite database name and alias name separately to avoid ambiguity.
 
-=== Handling parameters
+==== Handling parameters
 
 Further special handling with parameters is needed for database aliases and similarly named composite databases.
 
@@ -329,8 +475,8 @@ Consider the setup:
 .Query
 [source, cypher, role="noheader test-skip"]
 ----
-CREATE COMPOSITE DATABASE foo
-CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph`
+CYPHER 5 CREATE COMPOSITE DATABASE foo
+CYPHER 5 CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph`
 ----
 
 The alias `foo.bar` does not belong to the composite database `foo`.
@@ -348,7 +494,7 @@ Dropping this alias using parameters fails with an error about a missing alias:
 .Query
 [source, cypher, role=test-fail]
 ----
-DROP ALIAS $aliasname FOR DATABASE
+CYPHER 5 DROP ALIAS $aliasname FOR DATABASE
 ----
 
 .Error message