Cypher25 default language

[renetapopova]

Replaces #2153

[Hunterness]

Only got started on the review, have looked at 11/21 files and have all the big ones left. But figured I'd post the comments I have so far as I'm pausing for the day.

Status: 3 open comments

[Hunterness]

I feel like it's a bit odd to have the new label when only parts of the command is new. most of it is not introduced in this version 🤔

[Hunterness]

or is this to indicate that Cypher 25 in general is introduced then 🤔

[renetapopova]

The label means that they can use this Cypher 25 syntax with this version (whichever it will be). However, what you say is also valid. I'll discuss it with Natalia and Jens.

[Hunterness]

feels like you missed the default language part here? (especially with the \| at the end of the SET OPTION option value row)

[renetapopova]

I haven't missed it. See above.

[Hunterness]

if you didn't miss it you should remove the \| at the end, but as it should be available in both Cypher 5 and in Cypher 25 I still think you missed it, see my motivation on the comment below (in list of comments)/above (when looking at the file)

[Hunterness]

is there actually any syntax differences in alter that would require the tabbed examples? 🤔 the previous PR didn't do tabs for alter 🤷

[renetapopova]

Do we have SET DEFAULT LANGUAGE CYPHER {5\|25} now? If yes, from which version of the server is it available? It's not in the docs.

[Hunterness]

Marks PR was the one to add it to docs so yeah, it's not documented yet...

The command has been merged to both Cypher 5 and 25, but only the SET ... 5 version is generally available as the 25 option is hidden behind the cypher 25 feature flag. We decided that we didn't want to add it to documentation until both values were available, and then document that it exists in both Cypher 5 and Cypher 25.

So for both create and alter, all 4 of:

CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5
CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 25
CYPHER 25 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5
CYPHER 25 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 25 

will be valid once we release Cypher 25, but at the moment only

CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5

is, hence us skipping documenting it until all 4 is allowed if that makes sense

[Hunterness]

Still have 2 files left to look at, the privilege file (how did you get over 700 lines changed from our 90 something on the previous PR? XD) and the manage aliases for standard database file (only like 200 more lines changed than the previous PR :P)

Status: 5 open comments

[Hunterness]

Suggested change

	The most common variations include parts of the commands that are optional, or that can have multiple values.
	This page summarizes the various command syntax options.
	Some variations are indicated using special characters.
	See <<administration-syntax-reading,Reading the administration commands syntax>> for details.
	It also includes examples for both Cypher 5 and Cypher 25 when available.
	The most common variations include parts of the commands that are optional, or that can have multiple values.
	Some variations are indicated using special characters.
	See <<administration-syntax-reading,Reading the administration commands syntax>> for details.
	This page summarizes the various command syntax options.
	It also includes examples for both Cypher 5 and Cypher 25 when available.

it felt weird to me to split the two parts talking about the variations

[Hunterness]

I know this isn't from this PR but I'm not sure what

Starting with Neo4j 2025.04, a database alias can also be set as the default database for a composite database.

above even means?

[renetapopova]

https://github.com/neo-technology/neo4j/pull/29748

[Hunterness]

so

Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

same as the regular alias page?

because I think "default database for a composite" doesn't make sense, the composite doesn't have a default database attached to it. (and if you mean alias in composite the composite bit should not go there)

Additionally I don't think constituent aliases can be default database still 🤔 (since you should only be able to access them though the composite and not on it's own) but I'd have to confirm that

[Hunterness]

I doubt we have this on the drop/alter/composite db pages so it feels odd to have it here. Maybe it should be on the intro page for all the multi-db admin commands instead of on just the start of some of them? 🤔

Like this page: https://neo4j-docs-operations-2372.surge.sh/operations-manual/2025.04/database-administration/

[Hunterness]

same as in the syntax page, we shouldn't have the hanging \| at the end of the line, and should not need to tab the examples either as there is no syntax difference between Cypher 5 and Cypher 25, both add the set default language clause (with the same syntax in difference to create that have different syntax in the two versions)

