Skip to content

Allow parameters in CREATE/ALTER DATABASE TOPOLOGY #1911

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 31, 2024
Merged

Allow parameters in CREATE/ALTER DATABASE TOPOLOGY #1911

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9944644
Fix broken references
l-heemann Oct 25, 2024
b9d30f0
Add section about parameters in CREATE/ALTER DATABASE TOPOLOGY
l-heemann Oct 25, 2024
fd47a14
Apply suggestions from code review
l-heemann Oct 28, 2024
4cc8fb0
Include $dbname in parameter example
l-heemann Oct 28, 2024
efb71fc
Separate parameter examples for CREATE and ALTER
l-heemann Oct 28, 2024
ae35bd1
Apply suggestions from code review
l-heemann Oct 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions modules/ROOT/pages/clustering/databases.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,23 @@ However, over time, or after several `CREATE DATABASE` commands have been issued
At this point you can run `REALLOCATE DATABASES` to make the cluster re-balance databases across all servers that are part of the cluster.
====

The `CREATE DATABASE` and `ALTER DATABASE` commands support the usage of link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/syntax/parameters[parameters] when providing the number of primaries and secondaries.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this is overkill. We don't mention that the name could be a parameter. Maybe enough to add a second example to the create example. Something like:

CREATE DATABASE foo TOPOLOGY 3 PRIMARIES 2 SECONDARIES

or with parameters

{
  "dbname": "foo",
  "primary": 1,
  "secondary": 2
}

CREATE DATABASE $dbName TOPOLOGY $primary PRIMARIES $secondary SECONDARIES

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's useful to have both.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the dbname 👍

I feel like it would be overkill to have one parameter example for create and another for alter alter, by mentioning ALTER in the text we get away with only the one. Let me know if you'd prefer the or with parameters approach with one for create and one for alter 🤷

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a better practice is to keep them separate because whoever is looking for how to alter a database won't be looking at the create a database section. Of course, they might find a way to the example, but nobody reads the docs from top to bottom. A workaround could be to mention the feature, from when it is supported, etc., in the alter section and then refer to the create section, but it might be even more complicated.


.Parameters
[source,javascript, indent=0]
----
{
"primary": 1,
"secondary": 2
}
----

.Query
[source, cypher, indent=0]
----
CREATE DATABASE foo TOPOLOGY $primary PRIMARIES $secondary SECONDARIES
----

[[alter-database]]
== `ALTER DATABASE`

Expand Down Expand Up @@ -75,7 +92,7 @@ Keep in mind that during such a transition, the database will be unavailable for
`ALTER DATABASE` commands are optionally idempotent, with the default behavior to fail with an error if the database does not exist.
Appending `IF EXISTS` to the command ensures that no error is returned and nothing happens should the database not exist.

If the `ALTER DATABASE` command decreases the number of allocations of a database, allocations on xref:clustering/servers.adoc#_cordoned_servers[cordoned servers] are removed first.
If the `ALTER DATABASE` command decreases the number of allocations of a database, allocations on xref:clustering/servers.adoc#cordoned_state[cordoned servers] are removed first.

.Query
[source, cypher]
Expand Down Expand Up @@ -401,7 +418,7 @@ In this case, the address for `server01` is `localhost:7687` and thus, the serve
The topology of `foo` is stored in the `system` database and when you create it, it is allocated according to the default topology (which can be shown with `CALL dbms.showTopologyGraphConfig`).
This may be different from the topology of `foo` when it was backed up.
If you want to ensure a certain allocation across the cluster, you can specify the desired topology with the `TOPOLOGY` clause in the `CREATE DATABASE` command.
See <<#_create_database, `CREATE DATABASE`>> for more information.
See <<#create-database, `CREATE DATABASE`>> for more information.
+
[source, cypher, role=noplay]
----
Expand Down
3 changes: 2 additions & 1 deletion modules/ROOT/pages/clustering/servers.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,12 @@ When a server is in the deallocated state, it no longer hosts any databases besi
Additionally, deallocated servers cannot have any further databases allocated to them.
Note that there is a known situation in which a previously deallocated offline server can transiently show as deallocating when restarting, it will, however, eventually return to the deallocated state without intervention.

[#cordoned_state]
=== Cordoned state

The _Cordoned_ state is similar to _Deallocating_ in that servers in this state will not be allocated to host additional databases.
Unlike _Deallocating_ however, cordoned servers do not lose the databases they already host.
It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.
It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.

A server is transitioned from the _Enabled_ state to the _Cordoned_ state by executing the procedure `dbms.cluster.cordonServer`.
A server in the _Cordoned_ state may be transitioned to _Deallocating_, or back to _Enabled_.
Expand Down