[Hunterness]

Suggested change

	== `ALTER DATABASE` options
	== Alter database options

not really relevant for this PR, just noticed it was inconsistent with the other headers:

• Alter database topology
• Alter database default language
• Alter database access mode
  vs
• ALTER DATABASE options

[Hunterness]

Review of alias page

[Hunterness]

Suggested change

	Starting with Neo4j 2025.04, a database alias can also be set as the default database.
	Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

maybe? to make it a bit clearer?

[Hunterness]

this sentence feels a bit like it's supposed to tie into some part above but that part no longer exists so it feels a bit odd on its own 🤔 Before we had just mentioned things around alias targets so starting with talking about how they handle targets felt more connect to things than this now does on its own

I'm not sure how to make it better, but maybe it just needs to fall into the rest of the restructuring and moving around that you've been doing 🤔 (I'll add it moved around below, keeping the wording you have which I might have other comments on below as well)

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 xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[The DBMS ALIAS MANAGEMENT privileges].
When connected to the DBMS over Bolt, administration commands are automatically routed to the `system` database.

[NOTE]
====
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.
====

There are two kinds of database aliases - local and remote:

Local database aliases::
A local database alias can only target a database within the same DBMS.
It can be used in all 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 target database, and not the local database alias.
+
[NOTE]
====
Starting with Neo4j 2025.06, a database can be assigned a default Cypher version.
However, local database aliases cannot be assigned a default Cypher version.
They always get the Cypher version of their target database.
====

Remote database aliases::
A remote database alias may target a database from another Neo4j DBMS.
It 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
* label:new[Introduced in 2025.06] Setting a default Cypher version for queries to the remote database.
+
Remote database aliases require configuration to safely connect to the remote target, which is described in xref::database-administration/aliases/remote-database-alias-configuration.adoc[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.
Starting with Neo4j 2025.06, a remote database alias can be assigned a default Cypher version.

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.
Starting with Neo4j 2025.04, a database alias can also be set as the default database.

This page describes managing database aliases for standard databases.
For aliases created as part of a xref:database-administration/composite-databases/concepts.adoc[composite database], see xref:database-administration/aliases/manage-aliases-composite-databases.adoc[].

[Hunterness]

The info around local/remote applies to both regular aliases and aliases in composite, so moving down

This page describes managing database aliases for standard databases.
For aliases created as part of a xref:database-administration/composite-databases/concepts.adoc[composite database], see xref:database-administration/aliases/manage-aliases-composite-databases.adoc[].

makes sense, to have the general alias description/info first before mentioning which bits are covered here vs elsewhere

[Hunterness]

See previous comment on this note from the alias in composite page

Suggested change

	Starting with Neo4j 2025.06, a database can be assigned a default Cypher version.
	However, local database aliases cannot be assigned a default Cypher version.
	They always get the Cypher version of their target database.
	Starting with Neo4j 2025.06, a database or remote alias can be assigned a default Cypher version.
	However, local database aliases cannot be assigned a default Cypher version.
	They always get the Cypher version of their target database.

[Hunterness]

do you need this here if it's also in the list right above?

[Hunterness]

I don't like this phrasing "standard and composite database aliases", to me that reads like it's aliases targeting standard and composite databases instead of targeting standard or being a constituent of a composite.

Additionally, I wouldn't call a remote alias a standard database alias either so it just feels odd in general (I probably wouldn't use standard database alias at all but 🤷).

Is this what you are after?

Suggested change

	The command returns a table of all standard and composite database aliases. +
	The command returns a table of all database aliases, whether they belong to a composite database or not. +

[Hunterness]

Suggested change

	ALTER ALIAS `remote-with-default-language` SET DATABASE
	DEFAULT LANGUAGE CYPHER 5
	ALTER ALIAS `remote-with-default-language` SET DATABASE DEFAULT LANGUAGE CYPHER 5

or

Suggested change

	ALTER ALIAS `remote-with-default-language` SET DATABASE
	DEFAULT LANGUAGE CYPHER 5
	ALTER ALIAS `remote-with-default-language`
	SET DATABASE DEFAULT LANGUAGE CYPHER 5

to not break the clause syntax between the lines when there's only one part

[Hunterness]

it feels slightly wrong to just call them USER, PASSWORD and DRIVER clauses, they are all part of the SET DATABASE clause (even if the SET DATABASE is on one line and the others on separate ones after that).

The ALTER ALIAS command technically have one clause: SET DATABASE <something> and then the <something> part can be or or more of TARGET [AT <url>], PROPERTIES, DEFAULT LANGUAGE, USER, PASSWORD or DRIVER without repeating the SET DATABASE for each of them. So I'm not sure what to call them here, but it felt odd that we here don't mention SET DATABASE where we in all of the other ones does 🤷 (target and properties at least)

[Hunterness]

can't add a suggestion here but wouldn't it be nicer to do

ALTER ALIAS `remote-northwind`
SET DATABASE TARGET `northwind-graph-2020` AT "neo4j+s://other-location:7687"

to mirror how it looks on the local version and not split the clause on two lines

[Hunterness]

similarly here, we could make it more visible that the individual parts are part of the SET DATABASE if we want to

ALTER ALIAS `remote-with-driver-settings`
SET DATABASE
  USER bob
  PASSWORD 'new_example_secret'
  DRIVER {
    connection_timeout: duration({ minutes: 1}),
    logging_level: 'debug'
  }

[Hunterness]

Suggested change

	To verify that the local database alias has been deleted, you can use the `SHOW ALIASES FOR DATABASE` command.
	To verify that the local database alias has been deleted, you can use the `SHOW DATABASES` command.

[Hunterness]

Started on the privilege file updates

[Hunterness]

since some of these are not in this page it might still be nice to have the links? Maybe not as a separate list but then combined with the list above

[Hunterness]

* Load data.

should this maybe say Manage load data security. to match the other ones (based on that we previously had a link to the LOAD privileges page to read more about it)

[Hunterness]

Suggested change

	You can also create a custom administrator role that can perform almost all DBMS capabilities, excluding database management.
	You can also create a custom administrator role that can perform almost all DBMS capabilities, excluding database management.

[Hunterness]

the example below doesn't copy the admin role though 🤔

We're still only granting and denying privileges on our own.

[Hunterness]

looks like we previously only had two examples of the second option/custom role as well 🤷

[Hunterness]

looking back in the docs history it looks like we had for 4.0 and 4.1 just one example that did copy admin and deny things (since we didn't have all privileges available to be granted yet at that point). Then in 4.2 it was updated to two examples, neither copying the admin role anymore 🤷

[Hunterness]

both of these examples are still nice on their own as they are, maybe add a third example that actually do CREATE ROLE newRole AS COPY OF admin and then revoke the ability to read/write/load data?

CREATE ROLE newRole AS COPY OF admin;
REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM newRole;
REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM newRole;
REVOKE GRANT WRITE ON GRAPH * FROM newRole;
REVOKE GRANT LOAD ON ALL DATA FROM newRole;

potentially also remove the index/constraint/name management

REVOKE GRANT CONSTRAINT MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT INDEX MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT NAME MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT SHOW CONSTRAINT ON DATABASE * FROM newRole;
REVOKE GRANT SHOW INDEX ON DATABASE * FROM newRole;

If you want to be fancy we could also change what they have access on to system only:

REVOKE GRANT ACCESS ON DATABASE * FROM newRole;
GRANT ACCESS ON DATABASE system TO newRole; 

[Hunterness]

also found a typo

Suggested change

	ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' }
	ALTER USER jake REMOVE AUTH 'native' SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' }

[Hunterness]

not changing the info line above this example?

A user that is granted the `SET USER STATUS` privilege is allowed to run the `ALTER USER` administration command with only the `SET STATUS` part:

vs

The `SET USER STATUS` privilege allows the user to run the `ALTER USER` administration command with only the `SET STATUS` part.

[Hunterness]

more missed updates below

A user that is granted the `SET USER HOME DATABASE` privilege is allowed to run the `ALTER USER` administration command with only the `SET HOME DATABASE` or `REMOVE HOME DATABASE` part:

vs

The `SET USER HOME DATABASE` privilege allows the user to run the `ALTER USER` administration command with only the `SET HOME DATABASE` or `REMOVE HOME DATABASE` part.

[Hunterness]

it feels odd to have this note in the home database section, either it should be in all of the sub-privilege sections or maybe move up to the ALTER USER section? 🤔

[neo4j-docops-agent]

This PR includes documentation updates
View the updated docs at https://neo4j-docs-operations-2372.surge.sh

New pages:

• Configure the Cypher default version
• Alter composite databases
• Start and stop composite databases
• Start and stop databases

Updated pages:

• DBMS privileges
• Configuration
• Managing database aliases in composite databases
• Managing database aliases for standard databases
• Create composite databases
• List composite databases
• Alter databases
• Configuration parameters
• Create databases

[Hunterness]

Next chunk of the privilege file updates

[Hunterness]

why remove the link to the page about how to read the syntax summaries?

[Hunterness]

I can see we had this comment before as well, not sure why we add it here since that is true for all privileges 🤔 the role you try to grant a privilege to must exist regardless of which privilege it is 🤷

[Hunterness]

a) the It is also possible to deny and revoke that privilege. probably belonged to the above example and not this one
b) that also feels like a more generic privilege thing

so I think we could skip the (or revoke) here in general and remove the old sentence 🤷

Suggested change

	You can grant (or revoke) the privilege to impersonate specific users or a subset of users using the following query:
	You can grant the privilege to impersonate specific users or a subset of users using the following query:

[Hunterness]

with the reordering you introduced some inaccurate statements. Now it was inaccurate already since we use the same role without actually removing the old privileges anyway but it got more so now.

Lets take a stab at having your order and make it work/accurate:

=== Grant privilege to impersonate all users

You can grant the privilege to impersonate all users using the `IMPERSONATE (*)` privilege.
For example:

.Query
[source, cypher, role=noplay]
----
GRANT IMPERSONATE (*) ON DBMS TO allUserImpersonator
----

As a result, the `allUserImpersonator` role has privileges that allow impersonating all users.
To list all privileges for the role `allUserImpersonator` as commands, use the following query:

.Query
[source, cypher, role=noplay]
----
SHOW ROLE allUserImpersonator PRIVILEGES AS COMMANDS
----
.Result
[options="header,footer", width="100%", cols="m"]
|===
| command
| "GRANT IMPERSONATE (*) ON DBMS TO `allUserImpersonator`"
a|Rows: 1
|===
----

=== Grant privilege to impersonate specific users

You can also grant the privilege to impersonate specific users or a subset of users.
For example:

.Query
[source, cypher, role=noplay]
----
GRANT IMPERSONATE (alice, bob) ON DBMS TO userImpersonator
----

As a result, the `userImpersonator` role has privileges that allow impersonating only `alice` and `bob`.
Then, you deny the privilege to impersonate `alice`:

.Query
[source, cypher, role=noplay]
----
DENY IMPERSONATE (alice) ON DBMS TO userImpersonator
----

As a result, the `userImpersonator` user would be able to impersonate only `bob`.

Things I updated:

• The all user example has a new role name (so it would need to be added to the test setup)
• The last sentence is updated to reflect what happens within this example and role instead of being a mix of this and the all user one
• Updated the intro sentence to not have both the following query: and For example:
• While I didn't add it here, it might be nice to add a SHOW for userImpersonator as well, showing both the grant on alice and bob and the deny on alice?

[Hunterness]

Another alternative for the deny example if we want to keep it being impersonate all users, except `alice` is to have a third role which gets both the GRANT IMPERSONATE (*) and DENY IMPERSONATE (alice) privileges (or reuse the role from the all example, but then you'd need to mention that we already have the GRANT IMPERSONATE (*) I think)

[Hunterness]

here as well as above, why remove this?

[Hunterness]

@NataliaIvakina this one too

[Hunterness]

same as the above ones, why remove this link?

[Hunterness]

so

Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

same as the regular alias page?

because I think "default database for a composite" doesn't make sense, the composite doesn't have a default database attached to it. (and if you mean alias in composite the composite bit should not go there)

Additionally I don't think constituent aliases can be default database still 🤔 (since you should only be able to access them though the composite and not on it's own) but I'd have to confirm that

[Hunterness]

Suggested change

	The DBMS privileges for alias management can be granted, denied and revoked like other privileges and can be applied to both local and remote aliases.
	The DBMS privileges for alias management can be granted, denied and revoked like other privileges and applies to both local and remote aliases.

might actually be better, saying can be applied to might indicate that you can have/have two versions of the privileges, one for each 🤔

[Hunterness]

Got through the file, now everything have been looked at once

[Hunterness]

same as the ones yesterday, why remove this linking?

[Hunterness]

I can see you removed the one at least in the next section as well, I'll not add more comments on these but I don't think any of them should have been removed as they are links to read more about how to read the syntax summaries right below

[Hunterness]

wouldn't you need to create the serverManager and serverLister roles as well to the test setup at the top of the file? 🤔

[Hunterness]

since we just wrote about requiring two privileges it feels a bit like For example connects to that and not just this privilege :(

maybe just having a new like in between is enough to separate them and make it clearer that the example is for this section/privilege and not connected to the sentence just before it?

Suggested change

	For example:
	For example:

[Hunterness]

I think most other sections have ...Shower and not ...Lister for the roles that can only show things? 🤔

[Hunterness]

Looks like the alias section has Lister but the roles, users and privileges has Shower (the others don't have just show privileges)

[Hunterness]

Feels odd to me to have the For example: on the same line as A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands. if you have a line break after the first line 🤔

I would probably prefer either having all of them on new lines:

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege.
A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands.
For example:

or no newlines:

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege. A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands. For example:

or do as I thought on the previous section and add one empty line before the For example::

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege.
A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands.

For example:

(all examples of how it would look rendered and not in code with the +/line breaks between sentences)

I can see we also have this in the sections further below (and the one just above), so whatever we decide on should probably be the same in all those places as well.

[Hunterness]

I know this is from before but allow querying settings feels odd to me, allow showing settings/allow listing settings/allow viewing settings might be better?

[Hunterness]

Suggested change

	=== Grant privilege to show specific settings
	=== Grant privilege to show execute all but some settings

[Hunterness]

Suggested change

	You can grant the privilege to show all settings using `SHOW SETTINGS *` and deny the unwanted settings. +
	You can grant the privilege to show all but a few settings using `SHOW SETTINGS *` and deny the unwanted settings. +

[Hunterness]

so just above here we have

As the query result shows, access to any setting starting with `dbms.security` are blocked, but the rest can still be queried.

which have the same weirdness around saying querying and now also access.

[Hunterness]

I also saw it in at least the syntax table so I think it's just throughout this section

[l-heemann]

Yeah I think we have some language weirdness going on.
query is overloaded in meaning both:
"I query (ask) the database" and "I send a query (question) to the database"

and access has somewhat special meaning in the cypher-operations context where I think "Access to the setting" may be misinterpreted as "The ability to interact/modify the setting" rather than "The ability to view/see/show the setting"

[Hunterness]

since I can't comment below:

* Create, alter, and drop databases and aliases.
* Enable, alter, rename, reallocate, deallocate, and drop servers

should both probably also say show? (show databases might not be a privilege as such but show aliases are at least and those lines are combined into one so (plus the database privileges affect which databases are returned by show databases so it's not that wrong 🤷))