diff --git a/.backportrc.json b/.backportrc.json new file mode 100644 index 000000000..65699b417 --- /dev/null +++ b/.backportrc.json @@ -0,0 +1,5 @@ +{ + "repoOwner": "Neo4j", + "repoName": "docs-operations", + "prTitle": "[Cherry-pick][{{targetBranch}}] {{commitMessages}}" + } \ No newline at end of file diff --git a/.github/workflows/auto-backport.yml b/.github/workflows/auto-backport.yml new file mode 100644 index 000000000..deac30009 --- /dev/null +++ b/.github/workflows/auto-backport.yml @@ -0,0 +1,30 @@ +name: auto-cherry-pick +on: + pull_request_target: + types: ["closed"] + +jobs: + backport: + name: Cherry-pick PR + runs-on: [ubuntu-latest] + if: | + github.event.pull_request.merged == true + && contains(github.event.pull_request.labels.*.name, 'auto-cherry-pick') + && github.event.action == 'closed' + steps: + - name: Cherry-pick action + uses: sorenlouv/backport-github-action@929f69d04adbc196d982e60f02837b6cc00b3129 + with: + github_token: ${{ secrets.DOCS_AUTO_CP_TOKEN }} + auto_backport_label_prefix: auto-cherry-pick-to- + add_original_reviewers: false + + - name: Info log + if: ${{ success() }} + run: cat ~/.backport/backport.info.log + + - name: Debug log + if: ${{ failure() }} + run: cat ~/.backport/backport.debug.log + + diff --git a/README.adoc b/README.adoc index fe344139d..df2d60c9d 100644 --- a/README.adoc +++ b/README.adoc @@ -35,3 +35,34 @@ When you run `npm start`, the project is monitored for updates to asciidoc files If a change to an asciidoc file is detected the site is automatically rebuilt. +== Enable automatic cherry-picking on a PR + +To enable automatic cherry-picking on a PR, add the label `auto-cherry-pick` to it. +Without it, the responsible GitHub action is not going to be triggered. + +To select the target branches you would like to cherry-pick your PR to, add labels of the following structure: `auto-cherry-pick-to-`. +For example: `auto-cherry-pick-to-main` to cherry-pick it to the branch `main` or `auto-cherry-pick-to-5.x` for the branch `5.x`. +You may even add new labels for branches that do not have such a label yet. + +The feature is triggered by either merging a PR with the `auto-cherry-pick` label or by adding the `auto-cherry-pick` label to an already closed and merged PR. +In the latter case, ensure that you first add the labels containing the target branches and then finally the `auto-cherry-pick` label. +Otherwise the automation starts without any target branches. + +=== Details + +The PRs created by this GitHub action will have their heading prefixed with `[Cherry-pick][]`. +So, for example, for `main` as the target branch and `some changes` as the original PR heading, it results in `[Cherry-pick][main] some changes` as the heading for the cherry-picked PR. +In case an assignee was set for the original PR, the cherry-picked PRs will also receive the same assignee. +You must add reviewers manually after the cherry-picked PRs have been created. + +The creation of cherry-picked PRs can take a few minutes. +If you are an assignee of the original PR, you receive an email notification once the cherry-picked PRs have been created. +The original PR is updated with a comment that contains links to the newly created cherry-picked PRs. + +In case of a merge conflict while cherry-picking to a specific release branch, the branch will be skipped. +Information on skipped branches is also included in the comment added to the original PR. +In that case you have to take care of cherry-picking manually and resolve the conflicts. +This is not going to influence the other release branches as long as they do not have conflicts. + + + diff --git a/antora.yml b/antora.yml index 23a729ae6..83cc570bd 100644 --- a/antora.yml +++ b/antora.yml @@ -1,14 +1,14 @@ name: operations-manual title: Operations Manual -version: '2025.04' +version: '2025.06' current: true start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc asciidoc: attributes: - neo4j-version: '2025.04' - neo4j-version-minor: '2025.04' - neo4j-version-exact: '2025.04.0' - neo4j-buildnumber: '2025.04' - neo4j-debian-package-version: '1:2025.04.0@' + neo4j-version: '2025.06' + neo4j-version-minor: '2025.06' + neo4j-version-exact: '2025.06.0' + neo4j-buildnumber: '2025.06' + neo4j-debian-package-version: '1:2025.06.0@' diff --git a/models/hospital/access-control-old.adoc b/models/hospital/access-control-old.adoc index 839a5c82a..948c9e06f 100644 --- a/models/hospital/access-control-old.adoc +++ b/models/hospital/access-control-old.adoc @@ -1,11 +1,11 @@ [role=enterprise-edition] [[auth-access-control]] = Fine-grained access control -:description: Describes an example that illustrates various aspects of security and fine-grained access control. +:description: Describes an example that illustrates various aspects of security and fine-grained access control. When creating a database, administrators may want to establish which users have the ability to access certain information. -As described in xref:authentication-authorization/built-in-roles/auth-built-in-roles[Built-in roles], Neo4j already offers preset roles configured to specific permissions (i.e. read, edit, or write). +As described in xref:authentication-authorization/built-in-roles.adoc[Built-in roles], Neo4j already offers preset roles configured to specific permissions (i.e. read, edit, or write). While these built-in roles cover many common daily scenarios, it is also possible to create custom roles for specific needs. This page contains an example that illustrates various aspects of security and fine-grained access control. @@ -35,7 +35,7 @@ They can be described using the properties: * `description` `(:Disease)`:: -Known illnesses mapped in a catalog found in the database. +Known illnesses mapped in a catalog found in the database. They can be described using the properties: + * `name` @@ -82,10 +82,10 @@ This same database would be used by a number of different users, each with diffe Unlike applications which often require users to be modeled within the application itself, databases provide user management resources such as roles and privileges. This allows users to be created entirely within the database security model, a strategy that allows the separation of access to the data and the data itself. -For more information, see link:/docs/cypher-manual/{neo4j-version}/access-control/[Cypher Manual -> Access control]. +For more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/[Cypher Manual -> Access control]. The following examples show two different approaches to using Neo4j security features to support the _healthcare_ database application. -The first approach uses xref:authentication-authorization/built-in-roles/auth-built-in-roles[Built-in roles], whereas the second uses more advanced resources with fine-grained privileges for <>. +The first approach uses xref:authentication-authorization/built-in-roles.adoc[Built-in roles], whereas the second uses more advanced resources with fine-grained privileges for <>. In this example, consider five users of the _healthcare_ database: @@ -128,13 +128,13 @@ Neo4j comes with built-in roles that cover a number of common needs: * `architect` - Has all the capabilities of the publisher as well as the ability to manage indexes and constraints. * `admin` - Can perform architect actions as well as manage databases, users, roles, and privileges. -Consider Charlie from the example of users. +Consider Charlie from the example of users. As a researcher, they do not need write access to the database, so they are assigned the `reader` role. -On the other hand, Alice (the doctor), Daniel (the nurse), and Bob (the receptionist) all need to update the database with new patient information, but do not need to expand the schema with new labels, relationship types, property names or indexes. +On the other hand, Alice (the doctor), Daniel (the nurse), and Bob (the receptionist) all need to update the database with new patient information, but do not need to expand the schema with new labels, relationship types, property names or indexes. For this reason, they are all assigned the `editor` role. -Tina, the IT administrator who installs and manages the database, needs to be assigned the `admin` role. +Tina, the IT administrator who installs and manages the database, needs to be assigned the `admin` role. Here is how to grant roles to the users: @@ -183,11 +183,11 @@ Has the permission to save _diagnoses_ to the database, but not expand the schem Receptionist:: Should be able to read and write all patient data, but not be able to see the symptoms, diseases, or diagnoses. Researcher:: -Should be able to perform statistical analysis of all data, except patients’ personal information, to which they should have restricted access. +Should be able to perform statistical analysis of all data, except patients’ personal information, to which they should have restricted access. To illustrate two different ways of setting up the same effective privileges, two roles are created for comparison. Nurse:: Should be able to perform all tasks that both the doctor and the receptionist can do. -Granting both roles (doctor and receptionist) to the nurse does not work as expected. +Granting both roles (doctor and receptionist) to the nurse does not work as expected. This is explained in the section dedicated to the creation of the `nurse` role. Junior nurse:: While the senior nurse is able to save diagnoses just as a doctor can, some (junior) nurses might not be allowed to do that. @@ -278,7 +278,7 @@ SHOW ROLE itadmin PRIVILEGES AS COMMANDS; [NOTE] ==== -Privileges that were granted or denied earlier can be revoked using link:/docs/cypher-manual/{neo4j-version}/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. +Privileges that were granted or denied earlier can be revoked using link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. ==== To provide the IT administrator `tina` these privileges, they must be assigned the new role `itadmin`: @@ -500,7 +500,7 @@ If the `researcherB` role is revoked to Charlie, but `researcherW` is granted, w [NOTE] ==== -Privileges that were granted or denied earlier can be revoked using link:/docs/cypher-manual/{neo4j-version}/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. +Privileges that were granted or denied earlier can be revoked using link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. ==== === Privileges of `doctor` @@ -709,7 +709,7 @@ RETURN n.name, n.ssn, n.address, n.dateOfBirth; [[detach-delete-restricted-user]] -With the `receptionist` role, Bob can delete any new patient nodes they have just created, but they are not able to delete patients that have already received diagnoses since those are connected to parts of the graph that Bob cannot see. +With the `receptionist` role, Bob can delete any new patient nodes they have just created, but they are not able to delete patients that have already received diagnoses since those are connected to parts of the graph that Bob cannot see. Here is a demonstration of both scenarios: [source, cypher] @@ -787,7 +787,7 @@ GRANT DELETE ON GRAPH healthcare RELATIONSHIPS HAS, DIAGNOSIS TO receptionist; [NOTE] ==== -Privileges that were granted or denied earlier can be revoked using link:/docs/cypher-manual/{neo4j-version}/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. +Privileges that were granted or denied earlier can be revoked using link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. ==== === Privileges of nurses @@ -838,7 +838,7 @@ SHOW USER daniel PRIVILEGES AS COMMANDS; [NOTE] ==== -Privileges that were granted or denied earlier can be revoked using link:/docs/cypher-manual/{neo4j-version}/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. +Privileges that were granted or denied earlier can be revoked using link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/manage-privileges/#access-control-revoke-privileges[the `REVOKE` command]. ==== Now the intention is that a nurse can perform the actions of a receptionist, which means they should be able to read and write the `address` field of the `Patient` nodes. @@ -1111,7 +1111,7 @@ neo4j@system> SHOW USER tina PRIVILEGES AS COMMANDS; ==== No other privilege management privileges were granted here. How much power this role should have would depend on the requirements of the system. -Refer to the section link:/docs/cypher-manual/{neo4j-version}/access-control/built-in-roles/[Cypher Manual -> The `admin` role] for a complete list of privileges to consider. +Refer to the section link:{neo4j-docs-base-uri}/cypher-manual/current/access-control/built-in-roles/[Cypher Manual -> The `admin` role] for a complete list of privileges to consider. ==== Now Tina should be able to create new users and assign them to roles: diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index fb5f6516f..08dc1518c 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -80,8 +80,11 @@ ** xref:configuration/ports.adoc[] ** xref:configuration/connectors.adoc[] ** xref:configuration/set-initial-password.adoc[] +** xref:configuration/neo4j-admin-memrec.adoc[] ** xref:configuration/plugins.adoc[Plugins] ** xref:configuration/dynamic-settings.adoc[] +** xref:configuration/migrate-configuration.adoc[] +** xref:configuration/validate-config.adoc[] ** xref:configuration/configuration-settings.adoc[] *** xref:configuration/configuration-settings.adoc#_checkpoint_settings[Checkpoint settings] *** xref:configuration/configuration-settings.adoc#_cloud_storage_integration_settings[Cloud storage integration settings] @@ -103,14 +106,20 @@ *** xref:configuration/configuration-settings.adoc#_transaction_settings[Transaction settings] *** xref:configuration/configuration-settings.adoc#_transaction_log_settings[Transaction log settings] +* xref:import.adoc[] + * xref:database-administration/index.adoc[] ** xref:database-administration/syntax.adoc[] ** Standard databases *** xref:database-administration/standard-databases/naming-databases.adoc[] *** xref:database-administration/standard-databases/create-databases.adoc[] +*** xref:database-administration/standard-databases/seed-from-uri.adoc[] *** xref:database-administration/standard-databases/listing-databases.adoc[] *** xref:database-administration/standard-databases/alter-databases.adoc[] +*** xref:database-administration/standard-databases/recreate-database.adoc[] *** xref:database-administration/standard-databases/delete-databases.adoc[] +*** xref:database-administration/standard-databases/migrate-database.adoc[] +*** xref:database-administration/standard-databases/upload-to-aura.adoc[] *** xref:database-administration/standard-databases/wait-options.adoc[] *** xref:database-administration/standard-databases/configuration-parameters.adoc[] *** xref:database-administration/standard-databases/errors.adoc[] @@ -134,6 +143,7 @@ ** xref:database-internals/transaction-logs.adoc[] ** xref:database-internals/checkpointing.adoc[] ** xref:database-internals/store-formats.adoc[] +** xref:database-internals/neo4j-admin-store-info.adoc[] * xref:clustering/index.adoc[] ** xref:clustering/introduction.adoc[] @@ -157,6 +167,7 @@ ** xref:clustering/server-syntax.adoc[] ** xref:clustering/clustering-advanced/index.adoc[] *** xref:clustering/clustering-advanced/default-database.adoc[] +*** xref:clustering/clustering-advanced/unbind.adoc[] *** xref:clustering/clustering-advanced/multi-data-center-routing.adoc[] *** xref:clustering/clustering-advanced/reconciler.adoc[] ** xref:clustering/glossary.adoc[] @@ -167,6 +178,7 @@ ** xref:backup-restore/online-backup.adoc[] ** xref:backup-restore/aggregate.adoc[] ** xref:backup-restore/inspect.adoc[] +** xref:backup-restore/consistency-checker.adoc[] ** xref:backup-restore/restore-backup.adoc[] ** xref:backup-restore/offline-backup.adoc[] ** xref:backup-restore/restore-dump.adoc[] @@ -202,6 +214,7 @@ * xref:performance/index.adoc[] ** xref:performance/memory-configuration.adoc[] +** xref:performance/vector-index-memory-configuration.adoc[] ** xref:performance/index-configuration.adoc[] ** xref:performance/gc-tuning.adoc[] ** xref:performance/bolt-thread-pool-configuration.adoc[] @@ -220,23 +233,13 @@ ** xref:monitoring/query-management.adoc[] ** xref:monitoring/connection-management.adoc[] ** xref:monitoring/background-jobs.adoc[] +** xref:monitoring/neo4j-admin-report.adoc[] // ** xref:monitoring/cluster/index.adoc[] // *** xref:monitoring/cluster/procedures.adoc[] // *** xref:monitoring/cluster/http-endpoints.adoc[] -* xref:tools/index.adoc[] -** xref:tools/neo4j-admin/index.adoc[] -*** xref:tools/neo4j-admin/consistency-checker.adoc[] -*** xref:tools/neo4j-admin/neo4j-admin-report.adoc[] -*** xref:tools/neo4j-admin/neo4j-admin-store-info.adoc[] -*** xref:tools/neo4j-admin/neo4j-admin-memrec.adoc[] -*** xref:tools/neo4j-admin/neo4j-admin-import.adoc[] -*** xref:tools/neo4j-admin/unbind.adoc[] -*** xref:tools/neo4j-admin/upload-to-aura.adoc[] -*** xref:tools/neo4j-admin/migrate-database.adoc[] -*** xref:tools/neo4j-admin/migrate-configuration.adoc[] -*** xref:tools/neo4j-admin/validate-config.adoc[] -** xref:tools/cypher-shell.adoc[] +* xref:neo4j-admin-neo4j-cli.adoc[] +* xref:cypher-shell.adoc[] * xref:procedures.adoc[] diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index 2e7968fe5..0d3b6db31 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -159,7 +159,7 @@ CREATE ROLE customAdministrator ---- GRANT ALL DBMS PRIVILEGES ON DBMS TO customAdministrator ---- -. And explicitly deny the privilege to manage databases and aliases: +. And explicitly deny the privilege to manage databases: + [source, cypher, role=noplay] ---- @@ -172,7 +172,7 @@ DENY DATABASE MANAGEMENT ON DBMS TO customAdministrator GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO customAdministrator ---- -The resulting role has privileges that include all DBMS privileges except creating, dropping, and modifying databases and aliases, as well as managing transactions. +The resulting role has privileges that include all DBMS privileges except creating, dropping, and modifying databases, as well as managing transactions. Use the following query to list all privileges for the role `customAdministrator` as commands: [source, cypher, role=noplay] @@ -864,19 +864,19 @@ For more details about the syntax descriptions, see xref:database-administration GRANT [IMMUTABLE] CREATE DATABASE ON DBMS TO role[, ...] -| Enables the specified roles to create new standard databases and aliases. +| Enables the specified roles to create new standard databases. | [source, syntax, role=noheader] GRANT [IMMUTABLE] DROP DATABASE ON DBMS TO role[, ...] -| Enables the specified roles to delete standard databases and aliases. +| Enables the specified roles to delete standard databases. | [source, syntax, role=noheader] GRANT [IMMUTABLE] ALTER DATABASE ON DBMS TO role[, ...] -| Enables the specified roles to modify standard databases and aliases. +| Enables the specified roles to modify standard databases. | [source, syntax, role=noheader] GRANT [IMMUTABLE] SET DATABASE ACCESS @@ -906,12 +906,12 @@ GRANT COMPOSITE DATABASE MANAGEMENT GRANT [IMMUTABLE] DATABASE MANAGEMENT ON DBMS TO role[, ...] -| Enables the specified roles to create, delete, and modify databases and aliases. +| Enables the specified roles to create, delete, and modify databases. |=== -The ability to create standard databases and aliases can be granted via the `CREATE DATABASE` privilege. +The ability to create standard databases can be granted via the `CREATE DATABASE` privilege. See an example: [source, cypher, role=noplay] @@ -919,7 +919,7 @@ See an example: GRANT CREATE DATABASE ON DBMS TO databaseAdder ---- -The resulting role has privileges that only allow creating standard databases and aliases. +The resulting role has privileges that only allow creating standard databases. List all privileges for the role `databaseAdder` as commands by using the following query: [source, cypher, role=noplay] @@ -959,7 +959,7 @@ SHOW ROLE compositeDatabaseAdder PRIVILEGES AS COMMANDS a|Rows: 1 |=== -The ability to delete standard databases and aliases can be granted via the `DROP DATABASE` privilege. +The ability to delete standard databases can be granted via the `DROP DATABASE` privilege. See an example: [source, cypher, role=noplay] @@ -967,7 +967,7 @@ See an example: GRANT DROP DATABASE ON DBMS TO databaseDropper ---- -The resulting role has privileges that only allow deleting standard databases and aliases. +The resulting role has privileges that only allow deleting standard databases. List all privileges for the role `databaseDropper` as commands by using the following query: [source, cypher, role=noplay] @@ -1007,7 +1007,7 @@ SHOW ROLE compositeDatabaseDropper PRIVILEGES AS COMMANDS a|Rows: 1 |=== -The ability to modify standard databases and aliases can be granted via the `ALTER DATABASE` privilege. +The ability to modify standard databases can be granted via the `ALTER DATABASE` privilege. See an example: [source, cypher, role=noplay] @@ -1015,7 +1015,7 @@ See an example: GRANT ALTER DATABASE ON DBMS TO databaseModifier ---- -The resulting role has privileges that only allow modifying standard databases and aliases. +The resulting role has privileges that only allow modifying standard databases. List all privileges for the role `databaseModifier` as commands by using the following query: [source, cypher, role=noplay] @@ -1079,7 +1079,7 @@ SHOW ROLE compositeDatabaseManager PRIVILEGES AS COMMANDS a|Rows: 1 |=== -The ability to create, delete, and modify databases and aliases can be granted via the `DATABASE MANAGEMENT` privilege. +The ability to create, delete, and modify databases can be granted via the `DATABASE MANAGEMENT` privilege. See an example: [source, cypher, role=noplay] diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 9703d9b79..6395dcf51 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -28,7 +28,7 @@ For more information, see xref:authentication-authorization/password-and-user-re When triggered, Neo4j logs an error containing a timestamp and the message `failed to log in: too many failed attempts` in the _security.log_. ==== + -For the relevant Cypher commands, see xref:authentication-authorization/manage-users.adoc#access-control-user-syntax[Manage users syntax], xref:authentication-authorization/manage-roles.adoc#access-control-role-syntax[Manage roles syntax], and xref:authentication-authorization/manage-privileges.adoc#access-control-privileges-syntax[Manage privileges syntax]. +For the relevant Cypher commands, see xref:authentication-authorization/manage-users.adoc#access-control-user-syntax[Manage users syntax], xref:authentication-authorization/manage-roles.adoc#access-control-role-syntax[Manage roles syntax], and xref:authentication-authorization/manage-privileges.adoc[Manage privileges syntax]. Various scenarios that illustrate the use of the native auth provider are available in xref:tutorial/access-control.adoc[]. *User auth providers*:: @@ -47,7 +47,7 @@ The configuration steps are described in xref:authentication-authorization/sso-i *Custom-built plugin auth providers*:: A plugin option for building custom integrations. It is recommended that this option is used as part of a custom delivery as negotiated with link:https://neo4j.com/professional-services/[Neo4j Professional Services]. -For more information, see link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/security-plugins#extending-neo4j-security-plugins[Java Reference -> Authentication and authorization plugins]. +For more information, see link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/security-plugins[Java Reference -> Authentication and authorization plugins]. *Kerberos authentication and single sign-on*:: In addition to LDAP, native, and custom providers, Neo4j supports Kerberos for authentication and single sign-on. diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 4f1b40808..4da77597f 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -65,7 +65,7 @@ this LDAP group will fail authentication, even if their credentials are correct. |=== All settings are defined at server startup time in the default configuration file _xref:configuration/neo4j-conf.adoc[neo4j.conf]_ or can be modified at -runtime using xref:procedures.adoc#procedure_dbms_setconfigvalue[`dbms.setConfigValue()`]. +runtime using xref:procedures.adoc#procedure_dbms_setConfigValue[`dbms.setConfigValue()`]. [[auth-ldap-configure-provider]] @@ -95,8 +95,9 @@ dbms.security.authorization_providers=ldap,native To assign privileges to users based on their LDAP groups, you have to map the LDAP groups to the xref:authentication-authorization/built-in-roles.adoc[Neo4j built-in] and custom-defined roles. To do that, you need to know what privileges the Neo4j roles have, and based on these privileges, to create the mapping to the groups defined in the LDAP server. -The map must be formatted as a semicolon separated list of key-value pairs, where the key is a comma-separated list of the LDAP group names and the value is a comma-separated list of the corresponding role names. -For example, `group1=role1;group2=role2;group3=role3,role4,role5;group4,group5=role6`. +The map must be formatted as a semicolon separated list of key-value pairs, where the key is a LDAP group name and the value is a comma-separated list of the corresponding role names. + +For example, `group1=role1;group2=role2;group3=role3,role4,role5;group4=role6;group5=role6`. .Example of LDAP groups to Neo4j roles mapping ==== @@ -469,7 +470,7 @@ SET AUTH 'ldap' { SET ID 'cn=alice,ou=sales,dc=example,dc=com' } You can verify that your LDAP configuration is correct, and that the LDAP server responds, by using the LDAP command-line tool `ldapsearch`. The `ldapsearch` command accepts the LDAP configuration setting values as input and verifies both the authentication (using the `simple` mechanism) and authorization of a user. -See the https://docs.ldap.com/ldap-sdk/docs/tool-usages/ldapsearch.html[ldapsearch official documentation^] for more advanced usage and how to use SASL authentication mechanisms. +See the link:https://docs.ldap.com/ldap-sdk/docs/tool-usages/ldapsearch.html[ldapsearch official documentation] for more advanced usage and how to use SASL authentication mechanisms. . Verify the authentication and authorization of a user. For example, `john`. diff --git a/modules/ROOT/pages/authentication-authorization/limitations.adoc b/modules/ROOT/pages/authentication-authorization/limitations.adoc index d7d2d2daf..9879bd63b 100644 --- a/modules/ROOT/pages/authentication-authorization/limitations.adoc +++ b/modules/ROOT/pages/authentication-authorization/limitations.adoc @@ -390,8 +390,10 @@ So due to the additional data access required by the security checks, this opera [[property-based-access-control-limitations]] === Property-based access control limitations -Extra node-level security checks are necessary when adding security rules based on property rules, and these can have a significant performance impact. -The following example shows how the database behaves when adding security rules to roles `restricted` and `unrestricted`: +Extra node or relationship-level security checks are necessary when adding security rules based on property rules, and these can have a significant performance impact. + +The following example shows how the database behaves when adding security rules for nodes to roles `restricted` and `unrestricted`. +The same limitations apply to relationships. [source, cypher] ---- diff --git a/modules/ROOT/pages/authentication-authorization/manage-execute-permissions.adoc b/modules/ROOT/pages/authentication-authorization/manage-execute-permissions.adoc index f599e93be..f21e47852 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-execute-permissions.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-execute-permissions.adoc @@ -15,7 +15,7 @@ The elevated privileges only apply within the procedure or user-defined function -- The steps below assume that the procedure or user-defined function is already developed and installed. -Please refer to link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j#extending-neo4j[Java Reference -> Extending Neo4j] for a description of creating and using user-defined procedures and functions. +Please refer to link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/[Java Reference -> Extending Neo4j] for a description of creating and using user-defined procedures and functions. -- diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index a2b104d94..2cdafb969 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -636,7 +636,7 @@ RETURN user AS adminUser [[access-control-list-user-auth-providers]] == Listing user auth providers -To inspect users' xref:authentication-authorization/auth-providers.adoc#access-control-list-user-auth-providers[auth providers], use `SHOW USERS WITH AUTH`. +To inspect available user auth providers, use `SHOW USERS WITH AUTH`. The command produces a row per user per auth provider and yields the following two columns in addition to those output by `SHOW USERS`: [options="header", width="100%", cols="1a,4,1m,^.^,^.^"] @@ -745,6 +745,8 @@ WHERE provider = 'oidc1' ====== +For more information about auth providers, see xref:authentication-authorization/auth-providers.adoc[User auth providers]. + [[access-control-create-users]] == Creating users @@ -782,7 +784,7 @@ The `'password'` can either be a string value or a string parameter with default The `PLAINTEXT` and `ENCRYPTED` keywords are optional and can be used to specify the format of the password, i.e. whether Neo4j needs to hash it or it has already been hashed. By default, all passwords are encrypted (hashed) when stored in the Neo4j `system` database. * The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. +* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/databases/databasename/tools/metadata_script.cypher_ file of a database backup. See xref:backup-restore/restore-backup#_restore_users_and_roles_metadata[Restore users and roles metadata]. + With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: ** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. @@ -850,7 +852,7 @@ SET AUTH 'native' {SET PASSWORD 'abcd1234' SET PASSWORD CHANGE REQUIRED} .Create user with an encrypted password ====== -Or you can create the user `Jake` in an active state, with an encrypted password (taken from the _data/scripts/databasename/restore_metadata.cypher_ of a database backup), and the requirement to not change the password by running: +Or you can create the user `Jake` in an active state, with an encrypted password (taken from the _data/databases/databasename/tools/metadata_script.cypher_ of a database backup), and the requirement to not change the password by running: [source,cypher,role=noplay] ---- @@ -1006,7 +1008,7 @@ The `'password'` can either be a string value or a string parameter with default The `PLAINTEXT` and `ENCRYPTED` keywords are optional and can be used to specify the format of the password, i.e. whether Neo4j needs to hash it or it has already been hashed. By default, all passwords are encrypted (hashed) when stored in the Neo4j `system` database. * The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. +* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/databases/databasename/tools/metadata_script.cypher_ file of a database backup. See xref:backup-restore/restore-backup#_restore_users_and_roles_metadata[Restore users and roles metadata]. + With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: ** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. diff --git a/modules/ROOT/pages/authentication-authorization/password-and-user-recovery.adoc b/modules/ROOT/pages/authentication-authorization/password-and-user-recovery.adoc index 16f2b7f6b..2fb46c5b5 100644 --- a/modules/ROOT/pages/authentication-authorization/password-and-user-recovery.adoc +++ b/modules/ROOT/pages/authentication-authorization/password-and-user-recovery.adoc @@ -36,7 +36,7 @@ server.default_listen_address=127.0.0.1 + [NOTE] ==== -Ensure, you have blocked all network connections for any individual services configured to listen to `listen_addresses`. +Ensure, you have blocked all network connections for any individual services configured to listen to `listen_addresses`. ==== + . Start Neo4j: @@ -86,7 +86,7 @@ bin/neo4j start [[password-recovery-for-admin]] == Recover a lost password -You can use a client such as xref:tools/cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and set a new password for the admin user. +You can use a client such as xref:cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and set a new password for the admin user. [NOTE] ==== @@ -124,7 +124,7 @@ ALTER USER neo4j SET PASSWORD 'mynewpassword' [[recover-unassigned-admin-role]] == Recover an unassigned admin role -You can use a client such as xref:tools/cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and grant the admin user role to an existing user. +You can use a client such as xref:cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and grant the admin user role to an existing user. [NOTE] ==== @@ -162,7 +162,7 @@ GRANT ROLE admin TO neo4j [[recover-admin-role]] == Recover the admin role -If you have removed the admin role from your system entirely, you can use a client such as xref:tools/cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and recreate the role with its original capabilities. +If you have removed the admin role from your system entirely, you can use a client such as xref:cypher-shell.adoc[Cypher Shell] or the Neo4j Browser to connect to the xref:database-administration/index.adoc#manage-databases-system[`system`] database and recreate the role with its original capabilities. [NOTE] ==== diff --git a/modules/ROOT/pages/authentication-authorization/privileges-writes.adoc b/modules/ROOT/pages/authentication-authorization/privileges-writes.adoc index 2fbaa0411..a23da34bf 100644 --- a/modules/ROOT/pages/authentication-authorization/privileges-writes.adoc +++ b/modules/ROOT/pages/authentication-authorization/privileges-writes.adoc @@ -135,7 +135,7 @@ DENY DELETE ON GRAPH * RELATIONSHIPS bar TO regularUsers [NOTE] ==== Users with `DELETE` privilege, but restricted `TRAVERSE` privileges, will not be able to do `DETACH DELETE` in all cases. -See href:tutorial/access-control.adoc#detach-delete-restricted-user[delete restricted user] for more info. +See xref:tutorial/access-control.adoc#detach-delete-restricted-user[delete restricted user] for more info. ==== [NOTE] diff --git a/modules/ROOT/pages/authentication-authorization/property-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/property-based-access-control.adoc index 73bc04891..eede6f21e 100644 --- a/modules/ROOT/pages/authentication-authorization/property-based-access-control.adoc +++ b/modules/ROOT/pages/authentication-authorization/property-based-access-control.adoc @@ -12,9 +12,9 @@ CREATE ROLE regularUsers; [[property-based-access-control]] = Property-based access control -Property-based access control grants permissions to users to read node properties based on property/value conditions. +Property-based access control grants or denies permission to read or traverse nodes or relationships based on property/value conditions. Each property-based privilege can only be restricted by a single property. -For information about read privileges and their syntax, see xref:authentication-authorization/privileges-reads.adoc[Read privileges]. +For information about and syntax for these privileges, see xref:authentication-authorization/privileges-reads.adoc[Read privileges]. [IMPORTANT] ==== @@ -25,28 +25,32 @@ Users who can change this property can affect the granted property-based privile == Syntax -To specify the property/value conditions of the read privilege, you can use the following syntax: +To specify the property/value conditions of the privilege, you can use the following syntax: [source, syntax, role="noheader"] ---- {GRANT | DENY | REVOKE [GRANT | DENY]} [IMMUTABLE] -{MATCH | READ | TRAVERSE} +{MATCH | READ | TRAVERSE} ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } [ ELEMENT[S] { * | label-or-rel-type[, ...] } | NODE[S] { * | label[, ...] } | RELATIONSHIP[S] { * | rel-type[, ...] } | FOR { - -([var][:label["|" ...]] "{" property: value "}") - | (var[:label["|" ...]]) - WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } - | (var[:label["|" ...]] -WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } ) -} - - {TO | FROM} role[, ...] + ([var][:label["|" ...]] "{" property: value "}") + | (var[:label["|" ...]]) + WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } + | (var[:label["|" ...]] + WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } ) + | ()[<]-"["[var][:type["|" ...]] "{" property: value "}" "]"-[>]() + | ()[<]-"["var[:type["|" ...]]"]"-[>]() + WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } + | ()[<]-"["var[:type["|" ...]] + WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } "]"-[>]() + } + ] + {TO | FROM} role[, ...] ---- @@ -57,7 +61,7 @@ See xref:authentication-authorization/limitations.adoc#property-based-access-con When having property rules, the following factors can worsen the impact on performance: -* The number of properties on the nodes concerned (more properties = greater performance impact). +* The number of properties on the nodes and relationships concerned (more properties = greater performance impact). * The number of property-based privileges (more property-based privileges = greater performance impact). * The type of the privilege: `TRAVERSE` property-based privileges have greater performance impact than `READ` property-based privileges. * The type of storage medium in operation. The impact of the property-based privileges on performance is considerably amplified by accessing disc storage. @@ -81,7 +85,7 @@ GRANT privilege-name ON GRAPH graph-name FOR pattern TO role-name The user role does not need to have `READ` privilege for the property used by the property-based privilege. ==== -=== Grant a property-based privilege on a specific property using its value +=== Grant a property-based privilege on a specific property using the value of another property The following example shows how to grant permission to `READ` the `address` property on `Email` or `Website` nodes with domain `exampledomain.com` to role `regularUsers`: @@ -97,6 +101,12 @@ Alternatively, you can use the following syntax: GRANT READ { address } ON GRAPH * FOR (:Email|Website {domain: 'exampledomain.com'}) TO regularUsers ---- +The following example shows how to grant permission to `READ` the `since` property on `OWNS` relationships having `classification` equal to `UNCLASSIFIED` to role `regularUsers`: + +[source, syntax, role="noheader"] +---- +GRANT READ { since } ON GRAPH * FOR ()-[o:OWNS]-() WHERE o.classification = 'UNCLASSIFIED' TO regularUsers +---- === Grant a property-based privilege using `NULL` @@ -109,20 +119,22 @@ GRANT TRAVERSE ON GRAPH * FOR (n:Email) WHERE n.classification IS NULL TO regula === Deny a property-based privilege using a comparison operator -The following example shows how to deny permission to `READ` and `TRAVERSE` nodes where the property `classification` is different from `UNCLASSIFIED` to role `regularUsers`: +The following example shows how to deny permission to `READ` and `TRAVERSE` nodes and relationships where the property `classification` is different from `UNCLASSIFIED` to role `regularUsers`: [source, syntax, role="noheader"] ---- DENY MATCH {*} ON GRAPH * FOR (n) WHERE n.classification <> 'UNCLASSIFIED' TO regularUsers +DENY MATCH {*} ON GRAPH * FOR ()-[r]-() WHERE r.classification <> 'UNCLASSIFIED' TO regularUsers ---- === Grant a property-based privilege on all properties using a property value -The following example shows how to grant permission to `READ` all properties on nodes where the property `securityLevel` is higher than `3` to role `regularUsers`: +The following example shows how to grant permission to `READ` all properties on nodes and relationships where the property `securityLevel` is higher than `3` to role `regularUsers`: [source, syntax, role="noheader"] ---- GRANT READ {*} ON GRAPH * FOR (n) WHERE n.securityLevel > 3 TO regularUsers +GRANT READ {*} ON GRAPH * FOR ()-[r]-() WHERE r.securityLevel > 3 TO regularUsers ---- [NOTE] @@ -132,22 +144,24 @@ The role `regularUsers` does not need to have `READ` privilege for the property === Deny a property-based privilege using a list of values -The following example shows how to deny permission to `READ` all properties on nodes where the property `classification` is not included in the list of `[UNCLASSIFIED, PUBLIC]`: +The following example shows how to deny permission to `READ` all properties on nodes and relationships where the property `classification` is not included in the list of `[UNCLASSIFIED, PUBLIC]`: [source, syntax, role="noheader"] ---- DENY READ {*} ON GRAPH * FOR (n) WHERE NOT n.classification IN ['UNCLASSIFIED', 'PUBLIC'] TO regularUsers +DENY READ {*} ON GRAPH * FOR ()-[r]-() WHERE NOT r.classification IN ['UNCLASSIFIED', 'PUBLIC'] TO regularUsers ---- // The last two examples were added in 5.26. === Grant a property-based privilege using temporal value -The following example shows how to grant permission to `READ` all properties on nodes where the property `createdAt` is later than the current date: +The following example shows how to grant permission to `READ` all properties on nodes and relationships where the property `createdAt` is later than the current date: [source, syntax, role="noheader"] ---- GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date() TO regularUsers +GRANT READ {*} ON GRAPH * FOR ()-[r]-() WHERE r.createdAt > date() TO regularUsers ---- [NOTE] @@ -159,7 +173,7 @@ This is essential when revoking property-based privileges containing evaluated f [NOTE] ==== -Not all temporal values are comparable, see link:{neo4j-docs-base-uri}/cypher-manual/current/syntax/operators/#cypher-ordering[Cypher Manual -> Syntax -> Operators -> Ordering and comparison of values]. +Not all temporal values are comparable, see link:{neo4j-docs-base-uri}/cypher-manual/current/values-and-types/ordering-equality-comparison[Cypher Manual -> Equality, ordering, and comparison of value types]. ==== You can show the privilege created by the command in the previous example as a revoke command by running: @@ -174,6 +188,7 @@ SHOW ROLE regularUsers PRIVILEGES AS REVOKE COMMANDS |=== |command |"REVOKE GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date('2024-10-25') FROM `regularUsers`" -a|Rows: 1 +|"REVOKE GRANT READ {*} ON GRAPH * FOR ()-[r]-() WHERE r.createdAt > date('2024-10-25') FROM `regularUsers`" +a|Rows: 2 |=== diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index cd48d0c5c..284565da6 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -150,7 +150,7 @@ dbms.security.authorization_providers=oidc-newsso,oidc-oldsso,native . Check connectivity. Neo4j needs to connect to the identity provider to discover settings and fetch public keys to verify tokens. Check firewall settings and security controls, and, if necessary, logs to ensure that the Neo4j server is able to connect to the identity provider using HTTPS. -If a proxy is required, this can be https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/doc-files/net-properties.html#Proxies[configured] in the Java virtual machine using the configuration setting xref:configuration/configuration-settings.adoc#config_server.jvm.additional[server.jvm.additional]. +If a proxy is required, this can be link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/doc-files/net-properties.html#Proxies[configured] in the Java virtual machine using the configuration setting xref:configuration/configuration-settings.adoc#config_server.jvm.additional[server.jvm.additional]. Proxies that require credentials are not supported. [[auth-sso-map-idp-roles]] @@ -185,6 +185,12 @@ Custom-defined roles, such as `rolename`, must be explicitly created using the ` See xref:authentication-authorization/manage-roles.adoc[Manage roles]. ==== +[NOTE] +==== +When specifying explicit group to role mapping the automatic mapping for groups and roles sharing a name is disabled. +This means that all groups and roles need to be specified to be mapped, even if they share a name. +==== + [[auth-sso-configure-provider]] == Configure Neo4j to use an OpenID Connect identity provider diff --git a/modules/ROOT/pages/backup-restore/aggregate.adoc b/modules/ROOT/pages/backup-restore/aggregate.adoc index 0aaeb0a31..39f387e62 100644 --- a/modules/ROOT/pages/backup-restore/aggregate.adoc +++ b/modules/ROOT/pages/backup-restore/aggregate.adoc @@ -67,7 +67,7 @@ Aggregates a chain of backup artifacts into a single artifact. | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc b/modules/ROOT/pages/backup-restore/consistency-checker.adoc similarity index 97% rename from modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc rename to modules/ROOT/pages/backup-restore/consistency-checker.adoc index cdce4ac05..48f511431 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc +++ b/modules/ROOT/pages/backup-restore/consistency-checker.adoc @@ -1,6 +1,6 @@ :description: Describes the Neo4j consistency checker. [[consistency-checker]] -= Consistency checker += Check database consistency You can use the `neo4j-admin database check` command to check the consistency of a database, a dump, or a backup. The `neo4j-admin` tool is located in the _/bin_ directory. @@ -68,7 +68,7 @@ The `neo4j-admin database check` command has the following options: |Allow command expansion in config value evaluation. | -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] | Configuration file with additional configuration. | @@ -107,7 +107,7 @@ Value can be plain numbers, like `10000000` or e.g. `20G` for 20 gigabytes, or e |--from-path-data= |Path to the databases directory, containing the database directory to source from. -| xref:configuration/configuration-settings.adoc#config_server.directories.data, [`server.directories.data`]/databases +| xref:configuration/configuration-settings.adoc#config_server.directories.data[`server.directories.data`]/databases |--from-path-txn= |Path to the transactions directory, containing the transaction directory for the database to source from. diff --git a/modules/ROOT/pages/backup-restore/copy-database.adoc b/modules/ROOT/pages/backup-restore/copy-database.adoc index 5f6e1a2a6..6998b5127 100644 --- a/modules/ROOT/pages/backup-restore/copy-database.adoc +++ b/modules/ROOT/pages/backup-restore/copy-database.adoc @@ -81,7 +81,7 @@ The `neo4j-admin database copy` command has the following options: | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/backup-restore/index.adoc b/modules/ROOT/pages/backup-restore/index.adoc index 9be0cbdd2..87470ae88 100644 --- a/modules/ROOT/pages/backup-restore/index.adoc +++ b/modules/ROOT/pages/backup-restore/index.adoc @@ -9,6 +9,7 @@ This chapter describes the following: * xref:backup-restore/online-backup.adoc[Back up an online database] -- How to back up an online database. * xref:backup-restore/aggregate.adoc[Aggregate a database backup chain] - How to aggregate a backup chain into a single backup. * xref:backup-restore/inspect.adoc[Inspect the metadata of a database backup file] -- How to inspect the metadata of a database backup file. +* xref:backup-restore/consistency-checker.adoc[Check database consistency] -- How to check the consistency of a database, backup, or a dump. * xref:backup-restore/restore-backup.adoc[Restore a database backup] -- How to restore a database backup in a live Neo4j deployment. * xref:backup-restore/offline-backup.adoc[Back up an offline database] -- How to back up an offline database. * xref:backup-restore/restore-dump.adoc[Restore a database dump] -- How to restore a database dump in a live Neo4j deployment. diff --git a/modules/ROOT/pages/backup-restore/inspect.adoc b/modules/ROOT/pages/backup-restore/inspect.adoc index 0d11e200c..6e2998a69 100644 --- a/modules/ROOT/pages/backup-restore/inspect.adoc +++ b/modules/ROOT/pages/backup-restore/inspect.adoc @@ -22,6 +22,7 @@ The metadata contains the following information: * *Compressed*: indicates whether the backup data inside the backup file is compressed. * *Lowest transaction ID*: when the backup is full, this value is always 1, and when it is a differential backup, the value corresponds to the first transaction ID the backup starts with. * *Highest transaction ID*: similarly, this value indicates the last transaction ID stored in the backup file. +* label:new[Introduced in 2025.06] *Recovered*: shows whether a database backup is recovered or not. [[inspect-backup-syntax]] === Syntax @@ -66,7 +67,7 @@ The `` parameter can also inspect backups stored in AWS S3 buckets, | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | @@ -149,17 +150,17 @@ Empty backups are used to record the backup history. .Example output [result] ---- -| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | -| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | -| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | -| file:///backups/malmo-2024-10-07T16-01-08.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:08 | true | true | 1 | 7 | -| file:///backups/malmo-2024-10-07T16-00-50.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:50 | false | true | 0 | 0 | -| file:///backups/malmo-2024-10-07T16-00-44.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:44 | false | true | 7 | 7 | -| file:///backups/malmo-2024-10-07T16-00-34.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:34 | false | true | 6 | 6 | -| file:///backups/malmo-2024-10-07T16-00-19.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:19 | false | true | 0 | 0 | -| file:///backups/malmo-2024-10-07T16-00-07.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:07 | true | true | 1 | 5 | -| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | -| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | +| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | RECOVERED | +| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | true | +| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | true | +| file:///backups/malmo-2024-10-07T16-01-08.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:08 | true | true | 1 | 7 | false | +| file:///backups/malmo-2024-10-07T16-00-50.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:50 | false | true | 0 | 0 | false | +| file:///backups/malmo-2024-10-07T16-00-44.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:44 | false | true | 7 | 7 | false | +| file:///backups/malmo-2024-10-07T16-00-34.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:34 | false | true | 6 | 6 | false | +| file:///backups/malmo-2024-10-07T16-00-19.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:19 | false | true | 0 | 0 | false | +| file:///backups/malmo-2024-10-07T16-00-07.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:00:07 | true | true | 1 | 5 | true | +| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | false | +| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | true | ---- === Listing the latest backups @@ -174,10 +175,10 @@ bin/neo4j-admin backup inspect /backups --show-metadata --latest-backup .Example output [result] ---- -| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | -| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | -| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | -| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | +| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | RECOVERED | +| file:///backups/neo4j-2024-10-07T16-05-37.backup | neo4j | 7dcb1d0c-4374-4476-b8ae-d3c3f124683f | 2024-10-07T16:05:37 | true | true | 1 | 3 | true | +| file:///backups/malmo-2024-10-07T16-01-24.backup | malmo | 62d1820c-3ac6-4b15-a0b3-bf7e7becc8d0 | 2024-10-07T16:01:24 | true | true | 1 | 8 | true | +| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | false | ---- === Inspecting backup chains @@ -193,9 +194,9 @@ bin/neo4j-admin backup inspect /backups --show-metadata --latest-chain --databas .Example output [result] ---- -| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | -| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | -| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | +| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | RECOVERED | +| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | true | +| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | false | ---- The result returns a chain of size two: @@ -218,9 +219,9 @@ bin/neo4j-admin backup inspect /backups/london-2024-10-07T16-04-05.backup --sho .Example output [result] ---- -| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | -| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | -| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | +| FILE | DATABASE | DATABASE ID | TIME (UTC) | FULL | COMPRESSED | LOWEST TX | HIGHEST TX | RECOVERED | +| file:///backups/london-2024-10-07T16-04-05.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:04:05 | false | true | 6 | 6 | false | +| file:///backups/london-2024-10-07T16-03-51.backup | london | d4dae73c-dfef-4d28-88cd-fe6cc88ddca1 | 2024-10-07T16:03:51 | true | true | 1 | 5 | true | ---- [NOTE] diff --git a/modules/ROOT/pages/backup-restore/offline-backup.adoc b/modules/ROOT/pages/backup-restore/offline-backup.adoc index ce8256e00..238438007 100644 --- a/modules/ROOT/pages/backup-restore/offline-backup.adoc +++ b/modules/ROOT/pages/backup-restore/offline-backup.adoc @@ -65,7 +65,7 @@ The `neo4j-admin database dump` command has the following options: | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 3aa04ca5d..4d91b53c7 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -56,7 +56,7 @@ For more information, see xref:backup-restore/online-backup.adoc#online-backup-c [NOTE] ==== -`neo4j-admin database backup` is not supported in https://neo4j.com/cloud/aura/[Neo4j Aura]. +`neo4j-admin database backup` is not supported in link:https://neo4j.com/cloud/aura/[Neo4j Aura]. ==== [[backup-command-syntax]] @@ -64,14 +64,12 @@ For more information, see xref:backup-restore/online-backup.adoc#online-backup-c [source,role=noheader] ---- -neo4j-admin database backup [-h] [--expand-commands] [--verbose] +neo4j-admin database backup [-h] [--expand-commands] [--prefer-diff-as-parent] [--verbose] [--compress[=true|false]] [--keep-failed[=true|false]] - [--parallel-recovery[=true|false]] - [--additional-config=] - [--include-metadata=none|all|users|roles] - [--inspect-path=] [--pagecache=] [--temp-path=] - [--to-path=] [--type=] [--from=[,...]]... [...] + [--parallel-recovery[=true|false]] [--additional-config=] + [--include-metadata=none|all|users|roles] [--inspect-path=] + [--pagecache=] [--temp-path=] [--to-path=] + [--type=] [--from=[,...]]... [...] ---- === Description @@ -109,7 +107,7 @@ If is "*", `neo4j-admin` will attempt to back up all databases of the | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | @@ -162,6 +160,10 @@ It is recommended to use `SHOW USERS`, `SHOW ROLES`, and `SHOW ROLE $role PRIVIL Note: this is an EXPERIMENTAL option. Consult Neo4j support before use. |false +|--prefer-diff-as-parent +|label:new[Introduced in 2025.04] When performing a differential backup, prefer the latest non-empty differential backup as the parent instead of the latest backup. +|false + |--temp-path= |Provide a path to a temporary empty directory for storing backup files until the command is completed. The files will be deleted once the command is finished. | @@ -457,3 +459,154 @@ bin/neo4j-admin database backup --to-path=azb://myStorageAccount/myContainer/myD ---- ====== ===== + + +[role=label--new-2025.04] +[[diff-backup-as-parent]] +=== Perform a differential backup using the `--prefer-diff-as-parent` option + +By default, a differential backup (`--type=DIFF`) uses the *most recent non-empty* backup -- whether full or differential -- in the directory as its parent. + +The `--prefer-diff-as-parent` option changes this behavior and forces the backup job to use the *latest differential* backup as the parent, even if a newer full backup exists. + +This approach allows you to maintain a chain of differential backups for all transactions and restore to any point in time. +Without this option, the transactions between the last full backup and a previous differential backup cannot be backed up as individual transactions. + +To use the `--prefer-diff-as-parent` option, set it to `true`. + +The following examples cover different scenarios for using the `--prefer-diff-as-parent` option. + +[.tabbed-example] +===== +[role=include-with-Chain-with-full-and-differential-backups] +====== + +Let's assume that you write 10 transactions to the `neo4j` database every hour, except from 12:30 to 13:30, when you do not write any transactions. + +There is a backup job that takes a backup every hour and a full backup every four hours. +An empty backup has no transactions, meaning that both the lower transaction ID and the upper transaction ID are zero. + +Imagine you have the following backup chain: + +[cols="h,e,m,h,h"] +|=== +|Timestamp | Backup name | Backup type | Lower Transaction ID | Upper Transaction ID + +| 10:30 +| backup1 +| FULL +| 1 +| 10 + +| 11:30 +| backup2 +| DIFF +| 11 +| 20 + +| 12:30 +| backup3 +| DIFF +| 21 +| 30 + +| 13:30 +| backup4 +| DIFF +| 0 +| 0 + +| 14:30 +| backup5 +| FULL +| 1 +| 40 + +|=== + +At 15:30, you execute the following backup command: + +[source,shell] +---- +neo4j-admin database backup --from= --to-path= --type=DIFF neo4j +---- + +The result would be: + +[cols="h,e,m,h,h"] +|=== +| 15:30 +| backup6 +| DIFF +| 41 +| 50 +|=== + +The result means you have chosen `backup5` as the parent for your differential `backup6` since the `backup5` is the *latest non-empty* backup. + +However, if you execute the following command with the `--prefer-diff-as-parent` option: + +[source,shell] +---- +neo4j-admin database backup --from= --to-path= --type=DIFF --prefer-diff-as-parent neo4j +---- + +The result would be: + +[cols="h,e,m,h,h"] +|=== +| 15:30 +| backup6 +| DIFF +| 31 +| 50 +|=== + +In this case, the `backup3` is selected as the parent since it is the *latest non-empty differential* backup. + +====== +[role=include-with-Chain-with-only-full-backups] +====== + +Let's assume that you write 10 transactions to the `neo4j` database every hour and trigger an hourly full backup. + +[cols="h,e,m,h,h"] +|=== +|Timestamp | Backup name | Backup type | Lower Transaction ID | Upper Transaction ID + +| 10:30 +| backup1 +| FULL +| 1 +| 10 + +| 11:30 +| backup2 +| FULL +| 11 +| 20 +|=== + +In this case, there is no differential backup. +Therefore, the `--prefer-diff-as-parent` option has no effect and the behaviour is the same as the default one. + +[source,shell] +---- +neo4j-admin database backup \ +--from= --to-path= \ +--type=DIFF --prefer-diff-as-parent \ +neo4j +---- + +The result would be (with or without the `--prefer-diff-as-parent` option): +[cols="h,e,m,h,h"] +|=== +| 12:30 +| backup3 +| DIFF +| 21 +| 30 +|=== + +====== +===== diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index b2e7e529f..03c03d2f6 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -51,7 +51,7 @@ This ensures that if for some reason your Neo4j DBMS crashes, you will be able t == Backup and restore options Neo4j supports backing up and restoring both online and offline databases. -It uses xref:tools/neo4j-admin/index.adoc[Neo4j Admin tool] commands, which can be run from a live, as well as from an offline Neo4j DBMS. +It uses xref:neo4j-admin-neo4j-cli.adoc[Neo4j Admin tool] commands, which can be run from a live, as well as from an offline Neo4j DBMS. All `neo4j-admin` commands must be invoked as the `neo4j` user to ensure the appropriate file permissions. * `neo4j-admin database backup/restore` (Enterprise only) -– used for performing online backup (xref:backup-restore/modes.adoc#full-backup[full] and xref:backup-restore/modes.adoc#differential-backup[differential]) and restore operations. @@ -92,7 +92,7 @@ See xref:clustering/monitoring/show-databases-monitoring.adoc#show-databases-mon However, _restoring_ a database in a cluster is different since it is not known in advance how a database is going to be allocated to the servers in a cluster. This method relies on the seed already existing on one of the servers. -The recommended way to restore a database in a cluster is to xref:clustering/databases.adoc#cluster-seed-uri[seed from URI]. +The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. [NOTE] ==== diff --git a/modules/ROOT/pages/backup-restore/restore-backup.adoc b/modules/ROOT/pages/backup-restore/restore-backup.adoc index 8606948dd..933dcfb51 100644 --- a/modules/ROOT/pages/backup-restore/restore-backup.adoc +++ b/modules/ROOT/pages/backup-restore/restore-backup.adoc @@ -8,7 +8,7 @@ A database backup artifact (full or differential) can be restored within the same or to a later Neo4j version using the `restore` command of `neo4j-admin`. -You can also load a **full** database backup artifact using the xref:backup-restore/restore-dump.adoc#restore-dump-command[`neo4j-admin database load`] command. +You can also load a **full** database backup artifact using the xref:backup-restore/restore-dump.adoc[`neo4j-admin database load`] command. This functionality is available in the Community Edition. [NOTE] @@ -22,7 +22,8 @@ For more information, see xref:database-administration/standard-databases/create [NOTE] ==== -If you are using CDC, make sure to create this new database with the same `txLogEnrichment` value and in your CDC application, handle the potential loss or corruption of CDC data, see link:{neo4j-docs-base-uri}/cdc/{page-version}/backup-restore/[Change Data Capture Manual -> Restore backups and snapshots]. +If you are using CDC, make sure you create the new database with the same `txLogEnrichment` value and handle the potential loss or corruption of CDC data in your CDC application. +For more information, see the link:https://neo4j.com/docs/cdc/current/[Change Data Capture (CDC)] documentation. ==== [NOTE] @@ -66,7 +67,7 @@ neo4j-admin database restore [-h] [--expand-commands] [--verbose] [--overwrite-d | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | @@ -100,7 +101,7 @@ The restore recovers transaction logs up to, but not including, the transaction The restore recovers transactions that were committed before the provided timestamp. | -| --source-database[=source-database-name] +| --source-database[=source-database-name] |label:new[Introduced in 2025.02] A source database name. If the `--from-path` points to a folder containing backups for multiple databases, you must specify the database name to filter the artifacts. | @@ -174,15 +175,13 @@ That means, if you restore `neo4j-2023-06-29T14-50-45.backup`, your database wil === Restore a database backup The following examples assume that you want to restore your data in a new database, called `mydatabase`. -If you want to replace an existing database, you need to stop it first, and add the option `--overwrite-destination=true` to the restore command. - -==== Restore a full backup +If you want to replace an existing database, you need to stop it first and add the option `--overwrite-destination=true` to the restore command. . Restore a database backup by running the following command: + [source, shell,role=nocopy noplay] ---- -bin/neo4j-admin database restore --from-path=/path/to/backups/neo4j-2023-05-05T11-26-38.backup mydatabase +bin/neo4j-admin database restore --from-path=/path/to/backups/neo4j-2023-06-29T14-51-33.backup mydatabase ---- + The `--from-path=` argument must contain the path to the last backup of a chain, in this case, `neo4j-2023-06-29T14-51-33.backup`. @@ -199,9 +198,11 @@ You should also skip the `CREATE DATABASE` step afterward if you are replacing a CREATE DATABASE mydatabase ---- + === Restore data up to a specific date To restore data up to a specific date, you need to pass the backup artifact that contains the data up to that date. + + This example assumes that you want to restore your data in a new database, called `mydatabase`. If you want to replace an existing database, you need to stop it first, and add the option `--overwrite-destination=true` to the restore command. @@ -299,16 +300,16 @@ For more information, see xref:clustering/databases.adoc#cluster-seed[Designated If you have backed up a database with the option `--include-metadata`, you can manually restore the users and roles metadata. -From the __ directory, you run the Cypher script _data/scripts/databasename/restore_metadata.cypher_, which the `neo4j-admin database restore` command outputs, using xref:tools/cypher-shell.adoc[Cypher Shell]: +From the __ directory, you run the Cypher script _data/databases/databasename/tools/metadata_script.cypher_, which the `neo4j-admin database restore` command outputs, using xref:cypher-shell.adoc[]: *Using `cat` (UNIX)* [source, shell, role=nocopy noplay] ---- -cat data/scripts/databasename/restore_metadata.cypher | bin/cypher-shell -u user -p password -a ip_address:port -d system --param "database => 'databasename'" +cat data/databases/databasename/tools/metadata_script.cypher | bin/cypher-shell -u user -p password -a ip_address:port -d system --param "database => 'databasename'" ---- *Using `type` (Windows)* [source, shell, role=nocopy noplay] ---- -type data\scripts\databasename\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => 'databasename'" +type data\databases\databasename\tools\metadata_script.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => 'databasename'" ---- diff --git a/modules/ROOT/pages/backup-restore/restore-dump.adoc b/modules/ROOT/pages/backup-restore/restore-dump.adoc index 974f44fb1..1677b7dcd 100644 --- a/modules/ROOT/pages/backup-restore/restore-dump.adoc +++ b/modules/ROOT/pages/backup-restore/restore-dump.adoc @@ -58,7 +58,7 @@ If `--info` is specified, then the database is not loaded, but information (i.e. | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/changes-deprecations-removals.adoc b/modules/ROOT/pages/changes-deprecations-removals.adoc index 3dabf3265..439b32b92 100644 --- a/modules/ROOT/pages/changes-deprecations-removals.adoc +++ b/modules/ROOT/pages/changes-deprecations-removals.adoc @@ -37,7 +37,7 @@ However, it is recommended to update your _neo4j.conf_ file to use the new setti | Old name | New name -|`dbms.cluster.discovery.v2.endpoints` +|`dbms.cluster.discovery.v2.endpoints` |`dbms.cluster.endpoints` |`dbms.kubernetes.discovery.v2.service_port_name` @@ -57,6 +57,7 @@ It is highly recommended to keep it enabled and not to alter it. + If you require the _debug.log_ messages in a different format, create an additional Appender since the Neo4j Support team uses the default one. For more information, see xref:monitoring/logging.adoc#_default_logging_configuration[Default logging configuration]. + === Built-in procedures .See procedures removed in Neo4j 2025.01 without replacement. @@ -68,15 +69,15 @@ For more information, see xref:monitoring/logging.adoc#_default_logging_configur | Community Edition | Enterprise Edition -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_movetonextdiscoveryversion[`dbms.cluster.moveToNextDiscoveryVersion()`] +| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_moveToNextDiscoveryVersion[`dbms.cluster.moveToNextDiscoveryVersion()`] | | {check-mark} -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_showparalleldiscoverystate[`dbms.cluster.showParallelDiscoveryState()`] +| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_showParallelDiscoveryState[`dbms.cluster.showParallelDiscoveryState()`] | | {check-mark} -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_switchdiscoveryserviceversion[`dbms.cluster.switchDiscoveryServiceVersion()`] +| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_switchDiscoveryServiceVersion[`dbms.cluster.switchDiscoveryServiceVersion()`] | | {check-mark} @@ -258,7 +259,7 @@ The `server.logs.config` and the `server.logs.user.config` are changed to depend .causal_clustering.core.replication_fail + .causal_clustering.core.replication_maybe + .causal_clustering.core.replication_success + -.causal_clustering.core.last_leader_message +.causal_clustering.core.last_leader_message |**link:{neo4j-docs-base-uri}/operations-manual/5/monitoring/metrics/reference/#read-replica-metrics[Read Replica metrics] - replaced accordingly by the link:{neo4j-docs-base-uri}/operations-manual/5/monitoring/metrics/reference/#store-copy-metrics[Store copy metrics]** @@ -279,7 +280,7 @@ The `server.logs.config` and the `server.logs.user.config` are changed to depend [role=label--enterprise] -==== Renamed metrics +==== Renamed metrics In Neo4j 2025.01, the `.store.size.total` is renamed to `.store.size.full` to be in line with the Prometheus naming requirements. @@ -372,7 +373,7 @@ For details, refer to the link:{neo4j-docs-base-uri}/java-reference/current/exte This section lists all the Neo4j Server features deprecated in the 2025 series, including replacements where applicable. -For deprecations in Cypher language, see link:https://neo4j.com/docs/cypher-manual/current/deprecations-additions-removals-compatibility/[Cypher manual -> Deprecations, additions, and compatibility]. +For deprecations in Cypher language, see link:{neo4j-docs-base-uri}/cypher-manual/current/deprecations-additions-removals-compatibility/[Cypher manual -> Deprecations, additions, and compatibility]. === Procedures @@ -386,6 +387,13 @@ For deprecations in Cypher language, see link:https://neo4j.com/docs/cypher-manu | Enterprise Edition | Comment +| xref:procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] +| +| {check-mark} +| label:deprecated[Deprecated in 2025.04] + +Replaced by xref:procedures.adoc#procedure_dbms_recreateDatabase[`dbms.recreateDatabase()`] + + | xref:procedures.adoc#procedure_dbms_quarantineDatabase[`dbms.quarantineDatabase()`] label:admin-only[] | | {check-mark} @@ -393,7 +401,7 @@ For deprecations in Cypher language, see link:https://neo4j.com/docs/cypher-manu Replaced by xref:procedures.adoc#procedure_dbms_unquarantineDatabase[`dbms.unquarantineDatabase()`] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_uncordonServer[`dbms.cluster.uncordonServer()`] +| xref:procedures.adoc#procedure_dbms_cluster_uncordonServer[`dbms.cluster.uncordonServer()`] | | {check-mark} | label:deprecated[Deprecated in 5.23]. + @@ -401,56 +409,56 @@ Before Neo4j 5.23, the procedure can be run only with an admin privilege. + Replaced by xref:clustering/server-syntax.adoc#server-management-syntax[`ENABLE SERVER`]. -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_routing_getroutingtable[`dbms.cluster.routing.getRoutingTable()`] +| xref:procedures.adoc#procedure_dbms_cluster_routing_getRoutingTable[`dbms.cluster.routing.getRoutingTable()`] | {check-mark} | {check-mark} | label:deprecated[Deprecated in 5.21]. + -Replaced by: xref:procedures.adoc#procedure_dbms_routing_getroutingtable[`dbms.routing.getRoutingTable()`]. +Replaced by: xref:procedures.adoc#procedure_dbms_routing_getRoutingTable[`dbms.routing.getRoutingTable()`]. -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_cdc_current[`cdc.current()`] label:beta[] +| xref:procedures.adoc#procedure_cdc_current[`cdc.current()`] label:beta[] | | {check-mark} | label:deprecated[Deprecated in 5.17] + Replaced by: xref:procedures.adoc#procedure_db_cdc_current[`db.cdc.current()`] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_cdc_earliest[`cdc.earliest()`] label:beta[] +| xref:procedures.adoc#procedure_cdc_earliest[`cdc.earliest()`] label:beta[] | | {check-mark} | label:deprecated[Deprecated in 5.17] + Replaced by: xref:procedures.adoc#procedure_db_cdc_earliest[`db.cdc.earliest()`] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_cdc_query[`cdc.query()`] label:beta[] label:admin-only[] +| xref:procedures.adoc#procedure_cdc_query[`cdc.query()`] label:beta[] label:admin-only[] | | {check-mark} | label:deprecated[Deprecated in 5.17] + Replaced by: xref:procedures.adoc#procedure_db_cdc_query[`db.cdc.query()`] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_db_create_setVectorProperty[`db.create.setVectorProperty()`] label:beta[] +| xref:procedures.adoc#procedure_db_create_setVectorProperty[`db.create.setVectorProperty()`] label:beta[] | {check-mark} | {check-mark} | label:deprecated[Deprecated in 5.13] + Replaced by: xref:procedures.adoc#procedure_db_create_setNodeVectorProperty[`db.create.setNodeVectorProperty()`] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_upgrade[`dbms.upgrade()`] label:admin-only[] +| xref:procedures.adoc#procedure_dbms_upgrade[`dbms.upgrade()`] label:admin-only[] | {check-mark} | {check-mark} | label:deprecated[Deprecated in 5.9] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_upgradestatus[`dbms.upgradeStatus()`] label:admin-only[] +| xref:procedures.adoc#procedure_dbms_upgradeStatus[`dbms.upgradeStatus()`] label:admin-only[] | {check-mark} | {check-mark} | label:deprecated[Deprecated in 5.9] -| link:{neo4j-docs-base-uri}/operations-manual/5/procedures/#procedure_dbms_cluster_readreplicatoggle[`dbms.cluster.readReplicaToggle()`] label:admin-only[] +| xref:procedures.adoc#procedure_dbms_cluster_readReplicaToggle[`dbms.cluster.readReplicaToggle()`] label:admin-only[] | | {check-mark} | label:deprecated[Deprecated in 5.6] + -Replaced by: xref:procedures.adoc#procedure_dbms_cluster_secondaryreplicationdisable[`dbms.cluster.secondaryReplicationDisable()`]. +Replaced by: xref:procedures.adoc#procedure_dbms_cluster_secondaryReplicationDisable[`dbms.cluster.secondaryReplicationDisable()`]. |=== ==== @@ -466,6 +474,11 @@ Replaced by: xref:procedures.adoc#procedure_dbms_cluster_secondaryreplicationdis | Enterprise Edition | Comment +| xref:configuration/configuration-settings.adoc#config_dbms.routing.load_balancing.plugin[`dbms.routing.load_balancing.plugin`] +| +| {check-mark} +| label:deprecated[Deprecated in 2025.05] + | xref:configuration/configuration-settings.adoc#config_server.db.query_cache_size[`server.db.query_cache_size`] | {check-mark} | {check-mark} @@ -505,6 +518,12 @@ Replaced by: xref:procedures.adoc#procedure_dbms_cluster_secondaryreplicationdis |=== ==== +=== Logging + +Starting from 2025.05, the `failureReason` column of the JSON format query log is deprecated. +Instead, use the `errorInfo` column. +For details, refer to xref:monitoring/logging.adoc#_json_format_log_entries[Logging -> JSON format log entries for log type query]. + === Neo4j-admin tool .See all deprecated commands @@ -525,17 +544,38 @@ Replaced by xref:backup-restore/aggregate.adoc[`neo4j-admin backup aggregate`] |=== ==== +.See all deprecated command options +[%collapsible] +==== +[options=header, cols="3m,2,3"] +|=== +| Command +| Option +| Comment + +| link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/standard-databases/migrate-database[`neo4-admin database migrate`] +| `--page-cache` label:deprecated[Deprecated in 2025.04] +| The option is deprecated and replaced by the `--max-off-heap-memory` option. +|=== +==== + === Seed providers `S3SeedProvider` is deprecated since Neo4j 5.26 and replaced by the `CloudSeedProvider`. -For more information, see xref:clustering/databases.adoc#s3-seed-provider[Seed from URI]. +For more information, see xref:database-administration/standard-databases/seed-from-uri.adoc#s3-seed-provider[Seed from URI]. === Java API Since Neo4j 5.26, the server-side Notification API and the `getNotifications()` method of the Result Core API are deprecated. +=== Neo4j error codes messages + +Starting from 2025.04, using the error messages programmatically is deprecated. +Because error messages might change in a future release, please parse or use GQLSTATUS error codes in your application code. +For details, see link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/[Status Codes for Errors & Notifications -> List of GQLSTATUS error codes]. + == Changes in Neo4j 2025.x The section covers changes to Neo4j server functionality across different areas. diff --git a/modules/ROOT/pages/cloud-deployments/index.adoc b/modules/ROOT/pages/cloud-deployments/index.adoc index 2d97b9fb0..5ef0533f5 100644 --- a/modules/ROOT/pages/cloud-deployments/index.adoc +++ b/modules/ROOT/pages/cloud-deployments/index.adoc @@ -12,15 +12,15 @@ Neo4j's cloud marketplace listings represent a quick and easy way of getting sta | Amazon Web Services | xref:cloud-deployments/neo4j-aws.adoc[Neo4j on AWS] -| https://neo4j.com/partners/amazon/[Neo4j in the AWS Marketplace^] +| link:https://neo4j.com/partners/amazon/[Neo4j in the AWS Marketplace] -| Google Cloud +| Google Cloud | xref:cloud-deployments/neo4j-gcp.adoc[Neo4j on Google Cloud Platform] -| https://neo4j.com/partners/google/[Neo4j in the GCP Marketplace^] +| link:https://neo4j.com/partners/google/[Neo4j in the GCP Marketplace] | Microsoft Azure | xref:cloud-deployments/neo4j-azure.adoc[Neo4j on Microsoft Azure] -| https://neo4j.com/partners/microsoft/[Neo4j in the Azure Marketplace^] +| link:https://neo4j.com/partners/microsoft/[Neo4j in the Azure Marketplace] |=== @@ -28,7 +28,7 @@ Neo4j's cloud marketplace listings represent a quick and easy way of getting sta [TIP] ==== *Neo4j Aura* is a fully managed Neo4j database, hosted in the cloud and requires no installation. -For more information, see https://neo4j.com/aura/[the Aura product^], https://aura.support.neo4j.com/[support pages^], and the https://www.neo4j.com/docs/aura[Aura documentationˆ]. +For more information, see link:https://neo4j.com/aura/[the Aura product], link:https://aura.support.neo4j.com/[support pages], and the link:https://www.neo4j.com/docs/aura[Aura documentation]. //Neo4j can be run in a *Docker* container. //For information on running Neo4j on Docker, see xref:docker/index.adoc[Docker]. diff --git a/modules/ROOT/pages/cloud-deployments/neo4j-aws.adoc b/modules/ROOT/pages/cloud-deployments/neo4j-aws.adoc index e2eaf7148..bf9f26652 100644 --- a/modules/ROOT/pages/cloud-deployments/neo4j-aws.adoc +++ b/modules/ROOT/pages/cloud-deployments/neo4j-aws.adoc @@ -5,7 +5,7 @@ Neo4j can be easily deployed on EC2 instances in Amazon Web Services (AWS) by using the link:https://aws.amazon.com/marketplace/seller-profile?id=23ec694a-d2af-4641-b4d3-b7201ab2f5f9[official listings for Neo4j] on the AWS Marketplace. The AWS Marketplace listing uses a CloudFormation template maintained by Neo4j. -The template's code is available on link:https://github.com/neo4j-partners/amazon-cloud-formation-neo4j/tree/main/marketplace[GitHub^] and can be customized to meet more complex or bespoke use cases. +The template's code is available on link:https://github.com/neo4j-partners/amazon-cloud-formation-neo4j/tree/main/marketplace[GitHub] and can be customized to meet more complex or bespoke use cases. [NOTE] @@ -16,7 +16,7 @@ The Neo4j AWS Marketplace listings (and listings on GitHub) use CloudFormation t == Supported Neo4j versions -The Neo4j link:https://aws.amazon.com/marketplace/seller-profile?id=23ec694a-d2af-4641-b4d3-b7201ab2f5f9[AWS marketplace listing^] can be configured to deploy either Neo4j Enterprise Edition 5 or 4.4. +The Neo4j link:https://aws.amazon.com/marketplace/seller-profile?id=23ec694a-d2af-4641-b4d3-b7201ab2f5f9[AWS marketplace listing] can be configured to deploy either Neo4j Enterprise Edition 5 or 4.4. The CloudFormation template always installs the latest available version. == Neo4j CloudFormation template @@ -32,7 +32,7 @@ The Neo4j CloudFormation template takes several parameters as inputs, deploys a === Important considerations * The deployment of cloud resources will incur costs. -** Refer to the link:https://calculator.aws/#[AWS pricing calculator^]for more information. +** Refer to the link:https://calculator.aws[AWS pricing calculator]for more information. * The Neo4j CloudFormation template deploys a new VPC. ** AWS accounts are limited to an initial quota of 5 VPCs (you can view your current quota by viewing the *Limits* page of the Amazon EC2 console). @@ -126,12 +126,128 @@ After the installation finishes successfully, the CloudFormation template provid |=== -== Cluster version consistency +[role=label--enterprise-edition] +== Neo4j cluster on AWS + +=== Cluster version consistency When the CloudFormation template creates a new Neo4j cluster, an Auto Scaling group (ASG) is created and tagged with the monthly version of the installed Neo4j database. If you add more EC2 instances to your ASG, they will be installed with the same monthly version, ensuring that all Neo4j cluster servers are installed with the same version, regardless of when the EC2 instances were created. +=== Neo4j cluster and Auto Scaling Group + +The Neo4j AWS CloudFormation template deploys a cluster into an ASG. +However, managing a Neo4j cluster with ASG requires careful planning. +Starting from the 5.x series, Neo4j’s clustering relies on stable servers identities. +In contrast, ASGs are primarily designed for stateless, interchangeable workloads, which means they can terminate and recreate servers at any time, breaking their identity. + +To provide stable servers identities, it is recommended to use a persistent disk, e.g., Amazon Elastic Block Store (EBS). +For more information about EBS volumes, see link:https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volumes.html[Amazon EBS volumes]. +Amazon EBS provides block storage resources that can be used with Amazon EC2 instances. + +If a server in Neo4j cluster does not remount its original EBS volume, it will either: + +* Start with no data (store copy issue). +* Fail to rejoin the cluster correctly. + +How to run Neo4j cluster in EC2 instances with ASGs:: ++ +. Create an EBS volume and tag it. +You can follow the steps outlined in the guide link:https://docs.aws.amazon.com/ebs/latest/userguide/ebs-creating-volume.html[Create an Amazon EBS volume]. ++ +. Attach the EBS volume to an Amazon EC2 instance in the same Availability Zone. +For more information, see link:https://docs.aws.amazon.com/ebs/latest/userguide/ebs-attaching-volume.html[Attach an Amazon EBS volume to an Amazon EC2 instance]. ++ +. Ensure stable volume re-attachment. +Use an instance startup script (via EC2 User data or `systemd` service) to: +.. Identify its own logical identity (e.g., via private IP or hostname). +.. Locate the correct EBS volume by tag. +.. Attach the volume to the instance. +.. Mount the volume to `/var/lib/neo4j` or appropriate data directory. ++ +. Use rolling updates only. +Set `maxSurge = 0` and `maxUnavailable = 1` in any update mechanism to avoid multiple restarts that could destabilize the cluster. ++ +. Avoid auto-healing on cluster members. +ASG health checks should not terminate cluster members automatically. +Use external monitoring (e.g., Prometheus, Neo4j’s health checks) and manual intervention for cluster members. + + + +=== Remove a server from the Neo4j cluster + +Rolling updates on Amazon Machine Images (AMIs) often involve rotating the images. +However, simply removing Neo4j servers from the target Network Load Balancer (NLB) one by one does not prevent requests from being routed to them. +This occurs because the NLB and Neo4j server-side routing operate independently and do not share awareness of a server availability. + +To correctly remove a server from the cluster and reintroduce it after the update, follow the steps outlined below: + +. Remove the server from the AWS NLB. + This prevents external clients from sending requests to the server. + +. Since Neo4j's cluster routing (server-side routing) does not use the NLB, you need to ensure that queries are not routed to the server. +To do this, you have to cleanly shut down the server. + +.. Run the following query to check servers are hosting all their assigned databases. +The query should return no results: ++ +[source, cypher, role=noplay] +---- +SHOW SERVERS YIELD name, hosting, requestedHosting, serverId WHERE requestedHosting <> hosting +---- + +.. Use the following query to check all databases are in their expected state. +The query should return no results: ++ +[source, cypher, role=noplay] +---- +SHOW DATABASES YIELD name, address, currentStatus, requestedStatus, statusMessage WHERE currentStatus <> requestedStatus RETURN name, address, currentStatus, requestedStatus, statusMessage +---- + +.. To stop the Neo4j service, run the following command: ++ +[source, shell, role=copy] +---- +sudo systemctl stop neo4j +---- ++ +To configure the timeout period for waiting on active transactions to either complete or be terminated before the shutdown, modify the setting xref::configuration/configuration-settings.adoc#config_db.shutdown_transaction_end_timeout[`db.shutdown_transaction_end_timeout`] in the _neo4j.conf_ file. +`db.shutdown_transaction_end_timeout` defaults to 10 seconds. ++ +The environment variable `NEO4J_SHUTDOWN_TIMEOUT` determines how long the system will wait for Neo4j to stop before forcefully terminating the process. +You can change this using `systemctl edit neo4j.service`. +By default, `NEO4J_SHUTDOWN_TIMEOUT` is set to 120 seconds. +If the shutdown process exceeds this limit, it is considered failed. +You may need to increase the value if the system serves long-running transactions. + +.. Verify that the shutdown process has finished successfully by checking the _neo4j.log_ for relevant log messages confirming the shutdown. + + +. When everything is updated or fixed, start the servers one by one again. +.. Run `systemctl start neo4j`. +.. Once the server has been restarted, confirm it is running successfully. ++ +Run the following command and check the server has state `Enabled` and health `Available`. ++ +[source, cypher, role=noplay] +---- +SHOW SERVERS WHERE name = [server-id]; +---- + +.. Confirm that the server has started all the databases that it should. ++ +This command shows any databases that are not in their expected state: ++ +[source, cypher, role=noplay] +---- +SHOW DATABASES YIELD name, address, currentStatus, requestedStatus, serverID WHERE currentStatus <> requestedStatus AND serverID = [server-id] RETURN name, address, currentStatus, requestedStatus +---- + +. Reattach the server to the NLB. +Once the server is stable and caught up, add it back to the AWS NLB target group. + + [role=label--enterprise-edition] == Licensing @@ -142,7 +258,7 @@ When deploying Neo4j, users are required to confirm that they either have an ent If you require the Enterprise version of either Graph Data Science or Bloom, you need to provide a key issued by Neo4j as this will be required during the installation. -To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form^]. +To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form]. == Delete CloudFormation Stack and destroy resources diff --git a/modules/ROOT/pages/cloud-deployments/neo4j-azure.adoc b/modules/ROOT/pages/cloud-deployments/neo4j-azure.adoc index 9acef4277..bb080163a 100644 --- a/modules/ROOT/pages/cloud-deployments/neo4j-azure.adoc +++ b/modules/ROOT/pages/cloud-deployments/neo4j-azure.adoc @@ -5,7 +5,7 @@ Neo4j can be easily deployed on Virtual Machine instances in Microsoft Azure by using the link:https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neo4j.neo4j-ee?tab=Overview[official listing for Neo4j Enterprise] on the Azure Marketplace. The Azure Marketplace listing uses an Azure Resource Manager (ARM) template maintained by Neo4j. -The template's code is available on link:https://github.com/neo4j-partners/azure-resource-manager-neo4j/tree/main/marketplace[GitHub^] and can be customized to meet more complex or bespoke use cases. +The template's code is available on link:https://github.com/neo4j-partners/azure-resource-manager-neo4j/tree/main/marketplace[GitHub] and can be customized to meet more complex or bespoke use cases. [NOTE] @@ -16,7 +16,7 @@ The Neo4j Azure Marketplace listings (and listings on GitHub) use Azure Resource == Supported Neo4j versions -The Neo4j link:https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neo4j.neo4j-ee?tab=Overview[Azure marketplace listing^] can be configured to deploy either Neo4j Enterprise Edition 5 or 4.4. +The Neo4j link:https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neo4j.neo4j-ee?tab=Overview[Azure marketplace listing] can be configured to deploy either Neo4j Enterprise Edition 5 or 4.4. The ARM template always installs the latest available version. == Neo4j ARM template @@ -28,7 +28,7 @@ The Neo4j ARM template takes several parameters as inputs, deploys a set of clou === Important considerations * The deployment of cloud resources incurs costs. -** Refer to the link:https://azure.microsoft.com/en-gb/pricing/calculator/[Azure pricing calculator^]for more information. +** Refer to the link:https://azure.microsoft.com/en-gb/pricing/calculator/[Azure pricing calculator]for more information. * You need to create a resource group. ** You need to choose an empty resource group or create a new one. @@ -135,7 +135,7 @@ When deploying Neo4j, users are required to confirm that they either have an ent If you require the Enterprise version of either Graph Data Science or Bloom, you need to provide a key issued by Neo4j as this will be required during the installation. -To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form^]. +To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form]. == Delete Azure deployment Stack and destroy resources diff --git a/modules/ROOT/pages/cloud-deployments/neo4j-gcp.adoc b/modules/ROOT/pages/cloud-deployments/neo4j-gcp.adoc index 059597e99..995e51b3b 100644 --- a/modules/ROOT/pages/cloud-deployments/neo4j-gcp.adoc +++ b/modules/ROOT/pages/cloud-deployments/neo4j-gcp.adoc @@ -2,10 +2,10 @@ [[gcp]] = Neo4j on GCP -Neo4j Edition can be easily deployed on Virtual Machines in Google Cloud Platform (GCP) by using the link:https://console.cloud.google.com/marketplace/product/neo4j/neo4j-enterprise-edition[official listing for Neo4j Enterprise Edition] or https://console.cloud.google.com/marketplace/product/neo4j/neo4j-community-edition?project=cohesive-point-368015[Neo4j Community Edition] on the GCP Marketplace]. +Neo4j Edition can be easily deployed on Virtual Machines in Google Cloud Platform (GCP) by using the link:https://console.cloud.google.com/marketplace/product/neo4j/neo4j-enterprise-edition[official listing for Neo4j Enterprise Edition] or link:https://console.cloud.google.com/marketplace/product/neo4j/neo4j-community-edition?project=cohesive-point-368015[Neo4j Community Edition] on the GCP Marketplace]. The GCP Marketplace listing uses a Deployment Manager template maintained by Neo4j. -The template's code is available on link:https://github.com/neo4j-partners/google-deployment-manager-neo4j[GitHub^] and can be customized to meet more complex or bespoke use cases. +The template's code is available on link:https://github.com/neo4j-partners/google-deployment-manager-neo4j[GitHub] and can be customized to meet more complex or bespoke use cases. [NOTE] @@ -16,7 +16,7 @@ The Neo4j GCP Marketplace listings (and listings on GitHub) use Deployment Manag == Supported Neo4j versions -The Neo4j link:https://console.cloud.google.com/marketplace/product/neo4j/neo4j-enterprise-edition[GCP marketplace listing^] can be configured to deploy either Neo4j Enterprise Edition 5, or 4.4, or Neo4j Community Edition 5. +The Neo4j link:https://console.cloud.google.com/marketplace/product/neo4j/neo4j-enterprise-edition[GCP marketplace listing] can be configured to deploy either Neo4j Enterprise Edition 5, or 4.4, or Neo4j Community Edition 5. The Deployment Manager template always installs the latest available version. == Neo4j Deployment Manager template @@ -27,7 +27,7 @@ The Neo4j Deployment Manager template takes several parameters as inputs, deploy === Important considerations * The deployment of cloud resources incurs costs. -** Refer to the link:https://cloud.google.com/products/calculator/[GCP pricing calculator^]for more information. +** Refer to the link:https://cloud.google.com/products/calculator/[GCP pricing calculator]for more information. * The Neo4j Deployment Manager template deploys a new VPC, containing a single subnet based in the requested region. ** Unlike Azure and AWS where subnets are aligned to specific zones, GCP subnets are regional (and VPCs are global). @@ -128,7 +128,7 @@ When deploying Neo4j, you are required to confirm that you either have an Enterp If you require the Enterprise version of either Graph Data Science or Bloom, you need to provide a key issued by Neo4j as this is required during the installation. -To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form^]. +To obtain a valid license for either Neo4j, Bloom, or GDS, reach out to your Neo4j account representative or get in touch using the link:https://neo4j.com/contact-us/[contact form]. == Delete deployment and destroy resources diff --git a/modules/ROOT/pages/clustering/clustering-advanced/index.adoc b/modules/ROOT/pages/clustering/clustering-advanced/index.adoc index 3f71529cf..16d2f8358 100644 --- a/modules/ROOT/pages/clustering/clustering-advanced/index.adoc +++ b/modules/ROOT/pages/clustering/clustering-advanced/index.adoc @@ -7,6 +7,7 @@ This section includes information about advanced deployments of a Neo4j Cluster. * xref:clustering/clustering-advanced/default-database.adoc[Default database in a cluster] -- Details of the creation of the default database in a cluster. +* xref:clustering/clustering-advanced/unbind.adoc[Unbind a server] -- How to remove and archive the cluster state of a cluster server so that it can rebind to a cluster. * xref:clustering/clustering-advanced/multi-data-center-routing.adoc[Multi-data center routing] -- Information about routing in multi-data center deployments. * xref:clustering/clustering-advanced/reconciler.adoc[Reconciler] -- Details about the way database management operations are processed. diff --git a/modules/ROOT/pages/clustering/clustering-advanced/reconciler.adoc b/modules/ROOT/pages/clustering/clustering-advanced/reconciler.adoc index e8fdb1723..050652435 100644 --- a/modules/ROOT/pages/clustering/clustering-advanced/reconciler.adoc +++ b/modules/ROOT/pages/clustering/clustering-advanced/reconciler.adoc @@ -17,7 +17,7 @@ Executing an operation and getting back a successful response means that the req Servers can become aware the same operation at different times, since the `system` database is just another Raft group, where followers and replicas can lag behind the leader in some situations. Eventually, the new state gets propagated to all healthy servers, and they take action on it. -If you want to be sure that each server has processed an administrative operation before running the next action, you can use the link:{neo4j-docs-base-uri}/cypher-manual/current/administration/databases/#administration-wait-nowait[`WAIT`] keyword. +If you want to be sure that each server has processed an administrative operation before running the next action, you can use the xref:database-administration/standard-databases/wait-options.adoc[`WAIT`] keyword. `WAIT` makes the statement not return until all servers have seen the transaction, and their reconciler has finished processing it. .Example of database creation with `WAIT` @@ -40,6 +40,6 @@ For instance, some servers might be offline when a database is created, or a dis In this situation, the operation has not _failed_ as a whole, since the database may even be running (although with less fault tolerance than you intended). Some failed operations can just be re-tried: for example, `START DATABASE` can be re-run if not all members started successfully, and you think the cause of that has been resolved. -Other failures only require the underlying problem to be resolved. +Other failures only require the underlying problem to be resolved. When the issue is fixed, the reconciler will make the intended change, because it is still trying to achieve the requested state. For example, if a new server fails during a `DEALLOCATE DATABASES FROM SERVER` (meaning a database cannot be safely moved), fixing the new server should be enough to resolve the problem, as the new server will start its copy of the database as soon as the target is ready, allowing the deallocating server to shut down its copy. diff --git a/modules/ROOT/pages/tools/neo4j-admin/unbind.adoc b/modules/ROOT/pages/clustering/clustering-advanced/unbind.adoc similarity index 95% rename from modules/ROOT/pages/tools/neo4j-admin/unbind.adoc rename to modules/ROOT/pages/clustering/clustering-advanced/unbind.adoc index bab7929f4..4319e5690 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/unbind.adoc +++ b/modules/ROOT/pages/clustering/clustering-advanced/unbind.adoc @@ -1,7 +1,7 @@ :description: How to remove cluster state data from a Neo4j server using `neo4j-admin server unbind`. [role=enterprise-edition] [[neo4j-admin-unbind]] -= Unbind a Neo4j cluster server += Unbind a server You can use the `neo4j-admin server unbind` command to remove and archive the cluster state of a cluster server so that it can rebind to a cluster. @@ -39,7 +39,7 @@ The `neo4j-admin server unbind` command has the following options: | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index 5408ae738..f4f9143d3 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -4,8 +4,9 @@ [[database-management]] = Managing databases in a cluster -The number of both primary and secondary servers to host a database can be set when the database is created and altered after creation. -The command `CREATE DATABASE` can be used to specify the initial topology and `ALTER DATABASE` can be used to change the topology once the database is created. +When creating a database or altering it after creation, you can set the number of both primary and secondary servers to host your database. +To specify the initial topology, use the command `CREATE DATABASE`. +To change the topology once the database is created, run the `ALTER DATABASE` command. If a database is no longer needed, the command `DROP DATABASE` deletes the database from the cluster. [[create-database]] @@ -13,12 +14,13 @@ If a database is no longer needed, the command `DROP DATABASE` deletes the datab The command to create a database in a cluster is not significantly different from the command to create a database in a non-clustered environment (see xref:database-administration/standard-databases/create-databases.adoc[Create, start, and stop databases] for more information on database management on single servers). The difference in a clustered environment is that the topology can be specified, i.e. how many primaries and secondaries are desired for the database. -To create a database `foo` with 3 servers hosting the database in primary mode and 2 servers in secondary mode, the command looks like this: +To create a database `foo` with 3 servers hosting the database in primary mode and 2 servers in secondary mode, run the following command: [source, cypher] ---- CREATE DATABASE foo TOPOLOGY 3 PRIMARIES 2 SECONDARIES ---- + Alternatively, you can use link:{neo4j-docs-base-uri}/cypher-manual/current/syntax/parameters[parameters] to provide the number of primaries and secondaries: .Parameters @@ -44,11 +46,13 @@ For example, if the cluster's servers are set up with mode constraints to contai [NOTE] ==== If `TOPOLOGY` is not specified, the database is created according to `initial.dbms.default_primaries_count` and `initial.dbms.default_secondaries_count` specified in _neo4j.conf_. -After cluster startup, these values can be overwritten using the `dbms.setDefaultAllocationNumbers` procedure. +After cluster startup, you can overwrite these values using the `dbms.setDefaultAllocationNumbers` procedure. ==== + [NOTE] ==== A `CREATE DATABASE` command allocates the database, therefore there is no requirement to execute `REALLOCATE DATABASES` (described in xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers]). + However, over time, or after several `CREATE DATABASE` commands have been issued, the distribution of databases can become unbalanced. At this point you can run `REALLOCATE DATABASES` to make the cluster re-balance databases across all servers that are part of the cluster. ==== @@ -61,7 +65,7 @@ To alter the topology of or read/write access to a database after it has been cr [[alter-topology]] === Alter database topology -To change the topology of the database `foo` from the previous example, the command can look like this: +To change the topology of the database `foo` from the previous example, run the following command: [source, cypher] ---- @@ -95,21 +99,21 @@ Note, like `CREATE DATABASE`, the `ALTER DATABASE` command allocates the databas This normally happens when the cluster is configured with more servers than the sum of the number of primaries and secondaries for any one database. -It is not possible to automatically transition to a topology with a single primary host. Attempting to do so results in an error. +It is not possible to automatically transition to a topology with a single primary host. +Attempting to do so results in an error. -However, it is possible to _manually_ do this transition. -The first step is to back up the database, see xref:backup-restore/index.adoc[Backup and restore] for more information. -Once the database is backed up, the next step is to drop the database, see xref:database-administration/standard-databases/delete-databases.adoc[Delete databases] for more information. -The last step is to either seed a cluster from the backup with the new topology, or to restore the backup on a single server. +However, it is possible to _manually_ do this transition: + +. The first step is to back up the database, see xref:backup-restore/index.adoc[Backup and restore] for more information. +. Once the database is backed up, the next step is to drop the database. +See xref:database-administration/standard-databases/delete-databases.adoc[Delete databases] for more details. +. The last step is to either seed a cluster from the backup with the new topology, or to restore the backup on a single server. See xref:clustering/databases.adoc#cluster-seed[Seed a cluster] further on for information on seeding. Also, it is possible to automatically transition _from_ a topology with a single primary host to multiple primary hosts. -Keep in mind that during such a transition, the database will be unavailable for a short period of time. - -`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. +Keep in mind that during such a transition, the database is unavailable for a short period of time. -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. +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] @@ -246,134 +250,16 @@ neo4j@neo4j> DRYRUN REALLOCATE DATABASES; ---- -[[recreate-databases]] -== Recreate a database - -The xref:procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] procedure allows you to: - -* Change the database store to a specified backup, while keeping all the associated privileges for the database. - -* Make your database write-available again after it has been lost (for example, due to a disaster). -See xref:clustering/disaster-recovery.adoc[Disaster recovery] for more information. - -[CAUTION] -==== -The recreate procedure works only for real user databases and not for composite databases, or the `system` database. - -Remember that the recreate procedure results in downtime while the stores get updated. -The time is unbounded and may depend on different factors -- for example, the size of the store, network speed, etc. -==== - -The database in question can be in an `online` or `offline` state when it is recreated, but a successful operation starts the database regardless of its previous state. - -If your database has Change Data Capture (CDC) enabled, the CDC chain will stop when the database is recreated, even though CDC remains enabled in the recreated database. -To restore CDC functionality, follow the guide on how link:https://neo4j.com/docs/cdc/current/existing-databases/[to initialize CDC applications from an existing database]. - -Before recreating a database, any eventual quarantined states need to be addressed. -For more information, see xref:database-administration/standard-databases/errors.adoc#quarantine[Standard databases -> Error handling]. - -You need xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[the `CREATE DATABASE` and `DROP DATABASE` privileges] to run the recreate procedure. - -To check if the recreation is successful, use the `SHOW DATABASES` command and verify that all allocations have been started. - -Additionally, you have the option to modify <> during the recreation process. -However, note that the store format, access, and enrichment cannot be altered during recreation. - -[[recreate-seeding-options]] -=== Seeding options - -The store to be used during the recreation of a database can be defined in different ways. -One method uses a backup, while others use available allocations in the cluster. - -You can use either <> or <> to specify the source from which the database should be recreated. - -* If you define neither, an error is thrown. - -* If you define both of them, then `seedingServers` must be an empty list. -See <> for more details. - -* If `seedingServers` is not empty and `seedURI` is also defined, an error will occur. - -[[uri-seed]] -==== Use backup as a seed - -If you provide a URI to a backup or a dump, the stores on all allocations will be replaced by the backup or the dump at the given URI. -The new allocations can be put on any `ENABLED` server in the cluster. -See <> for more details. - - -[source, shell] ----- -CALL dbms.cluster.recreateDatabase("neo4j", {seedURI: "s3://myBucket/myBackup.backup"}); ----- - -[[seed-servers]] -==== Use available servers as a seed - -After the recreation is complete, the database will have the latest data store from the seeding servers. - -[CAUTION] -==== -Recreation is based on remaining stores or a store defined by the user. -This means that stores which were lost or not defined are not used for the recreation. -If not used stores were more up to date than the used ones, this results in data loss. -==== - -[[specified-servers]] -Specified servers:: - -You can specify a set of available servers. -The stores on all allocations will be synchronized to the most up-to-date store from the defined servers. -The number of defined servers cannot exceed the number of total allocations in the desired topology. -+ -[source, shell] ----- -CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: ["serverId1", "serverId2", "serverId3"]}); ----- - -[[undefined-servers]] -Undefined servers:: - -If you provide an empty list of seeding servers and do not specify a `seedURI`, Neo4j automatically selects all available allocations of the database as seeders. -The store will be replaced by the most up-to-date seeder available in the cluster. -+ -[source, shell] ----- -CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: []}); ----- - -[[undefined-servers-backup]] -Undefined servers with fallback backup:: - -If both an empty list of seeding servers and a `seedURI` are provided, Neo4j finds all available allocations of the database and use those as seeders. -However, if no available servers can be found, the database is recreated based on the backup or the dump defined by the URI. -This means the store is replaced by the most up-to-date seeder if available; otherwise, the backup is used. -+ -[source, shell] ----- -CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: [], seedURI: "s3://myBucket/myBackup.backup"}); ----- - -[[alter-topology-recreate]] -=== Change the topology - -There is an option to define a new topology when recreating a database. -This can be beneficial during a disaster, if enough servers are not available to recreate the database with the original topology. -When altering the total number of allocations down during a recreation, it is important to remember that the number of seeding servers cannot exceed the number of total allocations of the database. -This also holds true when using recreate with an empty list of seeders. -If there are more available servers in the cluster hosting the database than the number of new allocations, the recreation will fail. - -[source, shell] ----- -CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: [], primaries: 3, secondaries: 0}); ----- [[cluster-seed]] == Seed a cluster -There are two different ways to seed a cluster with data. -The first option is to use a _designated seeder_, where a designated server is used to create a backed-up database on other servers in the cluster. -The other options is to seed the cluster from URI, where all servers to host a database are seeded with an identical seed from an external source specified by the URI. +There are two different ways to seed a cluster with data: + +* The first option is to use a _designated seeder_, where a designated server is used to create a backed-up database on other servers in the cluster. +* The other option is to seed the cluster from a URI, where all servers to host the database are seeded with an identical seed from an external source specified by that URI. +For more details, see xref:database-administration/standard-databases/seed-from-uri.adoc[Create a database from a URI]. + Keep in mind that using a designated seeder can be problematic in some situations as it is not known in advance how a database is going to be allocated to the servers in a cluster. Also, this method relies on the seed already existing on one of the servers. @@ -450,227 +336,6 @@ SHOW DATABASE foo; 9 rows available after 3 ms, consumed after another 1 ms ---- -[[cluster-seed-uri]] -=== Seed from URI - -This method seeds all servers with an identical seed from an external source, specified by the URI. -The seed can either be a full backup, a differential backup (see xref:clustering/databases.adoc#cloud-seed-provider[`CloudSeedProvider`]), or a dump from an existing database. -The sources of seeds are called _seed providers_. - -The mechanism is pluggable, allowing new sources of seeds to be supported (see link:https://www.neo4j.com/docs/java-reference/current/extending-neo4j/project-setup/#extending-neo4j-plugin-seed-provider[Java Reference -> Implement custom seed providers] for more information). -The product has built-in support for seed from a mounted file system (file), FTP server, HTTP/HTTPS server, Amazon S3, Google Cloud Storage, and Azure Cloud Storage. - -[NOTE] -==== -Amazon S3, Google Cloud Storage, and Azure Cloud Storage are supported by default, but the other providers require configuration of xref:configuration/configuration-settings.adoc#config_dbms.databases.seed_from_uri_providers[`dbms.databases.seed_from_uri_providers`]. -==== - -The URI of the seed is specified when the `CREATE DATABASE` command is issued: - -[source, cypher, role="noplay"] ----- -CREATE DATABASE foo OPTIONS {existingData: 'use', seedURI:'s3://myBucket/myBackup.backup'} ----- - -Download and validation of the seed is only performed as the new database is started. -If it fails, the database is not available and it has the `statusMessage`: `Unable to start database` of the `SHOW DATABASES` command. - -[source, cypher, role="noplay"] ----- -neo4j@neo4j> SHOW DATABASES; -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "seed3" | "standard" | [] | "read-write" | "localhost:7682" | "unknown" | FALSE | "online" | "offline" | "Unable to start database `DatabaseId{3fe1a59b[seed3]}`" | FALSE | FALSE | [] | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ----- - -To determine the cause of the problem, it is recommended to look at the `debug.log`. - -[NOTE] -==== -Starting from Neo4j 2025.01, seed from URI can also be used in combination with xref:database-administration/standard-databases/create-databases.adoc[`CREATE OR REPLACE DATABASE`]. -==== - - -[[file-seed-provider]] -==== FileSeedProvider - -The `FileSeedProvider` supports: - -** `file:` - -[[url-connection-seed-provider]] -==== URLConnectionSeedProvider - -The `URLConnectionSeedProvider` supports the following: - -** `ftp:` -** `http:` -** `https:` - -Starting from Neo4j 2025.01, the `URLConnectionSeedProvider` does not support `file`. -// This is true for both Cypher 5 and Cypher 25. - -[[cloud-seed-provider]] -==== CloudSeedProvider - -The `CloudSeedProvider` supports: - -** `s3:` -** `gs:` -** `azb:` - -The `CloudSeedProvider` supports using xref:backup-restore/modes.adoc#differential-backup[differential backup] files as seeds. -With the provided differential backup file, the `CloudSeedProvider` searches the directory containing differential backup files for a xref:backup-restore/online-backup.adoc#backup-chain[backup chain] ending at the specified differential backup, and then seeds using this backup chain. - -[.tabbed-example] -===== -[role=include-with-AWS-S3] -====== - -include::partial$/aws-s3-overrides.adoc[] - -include::partial$/aws-s3-credentials.adoc[] - -. Create database from `myBackup.backup`. -+ -[source,shell, role="nocopy"] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup' } ----- - -====== -[role=include-with-Google-cloud-storage] -====== - -include::partial$/gcs-credentials.adoc[] - -. Create database from `myBackup.backup`. -+ -[source,shell] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'gs://myBucket/myBackup.backup' } ----- -====== -[role=include-with-Azure-cloud-storage] -====== - -include::partial$/azb-credentials.adoc[] - -. Create database from `myBackup.backup`. -+ -[source,shell] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'azb://myStorageAccount/myContainer/myBackup.backup' } ----- -====== -===== - -Starting from Neo4j 2025.01, the `CloudSeedProvider` supports seeding up to a specific date or transaction ID using the `seedRestoreUntil` option. - -[role=label--new-2025.01] -Seed up to a specific date:: - -To seed up to a specific date, you need to pass the differential backup, which contains the data up to that date. -+ -[source,shell] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: datetime("2019-06-01T18:40:32.142+0100") } ----- -+ -This will seed the database with transactions committed before the provided timestamp. - -[role=label--new-2025.01] -Seed up to a specific transaction ID:: - -To seed up to a specific transaction ID, you need to pass the differential backup that contains the data up to that transaction ID. -+ -[source,shell] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: 123 } ----- -+ -This will seed the database with transactions up to, but not including transaction 123. - -[role=label--deprecated] -[[s3-seed-provider]] -==== S3SeedProvider - -// When Cypher 25 is released, we have to label this section 'Cypher 5' as this functionality is only available in Cypher 5. - -The `S3SeedProvider` supports: - -** `s3:` label:deprecated[Deprecated in 5.26] - - -[NOTE] -==== -Neo4j comes bundled with necessary libraries for AWS S3 connectivity. -Therefore, if you use `S3SeedProvider`,`aws cli` is not required but can be used with the `CloudSeedProvider`. -==== - -The `S3SeedProvider` requires additional configuration. -This is specified with the `seedConfig` option. -This option expects a comma-separated list of configurations. -Each configuration value is specified as a name followed by `=` and the value, as such: - -[source, cypher, role="noplay"] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1' } ----- - -`S3SeedProvider` also requires passing in credentials. -These are specified with the `seedCredentials` option. -Seed credentials are securely passed from the Cypher command to each server hosting the database. -For this to work, Neo4j on each server in the cluster must be configured with identical keystores. -This is identical to the configuration required by remote aliases, see xref:database-administration/aliases/remote-database-alias-configuration.adoc#remote-alias-config-DBMS_admin-A[Configuration of DBMS with remote database alias]. -If this configuration is not performed, the `seedCredentials` option fails. - -[source, cypher, role="noplay"] ----- -CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1', seedCredentials: [accessKey];[secretKey] } ----- -Where `accessKey` and `secretKey` are provided by AWS. - -==== Seed provider reference - -[cols="1,2,2",options="header"] -|=== -| URL scheme -| Seed provider -| URI example - -| `file:` -| `FileSeedProvider` -| `file://tmp/backup1.backup` - -| `ftp:` -| `URLConnectionSeedProvider` -| `ftp://myftp.com/backups/backup1.backup` - -| `http:` -| `URLConnectionSeedProvider` -| `\http://myhttp.com/backups/backup1.backup` - -| `https:` -| `URLConnectionSeedProvider` -| `\https://myhttp.com/backups/backup1.backup` - -| `s3:` -| `S3SeedProvider` label:deprecated[Deprecated in 5.26], + -`CloudSeedProvider` -| `s3://mybucket/backups/backup1.backup` - -| `gs:` -| `CloudSeedProvider` -| `gs://mybucket/backups/backup1.backup` - -| `azb:` -| `CloudSeedProvider` -| `azb://mystorageaccount.blob/backupscontainer/backup1.backup` -|=== - [[cluster-allow-deny-db]] == Controlling locations with allowed/denied databases @@ -689,6 +354,7 @@ If not set, there are no mode constraints on the server. == Change the default database You can use the procedure xref:procedures.adoc#procedure_dbms_setDefaultDatabase[`dbms.setDefaultDatabase("newDefaultDatabaseName")`] to change the default database for a DBMS. +Starting with Neo4j 2025.04, the default database can also be set to a local or remote database alias. . Ensure that the database to be set as default exists, otherwise create it using the command `CREATE DATABASE `. . Show the name and status of the current default database by using the command `SHOW DEFAULT DATABASE`. diff --git a/modules/ROOT/pages/clustering/disaster-recovery.adoc b/modules/ROOT/pages/clustering/disaster-recovery.adoc index 98f846c57..c8e522940 100644 --- a/modules/ROOT/pages/clustering/disaster-recovery.adoc +++ b/modules/ROOT/pages/clustering/disaster-recovery.adoc @@ -96,7 +96,7 @@ Because both of these steps are executed by modifying the `system` database, mak ==== Verifying the state -The `system` database's write availability can be verified by using the xref:clustering/monitoring/status-check.adoc#monitoring-replication[Status check] procedure. +The `system` database's write availability can be verified by using the xref:clustering/monitoring/status-check.adoc[Status check] procedure. [source, shell] ---- @@ -122,7 +122,7 @@ It is important to get a `system` database that is as up-to-date as possible, so [NOTE] ===== This section of the disaster recovery guide uses `neo4j-admin` commands. -For more information about the used commands, see xref:tools/neo4j-admin/index.adoc#neo4j-admin-commands[neo4j-admin commands]. +For more information about the used commands, see xref:neo4j-admin-neo4j-cli.adoc#neo4j-admin-commands[neo4j-admin commands]. ===== . Shut down the Neo4j process on all servers. @@ -211,7 +211,7 @@ A database can be set to `READ-ONLY` before it is started to avoid updates on th ===== . On each server, run `CALL dbms.cluster.statusCheck([])` to check the write availability for all databases running in primary mode on this server. -See xref:clustering/monitoring/status-check.adoc#monitoring-replication[Monitoring replication] for more information. +See xref:clustering/monitoring/status-check.adoc[Monitoring replication] for more information. + [NOTE] ===== @@ -220,14 +220,14 @@ Instead, check that the primary is allocated on an available server and that it ===== . For each database that is not write-available, recreate it to move it from lost servers and regain write availability. -Go to xref:clustering/databases.adoc#recreate-databases[Recreate databases] for more information about recreate options. +Go to xref:database-administration/standard-databases/recreate-database.adoc[Recreate a database] for more information about recreate options. Remember to make sure there are recent backups for the databases before recreating them. See xref:backup-restore/online-backup.adoc[Online backup] for more information. -If any database has `currentStatus` = `quarantined` on an available server, recreate them from backup using xref:clustering/databases.adoc#uri-seed[Backup as seed]. +If any database has `currentStatus` = `quarantined` on an available server, recreate them from backup using xref:database-administration/standard-databases/recreate-database.adoc#uri-seed[Backup as seed]. + [CAUTION] ===== -If you recreate databases using xref:clustering/databases.adoc#undefined-servers[undefined servers] or xref:clustering/databases.adoc#undefined-servers-backup[undefined servers with fallback backup], the store might not be recreated as up-to-date as possible in certain edge cases where the `system` database has been restored. +If you recreate databases using xref:database-administration/standard-databases/recreate-database.adoc#undefined-servers[undefined servers] or xref:database-administration/standard-databases/recreate-database.adoc#undefined-servers-backup[undefined servers with fallback backup], the store might not be recreated as up-to-date as possible in certain edge cases where the `system` database has been restored. ===== . For each `Cordoned` server, run `DEALLOCATE DATABASES FROM SERVER cordoned-server-id` on one of the available servers. @@ -258,13 +258,13 @@ If they are still desired to be in stopped state, run `STOP DATABASE started-db [CAUTION] ==== -Remember, recreating a database takes an unbounded amount of time since it may involve copying the store to a new server, as described in xref:clustering/databases.adoc#recreate-databases[Recreate databases]. +Remember, recreating a database takes an unbounded amount of time since it may involve copying the store to a new server, as described in xref:database-administration/standard-databases/recreate-database.adoc[Recreate a database]. Therefore, an allocation with `currentStatus` = `starting` will probably reach the `requestedStatus` given some time. ==== [[example-verification]] ==== Verifying the state -You can verify all clustered databases' write availability by using the xref:clustering/monitoring/status-check.adoc#monitoring-replication[status check] procedure. +You can verify all clustered databases' write availability by using the xref:clustering/monitoring/status-check.adoc[status check] procedure. [source, shell] ---- @@ -291,14 +291,14 @@ Recreations might fail for different reasons, but one example is that the checks . Identify all write-unavailable databases by running `CALL dbms.cluster.statusCheck([])` as described in the xref:clustering/disaster-recovery.adoc#example-verification[Example verification] part of this disaster recovery step. Filter out all databases desired to be stopped, so that they are not recreated unnecessarily. . Recreate every database that is not write-available and has not been recreated previously. -See xref:clustering/databases.adoc#recreate-databases[Recreate databases] for more information. +See xref:database-administration/standard-databases/recreate-database.adoc[Recreate a database] for more information. Remember to make sure there are recent backups for the databases before recreating them. See xref:backup-restore/online-backup.adoc[Online backup] for more information. -If any database has `currentStatus` = `quarantined` on an available server, recreate them from backup using xref:clustering/databases.adoc#uri-seed[Backup as seed]. +If any database has `currentStatus` = `quarantined` on an available server, recreate them from backup using xref:database-administration/standard-databases/recreate-database.adoc#uri-seed[Backup as seed]. + [CAUTION] ===== -If you recreate databases using xref:clustering/databases.adoc#undefined-servers[undefined servers] or xref:clustering/databases.adoc#undefined-servers-backup[undefined servers with fallback backup], the store might not be recreated as up-to-date as possible in certain edge cases where the `system` database has been restored. +If you recreate databases using xref:database-administration/standard-databases/recreate-database.adoc#undefined-servers[undefined servers] or xref:database-administration/standard-databases/recreate-database.adoc#undefined-servers-backup[undefined servers with fallback backup], the store might not be recreated as up-to-date as possible in certain edge cases where the `system` database has been restored. ===== . Run `SHOW DATABASES` and check any recreated databases that are not write-available. @@ -306,6 +306,6 @@ Recreating a database will not complete if one of the following messages is disp ** `Seeders ServerId1 and ServerId2 have different checksums for transaction TransactionId. All seeders must have the same checksum for the same append index.` ** `Seeders ServerId1 and ServerId2 have incompatible storeIds. All seeders must have compatible storeIds.` ** `No store found on any of the seeders ServerId1, ServerId2...` -. For each database which will not complete recreation, recreate them from backup using xref:clustering/databases.adoc#uri-seed[Backup as seed]. +. For each database which will not complete recreation, recreate them from backup using xref:database-administration/standard-databases/recreate-database.adoc#uri-seed[Backup as seed]. ==== diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc index a3cde8632..2f64872ad 100644 --- a/modules/ROOT/pages/clustering/index.adoc +++ b/modules/ROOT/pages/clustering/index.adoc @@ -25,6 +25,7 @@ This chapter describes the following: * xref:clustering/server-syntax.adoc[Server commands reference] -- Reference of Cypher administrative commands to add and manage servers. * xref:clustering/clustering-advanced/index.adoc[Advanced clustering] -- Some more advanced features of Neo4j clusters. ** xref:clustering/clustering-advanced/default-database.adoc[Default database in a cluster] -- The initial default database created when the DBMS starts for the first time. +** xref:clustering/clustering-advanced/unbind.adoc[Unbind a server] -- How to remove and archive the cluster state of a cluster server so that it can rebind to a cluster. ** xref:clustering/clustering-advanced/multi-data-center-routing.adoc[Multi-data center routing] -- Clusters on mutli-data centers. ** xref:clustering/clustering-advanced/reconciler.adoc[Reconciler] -- An internal component that observes the requested state of a server and makes changes to the server to match that state. * xref:clustering/glossary.adoc[Clustering glossary] -- A glossary of terms related to the Neo4j clustering. diff --git a/modules/ROOT/pages/clustering/monitoring/endpoints.adoc b/modules/ROOT/pages/clustering/monitoring/endpoints.adoc index 15122e98a..dcc886886 100644 --- a/modules/ROOT/pages/clustering/monitoring/endpoints.adoc +++ b/modules/ROOT/pages/clustering/monitoring/endpoints.adoc @@ -145,20 +145,27 @@ Therefore, details such as `leader` and `raftCommandsPerSecond` are database-spe -------------- ==== +[[status-endpoint-descriptions]] .Status endpoint descriptions -[options="header", cols="2,1,1,2,4"] +[options="header", cols="2,1,1,2,4a"] |=== | Field | Type |Optional| Example | Description | `core` | boolean | no | `true` | Used to distinguish between if the server is hosting the database in primary (core) or secondary mode. -| `lastAppliedRaftIndex` | number | no | `4321` | Every transaction in a cluster is associated with a raft index. - - Gives an indication of what the latest applied raft log index is. +| `lastAppliedRaftIndex` | number | no | `4321` | Every transaction in a cluster is associated with a raft index. + +Gives an indication of what the latest applied raft log index is. | `participatingInRaftGroup` | boolean | no | `false` | A participating member is able to vote. A primary is considered participating when it is part of the voter membership and has kept track of the leader. -| `votingMembers` | string[] | no | `[]` | A member is considered a voting member when the leader has been receiving communication with it. +| `votingMembers` | string[] | no | `[]` | A member is considered a voting member when the leader has been receiving communication with it. + +List of member's `memberId` that are considered part of the voting set by this primary. +| `isHealthy` | boolean | no | `true` | Indicates that the local database on this cluster member has not encountered a critical error that can block database operation. + +[CAUTION] +==== +The `isHealthy` status applies only to this member's local database. +It does not reflect the overall health of the database if it is clustered. - List of member's `memberId` that are considered part of the voting set by this primary. -| `isHealthy` | boolean | no | `true` | Reflects that the local database of this member has not encountered a critical error preventing it from writing locally. +A cluster member may still report `"isHealthy": true` even if the database currently has no leader and so cannot accept write transactions. +==== | `memberId` | string | no | `30edc1c4-519c-4030-8348-7cb7af44f591` | Every member in a cluster has it's own unique member id to identify it. Use `memberId` to distinguish between primary and secondary servers. | `leader` | string | yes | `80a7fb7b-c966-4ee7-88a9-35db8b4d68fe` | Follows the same format as `memberId`, but if it is null or missing, then the leader is unknown. @@ -171,6 +178,8 @@ It is recommended to use the metric `.clustering.core.commit_index` on e After an instance has been switched on, the status endpoint can be accessed in order to make sure all the guarantees listed in the table below are met. + + To get the most accurate view of a cluster it is strongly recommended to access the _status endpoint_ on all primary members and compare the result. The following table explains how results can be compared. diff --git a/modules/ROOT/pages/clustering/monitoring/status-check.adoc b/modules/ROOT/pages/clustering/monitoring/status-check.adoc index 76724d9a0..6556055c7 100644 --- a/modules/ROOT/pages/clustering/monitoring/status-check.adoc +++ b/modules/ROOT/pages/clustering/monitoring/status-check.adoc @@ -1,7 +1,6 @@ :description: This section describes how to monitor a database's availability with the help of the cluster status check procedure. :page-role: enterprise-edition -[[monitoring-replication]] = Monitor replication status The xref:procedures.adoc#procedure_dbms_cluster_statusCheck[`dbms.cluster.statusCheck()`] procedure can be used to monitor the ability to replicate in clustered databases. diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc index b2ae9476a..2ce4ce6ea 100644 --- a/modules/ROOT/pages/clustering/servers.adoc +++ b/modules/ROOT/pages/clustering/servers.adoc @@ -93,7 +93,6 @@ 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. @@ -323,7 +322,7 @@ Once enabled, a server does not automatically host databases unless: * Another server is transitioned to the _Deallocating_ state. * You explicitly rebalance the databases across the cluster. -The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s), see xref:clustering/databases.adoc#_reallocate_databases[Reallocate databases] for more information. +The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s), see xref:clustering/databases.adoc#reallocate-databases[Reallocate databases] for more information. [[removing-servers]] diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 7a38695b0..56afb6264 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -36,7 +36,7 @@ If not specified, it defaults to zero hostings in secondary mode. ==== Any setting with the `initial` prefix is only effective on the first startup of the DBMS. Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. -See xref:clustering/databases.adoc#_create_database[`CREATE DATABASE`] for more information. +See xref:clustering/databases.adoc#create-database[`CREATE DATABASE`] for more information. To view the current default settings, use the xref:procedures.adoc#procedure_dbms_showTopologyGraphConfig[`dbms.showTopologyGraphConfig`] procedure. ==== diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 0bd459b01..82d977cd9 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -104,23 +104,23 @@ The configured server uses all the addresses from the SRV record to join or form [[clustering-discovery-k8s]] === Discovery in Kubernetes -A special case is when a cluster is running in https://kubernetes.io/[Kubernetes^] and each server is running as a Kubernetes service. -Then, the addresses of the other servers can be obtained using the List Service API, as described in the https://kubernetes.io/docs/reference/kubernetes-api/[Kubernetes API documentation^]. +A special case is when a cluster is running in link:https://kubernetes.io/[Kubernetes] and each server is running as a Kubernetes service. +Then, the addresses of the other servers can be obtained using the List Service API, as described in the link:https://kubernetes.io/docs/reference/kubernetes-api/[Kubernetes API documentation]. The following settings are used to configure for this scenario: * Set `dbms.cluster.discovery.resolver_type=K8S`. * Set `xref:configuration/configuration-settings.adoc#config_dbms.kubernetes.label_selector[dbms.kubernetes.label_selector]` to the label selector for the cluster services. -For more information, see the https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors[Kubernetes official documentation^]. +For more information, see the link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors[Kubernetes official documentation]. * Set xref:configuration/configuration-settings.adoc#config_dbms.kubernetes.discovery.service_port_name[`dbms.kubernetes.discovery.service_port_name]` to the name of the service port used in the Kubernetes service definition for the Core's discovery port. -For more information, see the https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#serviceport-v1-core[Kubernetes official documentation^]. +For more information, see the link:https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/[Kubernetes official documentation]. With this configuration, `dbms.cluster.endpoints` is not used and any value assigned to it is ignored. [NOTE] ==== * The pod running Neo4j must use a service account that has permission to list services. -For further information, see the Kubernetes documentation on https://kubernetes.io/docs/reference/access-authn-authz/rbac/[RBAC authorization^] or https://kubernetes.io/docs/reference/access-authn-authz/abac/[ABAC authorization^]. +For further information, see the Kubernetes documentation on link:https://kubernetes.io/docs/reference/access-authn-authz/rbac/[RBAC authorization] or link:https://kubernetes.io/docs/reference/access-authn-authz/abac/[ABAC authorization]. * The configured `server.cluster.advertised_address` must exactly match the Kubernetes-internal DNS name, which is of the form `..svc.cluster.local`. ==== diff --git a/modules/ROOT/pages/clustering/setup/single-to-cluster.adoc b/modules/ROOT/pages/clustering/setup/single-to-cluster.adoc index 7fd17833c..3abea78d2 100644 --- a/modules/ROOT/pages/clustering/setup/single-to-cluster.adoc +++ b/modules/ROOT/pages/clustering/setup/single-to-cluster.adoc @@ -17,7 +17,8 @@ See xref:clustering/setup/analytics-cluster.adoc[] for more information on analy .Move from a single `system` database to a cluster with three `system` primaries In this example, a standalone server named `server01` is running and two additional servers, `server02` and `server03`, are to be added to form a cluster. -The two additional servers are configured according to xref:clustering/setup/deploy.adoc#cluster-example-configure-a-three-primary-cluster[Configure a cluster with three servers] and are _not_ running. +The two additional servers are configured according to xref:clustering/setup/deploy.adoc#cluster-example-configure-a-three-primary-cluster[Configure a cluster with three servers]. +These two new servers should _not_ be started up yet. Neo4j Enterprise Edition is installed on all three servers. Start by stopping the standalone server. diff --git a/modules/ROOT/pages/configuration/command-expansion.adoc b/modules/ROOT/pages/configuration/command-expansion.adoc index d6b4c69ca..5687233ca 100644 --- a/modules/ROOT/pages/configuration/command-expansion.adoc +++ b/modules/ROOT/pages/configuration/command-expansion.adoc @@ -110,4 +110,4 @@ In this case, the execution stops and the server does not start. * Errors for incorrect values -- The returned value is not the one expected for the setting. In this case, the server does not start. -For more information, see xref:tools/neo4j-admin/index.adoc#neo4j-admin-exit-codes[Exit codes]. +For more information, see xref:neo4j-admin-neo4j-cli.adoc#neo4j-admin-exit-codes[Exit codes]. diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index f87138b06..316dcfd77 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -3,7 +3,7 @@ :description: This page provides a reference to the Neo4j configuration settings. :page-styles: hide-table-captions -The Neo4j configuration settings are set in xref::/configuration/file-locations.adoc#file-locations[_neo4j.conf_]. +The Neo4j configuration settings are set in xref::/configuration/file-locations.adoc[_neo4j.conf_]. Refer to xref:configuration/neo4j-conf.adoc#_configuration_settings[The neo4j.conf file] for details on how to use configuration settings. For lists of deprecated and removed configuration settings in 2025.x, refer to the page xref:changes-deprecations-removals.adoc[Changes, deprecations, and removals in Neo4j 2025.x]. @@ -1689,7 +1689,7 @@ m|+++true+++ |=== -[role=label--enterprise-edition] +[role=label--enterprise-edition label--deprecated-2025.05] [[config_dbms.routing.load_balancing.plugin]] === `dbms.routing.load_balancing.plugin` @@ -1697,9 +1697,9 @@ m|+++true+++ [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== |Description -a|The load balancing plugin to use. +a|Vary the order of the entries in routing tables each time one is produced. This means that different clients should select a range of servers as their first contact, reducing the chance of all clients contacting the same server if alternatives are available. This makes the load across the servers more even. |Valid values -a|A string that specified load balancer plugin exist.. +a|A string. |Default value m|+++server_policies+++ |=== @@ -1777,6 +1777,22 @@ They can be used to tune the performance of Cypher queries or to restrict the ki For more information, see xref:/performance/statistics-execution-plans.adoc[Statistics and execution plans]. +[role=label--new-2025.06] +[[config_db.query.default_language]] +=== `db.query.default_language` + +.db.query.default_language +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] +|=== +|Description +a|The default language of a database determines which language is used to evaluate queries that do not explicitly select a language. This setting determines the default language used for new (and initial) databases where not specified as part of `CREATE` or `ALTER` database. +|Valid values +a|One of [CYPHER_5, CYPHER_25] that the [] values acceptance depend on 'internal.dbms.cypher.enable_experimental_versions'. +|Default value +m|+++CYPHER_5+++ +|=== + + [[config_dbms.cypher.forbid_exhaustive_shortestpath]] === `dbms.cypher.forbid_exhaustive_shortestpath` @@ -1843,7 +1859,7 @@ m|+++OFF+++ |=== For some queries, the planner can infer predicates such as labels or types from the graph structure that can improve estimating the number of rows that each operator produces. -for more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/execution-plans/#runtimes-reading-execution-plans[Cypher Manual -> Execution plans and query tuning -> Understanding execution plans]. + +for more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/execution-plans/[Cypher Manual -> Execution plans and query tuning -> Understanding execution plans]. + For details on how to configure this setting on a per-query basis,effectively overriding this setting on that particular query, see link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/query-tuning/#cypher-infer-schema-parts[Cypher Manual -> Query tuning -> Cypher infer schema parts]. // In general, inferring more information should improve the estimation and thereby the planner's decisions. @@ -2092,7 +2108,7 @@ The DBMS settings must be consistent across all configuration files in a cluster [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== |Description -a|Name of the default database (aliases are not supported). + +a|Name of the default database. + NOTE: This setting is not the same as `dbms.default_database`, which was used to set the default database in Neo4j 4.x and earlier versions. The `initial.dbms.default_database` setting is meant to set the default database *before* the creation of the DBMS. @@ -2143,7 +2159,7 @@ The following values are available: `CloudSeedProvider`, `FileSeedProvider`, `S3 This list specifies enabled seed providers. If a seed source (URI scheme) is supported by multiple providers in the list, the first matching provider will be used. If the list is set to empty, the seed from URI functionality is effectively disabled. -See xref:/clustering/databases.adoc#cluster-seed-uri[Seed from URI] for more information. +See xref::database-administration/standard-databases/seed-from-uri.adoc[Seed from a URI] for more information. |Valid values a|A comma-separated list where each element is a string. |Default value @@ -2457,6 +2473,10 @@ a|A boolean. m|+++false+++ |=== +[NOTE] +==== +Keep in mind that if Neo4j receives a malformed query that cannot be parsed, it cannot obfuscate its literals (because it does not know which parts are literals) and, therefore, the query text will not be included in any logging. +==== [role=label--dynamic] [[config_db.logs.query.parameter_logging_enabled]] @@ -3096,9 +3116,16 @@ a|Specifies which metrics should be enabled by using a comma separated list of g |Valid values a|A comma-separated list where each element is A simple globbing pattern that can use `*` and `?`.. |Default value -m|+++*bolt.connections*,*bolt.messages_received*,*bolt.messages_started*,*dbms.pool.bolt.free,*dbms.pool.bolt.total_size,*dbms.pool.bolt.total_used,*dbms.pool.bolt.used_heap,*cluster.raft.is_leader,*cluster.raft.last_leader_message,*cluster.raft.replication_attempt,*cluster.raft.replication_fail,*cluster.raft.last_applied,*cluster.raft.last_appended,*cluster.raft.append_index,*cluster.raft.commit_index,*cluster.raft.applied_index,*cluster.internal.discovery.memberset.left,*cluster.internal.discovery.crdt.gossip_id_data.size,*cluster.internal.discovery.crdt.server_data.size,*cluster.internal.discovery.crdt.database_data.size,*cluster.internal.discovery.crdt.leader_data.size,*cluster.internal.discovery.crdt.total_merge_operations,*cluster.internal.discovery.crdt.total_update_operations,*cluster.internal.discovery.gossip.incoming_queue_size,*cluster.internal.discovery.gossip.total_received_data,*cluster.internal.discovery.gossip.total_sent_data,*cluster.internal.discovery.gossip.uncontactable_members_exist,*check_point.*,*cypher.replan_events,*cypher.cache*,*ids_in_use*,*.neo4j.count.*,*pool.transaction.*.total_used,*pool.transaction.*.used_heap,*pool.transaction.*.used_native,*store.size*,*transaction.active_read,*transaction.active_write,*transaction.committed*,*transaction.last_committed_tx_id,*transaction.peak_concurrent,*transaction.rollbacks*,*page_cache.hit*,*page_cache.page_faults,*page_cache.usage_ratio,*vm.file.descriptors.count,*vm.gc.time.*,*vm.heap.used,*vm.memory.buffer.direct.used,*vm.memory.pool.g1_eden_space,*vm.memory.pool.g1_old_gen,*vm.pause_time,*vm.thread*,*db.query.execution*,*protocol*+++ label:changed[Changed in 2025.03] +m|+++*bolt.connections*,*bolt.messages_received*,*bolt.messages_started*,*dbms.pool.bolt.free,*dbms.pool.bolt.total_size,*dbms.pool.bolt.total_used,*dbms.pool.bolt.used_heap,*cluster.raft.is_leader,*cluster.raft.last_leader_message,*cluster.raft.replication_attempt,*cluster.raft.replication_fail,*cluster.raft.last_applied,*cluster.raft.last_appended,*cluster.raft.append_index,*cluster.raft.commit_index,*cluster.raft.applied_index,*check_point.*,*cypher.replan_events,*cypher.cache*,*ids_in_use*,*.neo4j.count.*,*pool.transaction.*.total_used,*pool.transaction.*.used_heap,*pool.transaction.*.used_native,*store.size*,*transaction.active_read,*transaction.active_write,*transaction.committed*,*transaction.last_committed_tx_id,*transaction.peak_concurrent,*transaction.rollbacks*,*page_cache.hit*,*page_cache.page_faults,*page_cache.usage_ratio,*vm.file.descriptors.count,*vm.gc.time.*,*vm.heap.used,*vm.memory.buffer.direct.used,*vm.memory.pool.g1_eden_space,*vm.memory.pool.g1_old_gen,*vm.pause_time,*vm.thread*,*db.query.execution*,*protocol*+++ label:changed[Changed in 2025.03] label:changed[Changed in 2025.06] |=== +[NOTE] +==== +The default value of the `server.metrics.filter` was changed in Neo4j 2025.03 and 2025.06. + +For details, refer to the xref:changes-deprecations-removals.adoc#_configuration_settings_2[Changes, deprecations, and removals in Neo4j 2025.x]. +==== + [role=label--enterprise-edition] [[config_server.metrics.graphite.enabled]] @@ -3328,8 +3355,8 @@ m|+++true+++ == Kubernetes settings -The Kubernetes settings are used to configure a cluster running on https://kubernetes.io/[Kubernetes^], where each server is running as a Kubernetes service. -The addresses of the other servers can be obtained using the List Service API, as described in the https://kubernetes.io/docs/reference/kubernetes-api/[Kubernetes API documentation^]. +The Kubernetes settings are used to configure a cluster running on https://kubernetes.io/[Kubernetes], where each server is running as a Kubernetes service. +The addresses of the other servers can be obtained using the List Service API, as described in the https://kubernetes.io/docs/reference/kubernetes-api/[Kubernetes API documentation]. For more information, see xref:clustering/setup/discovery.adoc#clustering-discovery-k8s[Discovery in Kubernetes]. @@ -4798,6 +4825,23 @@ m|+++127.0.0.1:6362+++ |=== +[role=label--enterprise-edition label--new-2025.05] +[[config_server.backup.advertised_address]] +=== `server.backup.advertised_address` + +.server.backup.advertised_address +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] +|=== +|Description +a|The advertised address for the backup server. Default is the default advertised address combined with port defined in the backup listen address. +|Valid values +a|A socket address in the format of `hostname:port`, `hostname`, or `:port` that is an accessible address. If missing, it is acquired from `server.default_advertised_address`. +|Default value +m|+++:0+++ +|=== + + + [role=label--enterprise-edition] [[config_server.backup.store_copy_max_retry_time_per_request]] === `server.backup.store_copy_max_retry_time_per_request` @@ -4973,7 +5017,7 @@ m|+++neo4j+++ == Transaction settings The transaction settings helps you manage the transactions in your database, for example, the transaction timeout, the lock acquisition timeout, the maximum number of concurrently running transactions, etc. -For more information, see xref:/database-internals/transaction-management.adoc#_manage-transactions[Manage transactions] and xref:/database-internals/concurrent-data-access.adoc[Concurrent data access]. +For more information, see xref:/database-internals/transaction-management.adoc#_manage_transactions[Manage transactions] and xref:/database-internals/concurrent-data-access.adoc[Concurrent data access]. [role=label--dynamic] diff --git a/modules/ROOT/pages/configuration/file-locations.adoc b/modules/ROOT/pages/configuration/file-locations.adoc index 2a5296496..b2db0669c 100644 --- a/modules/ROOT/pages/configuration/file-locations.adoc +++ b/modules/ROOT/pages/configuration/file-locations.adoc @@ -1,6 +1,5 @@ :description: An overview of where files are stored in the different Neo4j distributions, and the necessary file permissions for running Neo4j. -[[file-locations]] = Default file locations [[neo4j-directories]] @@ -24,7 +23,7 @@ For the Neo4j's uses of the Java Native Access (JNA) library, set `server.jvm.ad [[neo4j-bin]] === Bin -The _bin_ directory contains the Neo4j running script and built-in tools, such as xref:tools/cypher-shell.adoc[Cypher Shell] and xref:tools/neo4j-admin/index.adoc[Neo4j Admin]. +The _bin_ directory contains the Neo4j running script and built-in tools, such as xref:cypher-shell.adoc[Cypher Shell] and xref:neo4j-admin-neo4j-cli.adoc[]. File permissions:: Read only and execute. diff --git a/modules/ROOT/pages/configuration/index.adoc b/modules/ROOT/pages/configuration/index.adoc index da8520f73..3cd4c696b 100644 --- a/modules/ROOT/pages/configuration/index.adoc +++ b/modules/ROOT/pages/configuration/index.adoc @@ -10,8 +10,11 @@ The topics described are: * xref:configuration/ports.adoc[Ports] -- An overview of the ports relevant to a Neo4j installation. * xref:configuration/connectors.adoc[Configure network connectors] -- How to configure network connectors for Neo4j. * xref:configuration/set-initial-password.adoc[Set initial password] -- How to set an initial password. -* xref:configuration/plugins.adoc[Configure Neo4j plugins] -- How to load plugins to a Neo4j deployment. +* xref:configuration/neo4j-admin-memrec.adoc[Get initial memory recommendations] -- How to get initial memory recommendations for Neo4j. +* xref:configuration/plugins.adoc[Configure Neo4j plugins] -- How to load plugins into a Neo4j deployment. * xref:configuration/dynamic-settings.adoc[Update dynamic settings] -- How to configure certain Neo4j parameters while Neo4j is running. +* xref:configuration/migrate-configuration.adoc[Migrate configurations] -- How to migrate configuration settings from a previous version of Neo4j to a new version. +* xref:configuration/validate-config.adoc[Validate configurations] -- How to validate Neo4j and Log4j configurations. * xref:configuration/configuration-settings.adoc[Configuration settings] -- A complete reference of all configuration settings. For a complete reference of Neo4j configuration settings, see xref:configuration/configuration-settings.adoc[All configuration settings]. diff --git a/modules/ROOT/pages/tools/neo4j-admin/migrate-configuration.adoc b/modules/ROOT/pages/configuration/migrate-configuration.adoc similarity index 97% rename from modules/ROOT/pages/tools/neo4j-admin/migrate-configuration.adoc rename to modules/ROOT/pages/configuration/migrate-configuration.adoc index 8798caa87..d1fe7cffc 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/migrate-configuration.adoc +++ b/modules/ROOT/pages/configuration/migrate-configuration.adoc @@ -1,11 +1,11 @@ [[neo4j-admin-migrate-configuration]] -= Migrate the Neo4j configuration file += Migrate configurations :description: This chapter describes the `neo4j-admin server migrate-configuration` command. You can use the `migrate-configuration` command to migrate a legacy Neo4j configuration file to the current format. The new version will be written in a target configuration directory. The default location for both the source and target configuration directory is the configuration directory specified by `NEO_CONF` or the default configuration directory for this installation. -Starting with Neo4j 2025.01, the root location of the configuration directory is xref:configuration/configuration-settings.adoc#_server_directories_settings.adoc#config_server.directories.configuration[`server.directories.configuration=conf`]. +Starting with Neo4j 2025.01, the root location of the configuration directory is xref:configuration/configuration-settings.adoc#config_server.directories.configuration[`server.directories.configuration=conf`]. If the source and target directories are the same, the original configuration files will be renamed. A configuration provided using `--additional-config` option will not be migrated. diff --git a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-memrec.adoc b/modules/ROOT/pages/configuration/neo4j-admin-memrec.adoc similarity index 91% rename from modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-memrec.adoc rename to modules/ROOT/pages/configuration/neo4j-admin-memrec.adoc index 4e6f6b4af..50f694b22 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-memrec.adoc +++ b/modules/ROOT/pages/configuration/neo4j-admin-memrec.adoc @@ -1,6 +1,6 @@ :description: This chapter describes the `memory-recommendation` command of Neo4j Admin. [[neo4j-admin-memrec]] -= Memory recommendations += Get initial memory recommendations You can use the `neo4j-admin server memory-recommendation` command to get an initial recommendation on how to configure the memory parameters of your Neo4j DBMS. @@ -19,7 +19,7 @@ neo4j-admin server memory-recommendation [-h] [--docker] [--expand-commands] The command prints heuristic memory settings recommendations for the Neo4j JVM heap and pagecache. It either uses the total system memory or the amount of memory specified in the `--memory` argument. The heuristic assumes that the system is dedicated to running Neo4j. -If this is not the case, then use the --memory argument to specify how much memory can be expected to be dedicated to Neo4j. +If this is not the case, then use the `--memory` argument to specify how much memory can be expected to be dedicated to Neo4j. The output is formatted such that it can be copy-pasted into the _neo4j.conf_ file. The argument `--docker` outputs environmental variables that can be passed to a Neo4j Docker container. @@ -36,7 +36,7 @@ The `neo4j-admin server memory-recommendation` command has the following options | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | diff --git a/modules/ROOT/pages/configuration/neo4j-conf.adoc b/modules/ROOT/pages/configuration/neo4j-conf.adoc index 250c3ac47..ebf868058 100644 --- a/modules/ROOT/pages/configuration/neo4j-conf.adoc +++ b/modules/ROOT/pages/configuration/neo4j-conf.adoc @@ -3,7 +3,7 @@ = The neo4j.conf file The _neo4j.conf_ file is the main source of configuration settings in Neo4j and includes the mappings of configuration setting keys to values. -The location of the _neo4j.conf_ file in the different configurations of Neo4j is listed in xref:configuration/file-locations.adoc#table-file-locations[Default file locations]. +The location of the _neo4j.conf_ file in the different configurations of Neo4j is listed in xref:configuration/file-locations.adoc[Default file locations]. Most of the configuration settings in the _neo4j.conf_ file apply directly to Neo4j itself, but there are also other settings related to the Java Runtime (the JVM) on which Neo4j runs. For more information, see the xref:configuration/neo4j-conf.adoc#neo4j-conf-JVM[JVM specific configuration settings]. diff --git a/modules/ROOT/pages/configuration/plugins.adoc b/modules/ROOT/pages/configuration/plugins.adoc index ea4546e93..f4876802b 100644 --- a/modules/ROOT/pages/configuration/plugins.adoc +++ b/modules/ROOT/pages/configuration/plugins.adoc @@ -26,12 +26,12 @@ The following plugins are supported: | APOC Extended | `apoc-extended` | -| https://neo4j.com/labs/apoc/5/[APOC Extended user guide (Labs project)] +| link:https://neo4j.com/labs/apoc/5/[APOC Extended user guide (Labs project)] | APOC | `apoc` | -| https://neo4j.com/docs/apoc/current/[APOC user guide] +| link:https://neo4j.com/docs/apoc/current/[APOC user guide] | Bloom Enterprise footnote:[You can also get basic access to Bloom via Graph Apps in Neo4j Desktop without a license key. See link:{neo4j-docs-base-uri}/bloom-user-guide/current/bloom-installation/bloom-deployment-modes/[Bloom deployment modes] for more details.] | `bloom` @@ -66,12 +66,12 @@ The following plugins are supported: | Neo Semantics | `n10s` | -| https://neo4j.com/labs/nsmtx-rdf/[Neo Semantics] +| link:https://neo4j.com/labs/nsmtx-rdf/[Neo Semantics] |=== For more information on using plugins in a different Neo4j setup, see: -* link:{neo4j-docs-base-uri}/desktop-manual/current/operations/install-plugin/[Neo4j Desktop -> Install a plugin] +* link:{neo4j-docs-base-uri}/desktop-manual/current/operations/instance-management/#_install_plugins[Neo4j Desktop -> Install a plugin] * xref:docker/plugins.adoc[Docker -> Plugins] * xref:/kubernetes/plugins.adoc[Kubernetes -> Plugins] * link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/project-setup/#_build_dependencies[Java-Reference -> Setting up a plugin project]. diff --git a/modules/ROOT/pages/configuration/ports.adoc b/modules/ROOT/pages/configuration/ports.adoc index 76973bbab..63323523d 100644 --- a/modules/ROOT/pages/configuration/ports.adoc +++ b/modules/ROOT/pages/configuration/ports.adoc @@ -235,8 +235,7 @@ Default port: `2003` This is an outbound connection that enables a Neo4j instance to communicate with a Graphite server. -For further information, see xref:monitoring/metrics/reference.adoc#metrics-graphite[] and the https://graphite.readthedocs.io/en/stable/carbon-daemons.html[Graphite official documentation]. - +For further information, see xref:monitoring/metrics/expose.adoc#metrics-graphite[Expose metrics -> Graphite] and the https://graphite.readthedocs.io/en/stable/carbon-daemons.html[Graphite official documentation]. === Prometheus monitoring @@ -264,7 +263,7 @@ Default port: `3637` | `xref:configuration/configuration-settings.adoc#config_server.jvm.additional[+++server.jvm.additional=-Dcom.sun.management.jmxremote.port=3637+++]` | `3637` | Additional setting for exposing the Java Management Extensions (JMX). |=== -For further information, see link:{neo4j-docs-base-uri}/java-reference/{page-version}/jmx-metrics#jmx-metrics[Java Reference -> JMX metrics] and https://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html[the official documentation on Monitoring and Management Using JMX]. +For further information, see link:{neo4j-docs-base-uri}/java-reference/{page-version}/jmx-metrics/[Java Reference -> JMX metrics] and https://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html[the official documentation on Monitoring and Management Using JMX]. === Remote debugging @@ -278,4 +277,4 @@ Default port: `5005` | `xref:configuration/configuration-settings.adoc#config_server.jvm.additional[+++server.jvm.additional=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005+++]` | `:5005` | Additional setting for exposing remote debugging. |=== -For more information, see the link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/server-debugging#server-debugging[Java Reference -> Setup for remote debugging]. +For more information, see the link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/server-debugging/[Java Reference -> Setup for remote debugging]. diff --git a/modules/ROOT/pages/tools/neo4j-admin/validate-config.adoc b/modules/ROOT/pages/configuration/validate-config.adoc similarity index 100% rename from modules/ROOT/pages/tools/neo4j-admin/validate-config.adoc rename to modules/ROOT/pages/configuration/validate-config.adoc diff --git a/modules/ROOT/pages/tools/cypher-shell.adoc b/modules/ROOT/pages/cypher-shell.adoc similarity index 89% rename from modules/ROOT/pages/tools/cypher-shell.adoc rename to modules/ROOT/pages/cypher-shell.adoc index 322651de0..dfb0cbf9f 100644 --- a/modules/ROOT/pages/tools/cypher-shell.adoc +++ b/modules/ROOT/pages/cypher-shell.adoc @@ -18,18 +18,13 @@ Alternatively, you can download it from link:https://neo4j.com/deployment-center The syntax for running Cypher Shell is: ---- - cypher-shell [-h] [-a ADDRESS] - [-u USERNAME] [--impersonate IMPERSONATE] - [-p PASSWORD] [--encryption {true,false,default}] - [-d DATABASE] [--access-mode {read,write}] - [--format {auto,verbose,plain}] - [-P PARAM] [--non-interactive] [--sample-rows SAMPLE-ROWS] - [--wrap {true,false}] [-v] [--driver-version] - [-f FILE] [--change-password] [--log [LOG-FILE]] - [--history HISTORY-BEHAVIOUR] - [--notifications] [--fail-fast | --fail-at-end] - [--idle-timeout IDLE-TIMEOUT] - [cypher] +cypher-shell [-h] [-a ADDRESS] [-u USERNAME] [--impersonate IMPERSONATE] [-p PASSWORD] + [--encryption {true,false,default}] [-d DATABASE] [--access-mode {read,write}] + [--enable-autocompletions] [--format {auto,verbose,plain}] [-P PARAM] + [--non-interactive] [--sample-rows SAMPLE-ROWS] [--wrap {true,false}] [-v] + [--driver-version] [-f FILE] [--change-password] [--log [LOG-FILE]] + [--history HISTORY-BEHAVIOUR] [--notifications] [--idle-timeout IDLE-TIMEOUT] + [--error-format {gql,legacy,stacktrace}] [--fail-fast | --fail-at-end] [cypher] ---- == Positional arguments @@ -63,18 +58,18 @@ The syntax for running Cypher Shell is: | Exit and report failures at the end of the input when reading from a file. | -| --enable-autocompletions -| Whether to enable Cypher autocompletions inside the CLI, which are disabled by default. -| +|--enable-autocompletions +|Whether to enable Cypher autocompletions inside the CLI. Completions can only be enabled for neo4j 5 and later. +|false |--format {auto,verbose,plain} |Desired output format. Displays the results in tabular format if you use the shell interactively and with minimal formatting if you use it for scripting. + -`verbose` displays results in a tabular format and prints statistics. + +`verbose` displays results in tabular format and prints statistics. + `plain` displays data with minimal formatting. |auto |-P PARAM, --param PARAM -|Add a parameter to this session. Example: `-P {a: 1}`, `-P '{a: 1, b: duration({seconds: 1})}'`, or using arrow syntax `-P 'a => 1'`. This argument can be specified multiple times. +|Add a parameter to this session. Example: `-P '{a: 1}'` or `-P '{a: 1, b: duration({seconds: 1})}'`. This argument can be specified multiple times. |[] |--non-interactive @@ -82,11 +77,11 @@ The syntax for running Cypher Shell is: |false |--sample-rows SAMPLE-ROWS -|Number of rows sampled to compute table widths (only for format=VERBOSE) +|Number of rows sampled to compute table widths (only for format=VERBOSE). |1000 |--wrap {true,false} -|Wrap table column values if the column is too narrow (only for format=VERBOSE). +|Wrap table column values if column is too narrow (only for format=VERBOSE). |true |-v, --version @@ -110,19 +105,23 @@ After executing all statements, Cypher Shell shuts down. |Enable logging to the specified file, or standard error if the file is omitted. | -|--history [HISTORY-BEHAVIOUR] -|File path of query and command history file or `in-memory` for in-memory history. -Defaults to /.neo4j/.cypher_shell_history. -It can also be set using the environmental variable NEO4J_CYPHER_SHELL_HISTORY. +|--history HISTORY-BEHAVIOUR +|File path of a query and a command history file or `in-memory` for in-memory history. +If the option is omitted, history is saved to `/.neo4j/.cypher_shell_history`. +Can also be set using the environment variable `NEO4J_CYPHER_SHELL_HISTORY`. | |--notifications -|Enable query notifications in interactive mode. +|Enable notifications in interactive mode. |false |--idle-timeout IDLE-TIMEOUT |Closes the application after the specified amount of idle time in interactive mode. You can specify the duration using the format `hms`, for example `1h` (1 hour), `1h30m` (1 hour 30 minutes), or `30m` (30 minutes). |disable + +|--error-format {gql,legacy,stacktrace} +|Controls how errors are displayed. +|gql label:new[Changed in 2025.06] |=== == Connection arguments @@ -151,10 +150,10 @@ Can also be specified using the environment variable `NEO4J_ADDRESS` or `NEO4J_U | | --encryption {true,false,default} -| Whether the connection to Neo4j should be encrypted. This must be consistent with Neo4j's configuration. If choosing `default`, the encryption setting is deduced from the specified address. For example, the `neo4j+ssc` protocol uses encryption. +| Whether the connection to Neo4j should be encrypted. This must be consistent with the Neo4j's configuration. If choosing 'default', the encryption setting is deduced from the specified address. For example, the 'neo4j+ssc' protocol uses encryption. | default -| -d DATABASE --database DATABASE +| -d DATABASE, --database DATABASE | Database to connect to. Can also be specified using the environment variable NEO4J_DATABASE. | diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc index 6fcf82c0a..deec79436 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc @@ -4,16 +4,17 @@ = Managing database aliases in composite databases Both local and remote database aliases can be created as part of a composite database. +Starting with Neo4j 2025.04, a database alias can also be set as the default database for a composite database. //// [source, cypher, role=test-setup] ---- -CREATE DATABASE `sci-fi-books`; -CREATE COMPOSITE DATABASE `library`; -CREATE ALIAS `library`.`sci-fi` FOR DATABASE `sci-fi-books`; -CREATE ALIAS `library`.`romance` FOR DATABASE `romance-books` AT 'neo4j+s://location:7687' USER alice PASSWORD 'password'; -CREATE COMPOSITE DATABASE garden; -CREATE DATABASE `perennial-flowers`; +CYPHER 25 CREATE DATABASE `sci-fi-books`; +CYPHER 25 CREATE COMPOSITE DATABASE `library`; +CYPHER 25 CREATE ALIAS `library.sci-fi` FOR DATABASE `sci-fi-books`; +CYPHER 25 CREATE ALIAS `library.romance` FOR DATABASE `romance-books` AT 'neo4j+s://location:7687' USER alice PASSWORD 'password'; +CYPHER 25 CREATE COMPOSITE DATABASE garden; +CYPHER 25 CREATE DATABASE `perennial-flowers`; ---- //// @@ -51,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. @@ -213,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`++`. @@ -235,7 +382,7 @@ 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: @@ -243,10 +390,10 @@ When not quoted individually, a database alias with the full name `my alias with .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. @@ -256,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`. @@ -276,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. @@ -297,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. @@ -319,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. @@ -328,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`. @@ -347,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 diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index 4efac4a30..a3f38143f 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -8,6 +8,7 @@ A local database alias can only target a database within the same DBMS. A remote database alias may target a database from another Neo4j DBMS. 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. Local and remote database aliases can also be created as part of a xref:database-administration/composite-databases/concepts.adoc[composite database]. @@ -398,14 +399,14 @@ If `ssl_enforced` is set to true, a secure URL scheme is enforced. This will be validated when the command is executed. * connection_timeout -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.connect_timeout[dbms.routing.driver.connection.connect_timeout] * connection_max_lifetime -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.max_lifetime[dbms.routing.driver.connection.max_lifetime]. -* connection_pool_acquisition_timeout -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection_pool_acquisition_timeout[dbms.routing.driver.connection_pool_acquisition_timeout]. -* connection_pool_idle_test -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection_pool_idle_test[dbms.routing.driver.connection_pool_idle_test]. +* connection_pool_acquisition_timeout -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.pool.acquisition_timeout[dbms.routing.driver.connection.pool.acquisition_timeout]. +* connection_pool_idle_test -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.pool.idle_test[dbms.routing.driver.connection.pool.idle_test]. * connection_pool_max_size -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.pool.max_size[dbms.routing.driver.connection.pool.max_size]. * logging_level (For details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.logging.level[dbms.routing.driver.logging.level]) -The driver settings are set in the `DRIVER` clause of the `CREATE ALIAS` or `ALTER ALIAS commands. +The driver settings are set in the `DRIVER` clause of the `CREATE ALIAS` or `ALTER ALIAS` commands. For example, the following query creates a remote database alias using driver settings `connection_timeout` and -`connection_pool_max_size` for connecting to the remote database `northwind-graph-2020: +`connection_pool_max_size` for connecting to the remote database `northwind-graph-2020`: .Query [source, cypher] diff --git a/modules/ROOT/pages/database-administration/aliases/naming-aliases.adoc b/modules/ROOT/pages/database-administration/aliases/naming-aliases.adoc index 55dc9c987..8eaf26010 100644 --- a/modules/ROOT/pages/database-administration/aliases/naming-aliases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/naming-aliases.adoc @@ -10,9 +10,10 @@ The following naming rules apply: * A name is a valid identifier. * Name length can be up to 65534 characters. * Names cannot end with dots. -* Unquoted dots signify that the database alias belongs to a composite database, separating the composite database name and the alias name. * Names that begin with an underscore or with the prefix `system` are reserved for internal use. * Non-alphabetic characters, including numbers, symbols, dots, and whitespace characters, can be used in names, but must be quoted using backticks. +* Dots (`.`) are interpreted as a delimiter between composite database and constituent alias name if a matching composite database exists. +Otherwise, Neo4j will fall back to interpreting the dot as simply part of the database name. The name restrictions and escaping rules apply to all the different database alias commands. diff --git a/modules/ROOT/pages/database-administration/composite-databases/concepts.adoc b/modules/ROOT/pages/database-administration/composite-databases/concepts.adoc index 47649db08..20806234e 100644 --- a/modules/ROOT/pages/database-administration/composite-databases/concepts.adoc +++ b/modules/ROOT/pages/database-administration/composite-databases/concepts.adoc @@ -58,5 +58,5 @@ image::federation-sharding.png[title="Data federation and sharding", width=450, [TIP] ==== -For a step-by-step tutorial on setting up and using a Composite database with federated and sharded data, see xref:tutorial/tutorial-composite-database.adoc[Set up and use a Composite database]. +For a step-by-step tutorial on setting up and using a Composite database with federated and sharded data, see xref:tutorial/tutorial-composite-database.adoc[Tutorials -> Setting up and using a composite database]. ==== \ No newline at end of file diff --git a/modules/ROOT/pages/database-administration/composite-databases/create-composite-databases.adoc b/modules/ROOT/pages/database-administration/composite-databases/create-composite-databases.adoc index 881b5841a..444ee6614 100644 --- a/modules/ROOT/pages/database-administration/composite-databases/create-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/composite-databases/create-composite-databases.adoc @@ -55,7 +55,7 @@ SHOW DATABASES +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- -For a full description of the columns returned by this command, and how to sort the results by specific columns, see xref:database-administration/standard-databases/listing-databases.adoc#manage-databases-listing-databases[Managing databases]. +For a full description of the columns returned by this command, and how to sort the results by specific columns, see xref:database-administration/standard-databases/listing-databases.adoc[List databases]. To create database aliases in the composite database, give the composite database as a namespace for the alias. For information about creating aliases in composite databases, see xref:database-administration/aliases/manage-aliases-composite-databases.adoc#create-composite-database-alias[Managing aliases in composite databases]. diff --git a/modules/ROOT/pages/database-administration/composite-databases/list-composite-databases.adoc b/modules/ROOT/pages/database-administration/composite-databases/list-composite-databases.adoc index 6ae295bdc..5ecbd26c8 100644 --- a/modules/ROOT/pages/database-administration/composite-databases/list-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/composite-databases/list-composite-databases.adoc @@ -6,9 +6,9 @@ //// [source, cypher, role=test-setup] ---- -CREATE COMPOSITE DATABASE `library`; -CREATE DATABASE `sci-fi`; -CREATE ALIAS `library`.`sci-fi` FOR DATABASE `sci-fi`; +CYPHER 25 CREATE COMPOSITE DATABASE `library`; +CYPHER 25 CREATE DATABASE `sci-fi`; +CYPHER 25 CREATE ALIAS `library.sci-fi` FOR DATABASE `sci-fi`; ---- //// @@ -33,7 +33,7 @@ SHOW DATABASES +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- -For a description of all the returned columns of this command, ways in which the `SHOW DATABASE` command can be filtered, and details about the privileges required for the command, see xref:database-administration/standard-databases/listing-databases.adoc#manage-databases-list[List standard databases]. +For a description of all the returned columns of this command, ways in which the `SHOW DATABASE` command can be filtered, and details about the privileges required for the command, see xref:database-administration/standard-databases/listing-databases.adoc[List standard databases]. For composite databases, the `constituents` column is particularly interesting as it lists the aliases that make up the composite database. diff --git a/modules/ROOT/pages/database-administration/composite-databases/querying-composite-databases.adoc b/modules/ROOT/pages/database-administration/composite-databases/querying-composite-databases.adoc index 644147635..8d73cbb74 100644 --- a/modules/ROOT/pages/database-administration/composite-databases/querying-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/composite-databases/querying-composite-databases.adoc @@ -14,6 +14,10 @@ The examples featured in this section make use of the two Cypher clauses: link:{ The following set-up is required to recreate the examples on this page: +[.tabbed-example] +==== +[role=include-with-cypher-5] +===== .Create a standard database `movies2022` [source, cypher] ---- @@ -42,6 +46,40 @@ CREATE ALIAS `cineasts`.`upcoming` USER neo4j PASSWORD 'password' ---- +===== +[role=include-with-cypher-25 label--new-2025.06] +===== +.Create a standard database `movies2022` +[source, cypher] +---- +CREATE DATABASE movies2022 +---- + +.Create a composite database `cineasts` +[source, cypher] +---- +CREATE COMPOSITE DATABASE cineasts +---- + +.Create database alias `cineasts.latest` for a local database in a composite database +[source, cypher] +---- +CREATE ALIAS `cineasts.latest` + FOR DATABASE movies2022 +---- + +.Create database alias `cineasts.upcoming` for a remote database in a composite database +[source, cypher] +---- +CREATE ALIAS `cineasts.upcoming` + FOR DATABASE upcoming + AT 'neo4j+s://location:7687' + USER neo4j + PASSWORD 'password' +---- +===== +==== + For more information about composite databases and database aliases in composite databases, see xref:database-administration/composite-databases/concepts.adoc[], and xref:database-administration/aliases/manage-aliases-composite-databases.adoc[]. @@ -113,7 +151,7 @@ In this case, once selecting `cineasts.latest`, and once selecting `cineasts.upc [[composite-databases-queries-listing-graphs]] === Listing graphs -The built-in function link:{neo4j-docs-base-uri}/cypher-manual/current/functions/query-functions#functions-graph-names[`graph.names()`] returns a list containing the names of all constituent graphs on the current Composite database. +The built-in function link:{neo4j-docs-base-uri}/cypher-manual/current/functions/#header-query-functions-graph[`graph.names()`] returns a list containing the names of all constituent graphs on the current Composite database. .The `graph.names()` function ==== @@ -316,7 +354,7 @@ RETURN m When a query is submitted to a Composite database, different parts of the query may run using different runtimes. Clauses or expressions in scopes where no graph has been specified run using the _slotted_ runtime. -Parts of the query directed to different constituent graphs are run using the default runtime for that graph, or respect the submitted link:{neo4j-docs-base-uri}/cypher-manual/current/query-tuning/query-options/#cypher-runtime[Cypher query options] if specified. +Parts of the query directed to different constituent graphs are run using the default runtime for that graph, or respect the submitted link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/query-tuning/#_query_options[Cypher query options] if specified. [[composite-databases-queries-built-in-functions]] == Built-in graph functions diff --git a/modules/ROOT/pages/database-administration/queries.adoc b/modules/ROOT/pages/database-administration/queries.adoc index b1fbf7cda..8339bd12d 100644 --- a/modules/ROOT/pages/database-administration/queries.adoc +++ b/modules/ROOT/pages/database-administration/queries.adoc @@ -4,7 +4,7 @@ [NOTE] ==== -All commands and example queries in this section are run in xref:tools/cypher-shell.adoc[the Neo4j Cypher Shell command-line interface (CLI)]. +All commands and example queries in this section are run in xref:cypher-shell.adoc[]. Note that the `cypher-shell` queries are not case-sensitive, but must end with a semicolon. ==== diff --git a/modules/ROOT/pages/database-administration/standard-databases/alter-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/alter-databases.adoc index 21e31bc55..d5e186a0a 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/alter-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/alter-databases.adoc @@ -107,6 +107,7 @@ For more information, see xref::clustering/databases.adoc#alter-topology[Managin The `ALTER DATABASE` command can be used to set or remove specific options for a database. +.Available options [options="header", cols="1m,1m,3a"] |=== | Key @@ -116,12 +117,13 @@ The `ALTER DATABASE` command can be used to set or remove specific options for a | txLogEnrichment | FULL\|DIFF\|OFF | Defines the level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes. -For details about enrichment mode, see link:{neo4j-docs-base-uri}/cdc/{page-version}/get-started/self-managed/#set-enrichment-mode/[Change Data Capture Manual -> Set the enrichment mode]. +For details about enrichment mode, see link:https://neo4j.com/docs/cdc/current/get-started/self-managed/#_modify_a_databases_cdc_mode[Change Data Capture Manual -> Modify a database’s CDC mode]. |=== [NOTE] ==== -There are no available `OPTIONS` values for composite databases. +The `ALTER DATABASE` command cannot be used to modify the store format of a database. +For details about how to change the store format of a database, see xref::database-internals/store-formats.adoc#change-store-format[Changing the store format of existing databases]. ==== === Modify the options set for a database diff --git a/modules/ROOT/pages/database-administration/standard-databases/create-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/create-databases.adoc index fa6115fcf..f53943852 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/create-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/create-databases.adoc @@ -91,25 +91,25 @@ Replaced by `existingDataSeedServer`. | URI to a backup or a dump from an existing database. | Defines an identical seed from an external source which will be used to seed all servers. +For more information, see xref::database-administration/standard-databases/seed-from-uri.adoc[Seed from a URI]. | `seedConfig` | Comma-separated list of configuration values. | -For more information see xref::clustering/databases.adoc#cluster-seed-uri[Seed from URI]. | `seedCredentials` label:deprecated[Deprecated in 5.26] | credentials | Defines credentials that need to be passed into certain seed providers. It is recommended to use the `CloudSeedProvider` seed provider, which does not require this configuration when seeding from cloud storage. -For more information see xref::clustering/databases.adoc#cloud-seed-provider[CloudSeedProvider]. +For more information see xref::database-administration/standard-databases/seed-from-uri.adoc#cloud-seed-provider[CloudSeedProvider]. | `txLogEnrichment` | `FULL` \| `DIFF` \| `OFF` | Defines the level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes. -For details about enrichment mode, see link:{neo4j-docs-base-uri}/cdc/current/get-started/self-managed/#set-enrichment-mode/[Change Data Capture Manual -> Enable CDC on self-managed instances -> Set the enrichment mode]. +For details about enrichment mode, see link:https://neo4j.com/docs/cdc/current/get-started/self-managed/#_modify_a_databases_cdc_mode[Change Data Capture Manual -> Enable CDC on self-managed instances -> Modify a database’s CDC mode]. | `storeFormat` | `aligned` \| `standard` \| `high_limit` \| `block` diff --git a/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc index 76f60adf8..7eef2427f 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc @@ -86,7 +86,7 @@ DROP DATABASE movies DUMP DATA ---- In Neo4j, dumps can be stored in the directory specified by the xref:configuration/configuration-settings.adoc#config_server.directories.dumps.root[`server.directories.dumps.root`] setting (by default, the path for storing dumps is xref:configuration/file-locations.adoc#data[`/data/dumps`]). -You can use dumps to create databases through the xref:clustering/databases.adoc#cluster-seed-uri[Seed from URI approach]. +You can use dumps to create databases using the xref::database-administration/standard-databases/seed-from-uri.adoc[seed from a URI] approach. The option `DESTROY DATA` explicitly requests the default behavior of the command. diff --git a/modules/ROOT/pages/database-administration/standard-databases/listing-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/listing-databases.adoc index b55f58fe6..c1670a6ec 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/listing-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/listing-databases.adoc @@ -1,5 +1,5 @@ :description: how to list databases in Neo4j, use SHOW DATABASES command, see all available databases, databases states. How to filter listed databases in Neo4j. -[[manage-databases-list]] + = List databases You can list your databases using the Cypher command `SHOW DATABASES`. @@ -35,13 +35,13 @@ Depending on what you want to see, you can list: * All databases. * A particular database. -* The default database. +* The DBMS default database. * The home database. These commands return the following columns: .Listing databases output -[options="header", width="100%", cols="4m,6a,2m"] +[options="header", width="100%", cols="3m,6,2m"] |=== | Column | Description | Type @@ -81,6 +81,8 @@ The default for a standalone database is `neo4j://localhost:7687`. label:default | role | The current role of the database (`primary`, `secondary`, `unknown`). label:default-output[] + +The value for composite databases is `NULL` because it does not apply to them. | STRING | writer @@ -93,7 +95,7 @@ The value can be either `online` or `offline`. label:default-output[] | STRING | currentStatus -| The actual status of the database. label:default-output[] +a| The actual status of the database. label:default-output[] The possible statuses are: @@ -117,34 +119,42 @@ See <> for more information. | default | -Show if this is the default database for the DBMS. label:default-output[] +`true` if this is the default database for the DBMS. label:default-output[] Not returned by `SHOW HOME DATABASE` or `SHOW DEFAULT DATABASE`. | BOOLEAN | home | -Shown if this is the home database for the current user. label:default-output[] +`true` if this is the home database for the current user. label:default-output[] Not returned by `SHOW HOME DATABASE` or `SHOW DEFAULT DATABASE`. | BOOLEAN | `currentPrimariesCount` | Number of primaries for this database reported as running currently. It is the same as the number of rows where `role=primary` and `name=this database`. + +The value for composite databases is `NULL` because it does not apply to them.footnote:compositeDb[This change applies to versions 2025.04 and later and 5.26.5 and later.] | INTEGER | `currentSecondariesCount` | Number of secondaries for this database reported as running currently. It is the same as the number of rows where `role=secondary` and `name=this database`. + +The value for composite databases is `NULL` because it does not apply to them.footnote:compositeDb[] | INTEGER | `requestedPrimariesCount` | The requested number of primaries for this database. May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. + +The value for composite databases is `NULL` because it does not apply to them. | INTEGER | `requestedSecondariesCount` | The requested number of secondaries for this database. May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. + +The value for composite databases is `NULL` because it does not apply to them. | INTEGER | creationTime @@ -160,17 +170,15 @@ May be lower than current if the DBMS is currently reducing the number of copies | ZONED DATETIME | store -a| +| Information about the storage engine and the store format. -The value is a string formatted as: +The value is a string formatted as `{storage engine}-{store format}-{major version}.{minor version}`. -[source, syntax, role="noheader"] ----- -{storage engine}-{store format}-{major version}.{minor version} ----- A database must be `online` or `deallocating` for this value to be available. For other database states the value will be `NULL`. + +The value for composite databases is `NULL` because it does not apply to them.footnote:compositeDb[] | STRING | lastCommittedTxn @@ -195,6 +203,8 @@ For other database states the value will be `NULL`. |options |The map of options applied to the database. + +The value for composite databases is `NULL` because it does not apply to them. | MAP |=== diff --git a/modules/ROOT/pages/tools/neo4j-admin/migrate-database.adoc b/modules/ROOT/pages/database-administration/standard-databases/migrate-database.adoc similarity index 88% rename from modules/ROOT/pages/tools/neo4j-admin/migrate-database.adoc rename to modules/ROOT/pages/database-administration/standard-databases/migrate-database.adoc index 4d869e3d6..bf0386a85 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/migrate-database.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/migrate-database.adoc @@ -19,8 +19,8 @@ The `neo4j-admin database migrate` has the following syntax: ---- neo4j-admin database migrate [-h] [--expand-commands] [--force-btree-indexes-to-range] - [--verbose] - [--additional-config=] [--pagecache=] + [--verbose] [--additional-config=] + [--max-off-heap-memory=] [--pagecache=] [--to-format=standard|high_limit|aligned|block] ---- @@ -46,16 +46,19 @@ The `neo4j-admin database migrate` command is run only on a stopped database. The `neo4j-admin database migrate` command has the following options: .`neo4j-admin database migrate` options -[options="header", cols="5m,6a"] +[options="header", cols="5m,6a,1m"] |=== | Option | Description +| Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. +| |--expand-commands |Allow command expansion in config value evaluation. +| |--force-btree-indexes-to-range |Special option for automatically turning all BTREE indexes/constraints into RANGE. Be aware that RANGE indexes are not always the optimal replacement of BTREEs and performance may be affected while the new indexes are populated. @@ -63,19 +66,31 @@ See the Neo4j v5 migration guide online for more information. The newly created indexes will be populated in the background on the first database start up following the migration and users should monitor the successful completion of that process. [NOTE] This option is only relevant when migrating from Neo4j 4.4. +| + |-h, --help |Show this help message and exit. +| + +|--max-off-heap-memory= label:new[Introduced in Neo4j 2025.04] +|Maximum memory that neo4j-admin can use for various data structures and caching to improve performance. +Values can be plain numbers, such as 10000000, or 20G for 20 gigabytes. +It can also be specified as a percentage of the available memory, for example 70%. +|90% -|--pagecache= +|--pagecache= label:deprecated[Deprecated in Neo4j 2025.04] |The size of the page cache to use for the migration process. The general rule is that values up to the size of the database proportionally increase performance. +| |--to-format=standard\|high_limit\|aligned\|block |Name of the format to migrate the store to. If the format is specified, the target database is migrated to the latest known combination of `MAJOR` and `MINOR` versions of the specified format. If not specified, the tool migrates the target database to the latest known combination of `MAJOR` and `MINOR` versions of the current format. +| |--verbose |Enable verbose output. +| |=== [NOTE] diff --git a/modules/ROOT/pages/database-administration/standard-databases/naming-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/naming-databases.adoc index ad8e51745..eaea62a61 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/naming-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/naming-databases.adoc @@ -20,9 +20,7 @@ Support for database names starting with a numeric character is available from N The `-` (dash) and `.` (dot) characters are not legal in Cypher variables. Names containing a `-` or that begin with a numeric character must be enclosed within backticks. For example, `CREATE DATABASE ++`main-db`++` is a valid database name. -Database names are the only identifier for which dots do not need to be quoted. -For example `main.db` is a valid database name. -However, this behavior is deprecated due to the difficulty of determining if a dot is part of the database name or a delimiter for a database alias in a composite database. +Using dots in database names is not recommended, as it makes it difficult to determine if a dot is part of the database name or a delimiter for a database alias in a composite database. ==== It is possible to create an alias to refer to an existing database to avoid these restrictions. diff --git a/modules/ROOT/pages/database-administration/standard-databases/recreate-database.adoc b/modules/ROOT/pages/database-administration/standard-databases/recreate-database.adoc new file mode 100644 index 000000000..d2f79da1c --- /dev/null +++ b/modules/ROOT/pages/database-administration/standard-databases/recreate-database.adoc @@ -0,0 +1,218 @@ +:description: How to recreate your database in Neo4j. +[role=enterprise-edition] + += Recreate a database + +== The recreate procedure + +The recreate procedure allows you to: + +* Change the database store to a specified backup, while keeping all the associated privileges for the database. + +* Make your database write-available again after it has been lost (for example, due to a disaster). +See xref:clustering/disaster-recovery.adoc[Disaster recovery] for more information. + +* label:new[Introduced in 2025.02] Delete the data and schema for a database, while keeping the database privileges assigned to each role. + +* label:new[Introduced in 2025.04] Alter the database store format when clearing the data and schema. + +[CAUTION] +==== +The recreate procedure works only for real user databases and not for composite databases, or the `system` database. + +Remember that the recreate procedure results in downtime while the stores get updated. +The time is unbounded and may depend on different factors -- for example, the size of the store, network speed, etc. +==== + +In Neo4j 2025.04, the xref:procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] procedure is deprecated in favor of xref:procedures.adoc#procedure_dbms_recreateDatabase[`dbms.recreateDatabase()`]. + +=== Syntax + +[source, shell] +---- +dbms.recreateDatabase(database :: STRING, options = {} :: MAP) +---- + +Input arguments are the database name and list of the seeding and topology options used for recreating a database. + +.Seeding and topology options of the recreate procedure +[cols="2a,4",frame="topbot",options="header"] +|=== +|Option +|Description + +|seedingServers +|A list of possible seeding servers. +You can define available servers or provide an empty list. +For details, see <>. + +|seedURI +|External source specified by URI. + +|clearData label:new[Introduced in 2025.02] +|Allows you to delete the data and schema for a database, while keeping the database privileges assigned to each role. + +|storeFormat label:new[Introduced in 2025.04] +|Allows you to change the database store format when clearing the data and schema. + +|primaries +|Number of primary allocations for the recreated database. +If you set number of primaries without secondaries, then secondaries is set to `0`. +For more details, see <>. + +|secondaries +|Number of secondary allocations for the recreated database. +You cannot set secondaries without primaries. + +|=== + +=== Prerequisites and considerations + +The database in question can be in an `online` or `offline` state when it is recreated, but a successful operation starts the database regardless of its previous state. + +If your database has Change Data Capture (CDC) enabled, the CDC chain will stop when the database is recreated, even though CDC remains enabled in the recreated database. +To restore CDC functionality, follow the guide on how link:https://neo4j.com/docs/cdc/current/existing-databases/[to initialize CDC applications from an existing database]. + +Before recreating a database, any eventual quarantined states need to be addressed. +For more information, see xref:database-administration/standard-databases/errors.adoc#quarantine[Standard databases -> Error handling]. + +You need xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[the `CREATE DATABASE` and `DROP DATABASE` privileges] to run the recreate procedure. + +Additionally, in a cluster deployment, you have the option to modify <> during the recreation process. + +However, note that the store format (up to Neo4j 2025.04), access, and enrichment cannot be altered during recreation. +Starting with 2025.04, the store format can only be altered if the `clearData` option is used. + +To check if the recreation is successful, use the `SHOW DATABASES` command and verify that all allocations have been started. + +[[recreate-seeding-options]] +== Seeding options + +The store to be used during the recreation of a database can be defined in different ways. +One method uses a backup, while others use available allocations in the cluster. + +You can use either <> or <> to specify the source from which the database should be recreated. + +* If you define neither, an error is thrown. + +* If you define both of them, then `seedingServers` must be an empty list. +See <> for more details. + +* If `seedingServers` is not empty and `seedURI` is also defined, an error will occur. + +[[uri-seed]] +=== Use a backup as a seed + +If you provide a URI to a backup or a dump, the stores on all allocations will be replaced by the backup or the dump at the given URI. +The new allocations can be put on any `ENABLED` server in the cluster. +See xref::database-administration/standard-databases/seed-from-uri.adoc[Seed from URI] for more details. + + +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {seedURI: "s3://myBucket/myBackup.backup"}); +---- + +[[seed-servers]] +=== Use available servers as a seed + +After the recreation is complete, the database will have the latest data store from the seeding servers. + +[CAUTION] +==== +Recreation is based on available remaining stores or specific stores explicitly defined by the user. +Stores that are lost or not explicitly specified are excluded from the recreation process. +Therefore, if the excluded stores contained more recent data than those used, data loss may occur. +==== + +[[specified-servers]] +Specified servers:: + +You can specify a set of available servers. +The stores on all allocations will be synchronized to the most up-to-date store from the defined servers. +The number of defined servers cannot exceed the number of total allocations in the desired topology. ++ +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {seedingServers: ["serverId1", "serverId2", "serverId3"]}); +---- + +[[undefined-servers]] +Undefined servers:: + +If you provide an empty list of seeding servers and do not specify a `seedURI`, Neo4j will select all allocations of the database (primaries and secondaries) on currently enabled and non-cordoned servers to act as seeders. ++ +Before running the procedure, ensure that all unavailable servers are xref:clustering/servers.adoc#_cordoned_state[cordoned]; otherwise, the procedure will fail. ++ +To determine where the database is allocated, use the `SHOW DATABASES` command. +To identify all enabled and available servers hosting the required database, run the `SHOW SERVERS` command. +Servers have to show `health = Available` and `status = Enabled`. +Cordon all unreachable servers by running the `dbms.cluster.cordonServer()` procedure. ++ +Then Neo4j will select the most up-to-date seeder available in the cluster to recreate the database. ++ +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {seedingServers: []}); +---- + + +[[undefined-servers-backup]] +Undefined servers with fallback backup:: + +If both an empty list of seeding servers and a `seedURI` are provided, Neo4j finds all allocations of the database and use those as seeders. +Unavailable servers must be cordoned. ++ +However, if no available servers can be found, the database is recreated based on the backup or the dump specified by the URI. +This means the store is replaced by the most up-to-date seeder if available; otherwise, the backup is used. ++ +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {seedingServers: [], seedURI: "s3://myBucket/myBackup.backup"}); +---- + + +[[alter-topology-recreate]] +== Change the topology + +In a cluster deployment, there is an option to define a new topology when recreating a database. +This can be beneficial during a disaster, if enough servers are not available to recreate the database with the original topology. +When altering the total number of allocations down during a recreation, it is important to remember that the number of seeding servers cannot exceed the number of total allocations of the database. +This also holds true when using recreate with an empty list of seeders. +If there are more available servers in the cluster hosting the database than the number of new allocations, the recreation will fail. + +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {seedingServers: [], primaries: 3, secondaries: 0}); +---- + + +[role=label--new-2025.02] +[[clear-data-recreate]] +== Clear data option + +In Neo4j 2025.02, the `clearData` option was added to the recreate procedure. +This option allows you to delete the data (e.g., nodes and relationships) and the schema (e.g., constraints and indexes) for the database. +This means you end up with an empty store, but as with the other recreate database options, all privileges associated with the database are kept. + +[CAUTION] +==== +Using the clear data option means the data and schema will be deleted *permanently*. +If you want to have the option of getting them back later, make sure to take a backup before clearing the database. +See xref:backup-restore/online-backup.adoc[Online backup] for more information. +==== + +[role=label--new-2025.04] +[[alter-store-format]] +=== Alter the database store format + +In Neo4j 2025.04, the database store format can also be altered during recreation, but only when the `clearData` option is specified. + +See xref:database-internals/store-formats.adoc[Store formats], for more details about available database store formats in Neo4j. +If the store format option is not defined, the recreated database ends up with the same store format as before the recreation. + +[source, shell] +---- +CALL dbms.recreateDatabase("neo4j", {clearData: true, storeFormat: "block"}); +---- + diff --git a/modules/ROOT/pages/database-administration/standard-databases/seed-from-uri.adoc b/modules/ROOT/pages/database-administration/standard-databases/seed-from-uri.adoc new file mode 100644 index 000000000..2337b74d5 --- /dev/null +++ b/modules/ROOT/pages/database-administration/standard-databases/seed-from-uri.adoc @@ -0,0 +1,235 @@ +:page-role: enterprise-edition +:description: How to create a database using a seed from URI. + +[[database-seed-uri]] += Create a database from a URI + +This method seeds all databases with an identical seed from an external source, specified by a URI. + +You specify the seed URI as an argument of the `CREATE DATABASE` command: + +[source, cypher, role="noplay"] +---- +CREATE DATABASE foo OPTIONS {existingData: 'use', seedURI:'s3://myBucket/myBackup.backup'} +---- + +Download and validation of the seed is only performed as the new database is started. +If it fails, the database is not available and it has the `statusMessage`: `Unable to start database` of the `SHOW DATABASES` command. + +[source, cypher, role="noplay"] +---- +neo4j@neo4j> SHOW DATABASES; ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "seed3" | "standard" | [] | "read-write" | "localhost:7682" | "unknown" | FALSE | "online" | "offline" | "Unable to start database `DatabaseId{3fe1a59b[seed3]}`" | FALSE | FALSE | [] | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +---- + +To determine the cause of the problem, it is recommended to look at the `debug.log`. + +[NOTE] +==== +Starting from Neo4j 2025.01, seed from URI can also be used in combination with xref:database-administration/standard-databases/create-databases.adoc[`CREATE OR REPLACE DATABASE`]. +==== + +[[neo4j-seed-providers]] +== Seed providers in Neo4j + +The seed can either be a full backup, a differential backup (see <>), or a dump from an existing database. +The sources of seeds are called _seed providers_. + +The mechanism is pluggable, allowing new sources of seeds to be supported (see link:https://www.neo4j.com/docs/java-reference/current/extending-neo4j/project-setup/#extending-neo4j-plugin-seed-provider[Java Reference -> Implement custom seed providers] for more information). + +The product has built-in support for seed from a mounted file system (file), FTP server, HTTP/HTTPS server, Amazon S3, Google Cloud Storage, and Azure Cloud Storage. + +[NOTE] +==== +Amazon S3, Google Cloud Storage, and Azure Cloud Storage are supported by default, but the other providers require configuration of xref:configuration/configuration-settings.adoc#config_dbms.databases.seed_from_uri_providers[`dbms.databases.seed_from_uri_providers`]. +==== + +[[file-seed-provider]] +=== FileSeedProvider + +The `FileSeedProvider` supports: + +** `file:` + +[[url-connection-seed-provider]] +=== URLConnectionSeedProvider + +The `URLConnectionSeedProvider` supports the following: + +** `ftp:` +** `http:` +** `https:` + +Starting from Neo4j 2025.01, the `URLConnectionSeedProvider` does not support `file`. +// This is true for both Cypher 5 and Cypher 25. + +[[cloud-seed-provider]] +=== CloudSeedProvider + +The `CloudSeedProvider` supports: + +** `s3:` +** `gs:` +** `azb:` + +The `CloudSeedProvider` supports using xref:backup-restore/modes.adoc#differential-backup[differential backup] files as seeds. +With the provided differential backup file, the `CloudSeedProvider` searches the directory containing differential backup files for a xref:backup-restore/online-backup.adoc#backup-chain[backup chain] ending at the specified differential backup, and then seeds using this backup chain. + +[.tabbed-example] +===== +[role=include-with-AWS-S3] +====== + +include::partial$/aws-s3-overrides.adoc[] + +include::partial$/aws-s3-credentials.adoc[] + +. Create database from `myBackup.backup`. ++ +[source,shell, role="nocopy"] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup' } +---- + +====== +[role=include-with-Google-cloud-storage] +====== + +include::partial$/gcs-credentials.adoc[] + +. Create database from `myBackup.backup`. ++ +[source,shell] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'gs://myBucket/myBackup.backup' } +---- +====== +[role=include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Create database from `myBackup.backup`. ++ +[source,shell] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'azb://myStorageAccount/myContainer/myBackup.backup' } +---- +====== +===== + + +[role=label--deprecated] +[[s3-seed-provider]] +=== S3SeedProvider + +// When Cypher 25 is released, we have to label this section 'Cypher 5' as this functionality is only available in Cypher 5. + +The `S3SeedProvider` supports: + +** `s3:` label:deprecated[Deprecated in 5.26] + + +[NOTE] +==== +Neo4j comes bundled with necessary libraries for AWS S3 connectivity. +Therefore, if you use `S3SeedProvider`,`aws cli` is not required but can be used with the `CloudSeedProvider`. +==== + +The `S3SeedProvider` requires additional configuration. +This is specified with the `seedConfig` option. +This option expects a comma-separated list of configurations. +Each configuration value is specified as a name followed by `=` and the value, as such: + +[source, cypher, role="noplay"] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1' } +---- + +`S3SeedProvider` also requires passing in credentials. +These are specified with the `seedCredentials` option. +Seed credentials are securely passed from the Cypher command to each server hosting the database. +For this to work, Neo4j on each server in the cluster must be configured with identical keystores. +This is identical to the configuration required by remote aliases, see xref:database-administration/aliases/remote-database-alias-configuration.adoc#remote-alias-config-DBMS_admin-A[Configuration of DBMS with remote database alias]. +If this configuration is not performed, the `seedCredentials` option fails. + +[source, cypher, role="noplay"] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1', seedCredentials: [accessKey];[secretKey] } +---- +Where `accessKey` and `secretKey` are provided by AWS. + +=== Seed provider reference + +[cols="1,2,2",options="header"] +|=== +| URL scheme +| Seed provider +| URI example + +| `file:` +| `FileSeedProvider` +| `\file:///tmp/backup1.backup` + +| `ftp:` +| `URLConnectionSeedProvider` +| `\ftp://myftp.com/backups/backup1.backup` + +| `http:` +| `URLConnectionSeedProvider` +| `\http://myhttp.com/backups/backup1.backup` + +| `https:` +| `URLConnectionSeedProvider` +| `\https://myhttp.com/backups/backup1.backup` + +| `s3:` +| `S3SeedProvider` label:deprecated[Deprecated in 5.26], + +`CloudSeedProvider` +| `s3://mybucket/backups/backup1.backup` + +| `gs:` +| `CloudSeedProvider` +| `gs://mybucket/backups/backup1.backup` + +| `azb:` +| `CloudSeedProvider` +| `azb://mystorageaccount.blob/backupscontainer/backup1.backup` +|=== + + +[[seed-restore-until-option]] +== Support for seeding up to a date or a transaction ID + +Starting from Neo4j 2025.01, when creating a database you can seed up to a specific date or transaction ID via the `seedRestoreUntil` option. + +The `seedRestoreUntil` option is supported by the `CloudSeedProvider` and the `FileSeedProvider`. + + +Seed up to a specific date:: + +To seed up to a specific date, you need to pass the differential backup, which contains the data up to that date. ++ +[source,shell] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: datetime("2019-06-01T18:40:32.142+0100") } +---- ++ +This will seed the database with transactions committed before the provided timestamp. + + +Seed up to a specific transaction ID:: + +To seed up to a specific transaction ID, you need to pass the differential backup that contains the data up to that transaction ID. ++ +[source,shell] +---- +CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: 123 } +---- ++ +This will seed the database with transactions up to, but not including transaction 123. + diff --git a/modules/ROOT/pages/tools/neo4j-admin/upload-to-aura.adoc b/modules/ROOT/pages/database-administration/standard-databases/upload-to-aura.adoc similarity index 95% rename from modules/ROOT/pages/tools/neo4j-admin/upload-to-aura.adoc rename to modules/ROOT/pages/database-administration/standard-databases/upload-to-aura.adoc index 6fd6abe8d..e5780200e 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/upload-to-aura.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/upload-to-aura.adoc @@ -72,7 +72,7 @@ The `neo4j-admin database upload` command has the following options: | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | @@ -139,7 +139,7 @@ Otherwise, the command aborts and throws an error. [CAUTION] ==== This command does not currently support https://neo4j.com/docs/aura/platform/security/secure-connections/#_vpc_isolation[private linking]. -Please https://aura.support.neo4j.com/hc/en-us/requests/new[raise a support ticket] if you have public traffic disabled and need to use this command. +Please https://support.neo4j.com/s/[raise a support ticket] if you have public traffic disabled and need to use this command. ==== [source, shell,role=nocopy] diff --git a/modules/ROOT/pages/database-internals/concurrent-data-access.adoc b/modules/ROOT/pages/database-internals/concurrent-data-access.adoc index be1c3e96e..d2c129c71 100644 --- a/modules/ROOT/pages/database-internals/concurrent-data-access.adoc +++ b/modules/ROOT/pages/database-internals/concurrent-data-access.adoc @@ -25,41 +25,51 @@ All the anomalies listed here can only occur with the read-committed isolation l In Cypher, it is possible to acquire write locks to simulate improved isolation in some cases. Consider the case where multiple concurrent Cypher queries increment the value of a property. Due to the limitations of the _read-committed isolation level_, the increments might not result in a deterministic final value. -If there is a direct dependency, Cypher automatically acquires a write lock before reading. -A direct dependency is when the right-hand side of `SET` has a dependent property read in the expression or the value of a key-value pair in a literal map. -For example, if you run the following query by one hundred concurrent clients, it is very likely not to increment the property `n.prop` to 100, unless a write lock is acquired before reading the property value. -This is because all queries read the value of `n.prop` within their own transaction, and cannot see the incremented value from any other transaction that has not yet been committed. -In the worst-case scenario, the final value would be as low as 1 if all threads perform the read before any has committed their transaction. +Cypher automatically acquires write locks in some cases, but not in others. +When a Cypher query uses the `SET` clause to update a property, it may or may not acquire a write lock on the node or relationship being updated, depending on whether there is a direct dependency on the property being read. -.Cypher can acquire a write lock -==== -The following example requires a write lock, and Cypher automatically acquires one: +==== Acquiring a write lock automatically +When a Cypher query has a direct dependency on the property being read, Cypher automatically acquires a write lock before reading the property. +This is the case when the query uses the `SET` clause to update a property on a node or relationship, and the right-hand side of the `SET` clause has a dependency on the property being read. +For example, in the following queries, the right-hand side of `SET` has a dependent property read in an expression or a value of a key-value pair in a literal map. + +.Incrementing a property using an expression +==== [source, cypher, role="noheader"] ---- MATCH (n:Example {id: 42}) SET n.prop = n.prop + 1 ---- +This query increments the property `n.prop` by 1. +In this case, Cypher automatically acquires a write lock on the node `n` before reading the value of `n.prop`. +This ensures that no other concurrent queries can modify the node `n` while this query is running, thus preventing lost updates. ==== -.Cypher can acquire a write lock +.Incrementing a property using a map literal ==== -This example also requires a write lock, and Cypher automatically acquires one: - [source, cypher, role="noheader"] ---- MATCH (n) SET n += {prop: n.prop + 1} ---- + +This query also increments the property `n.prop` by 1, but it does so using a map literal. +In this case, Cypher also acquires a write lock on the node `n` before reading the value of `n.prop`. ==== -Due to the complexity of determining such a dependency in the general case, Cypher does not cover any of the following example cases: +==== No direct dependency to acquire a write lock -.Complex Cypher -==== -Variable depending on results from reading the property in an earlier statement: +When a query does not have a direct dependency on the property being read, Cypher does not automatically acquire a write lock. +This means if you run multiple concurrent queries that read and write the same property, it is possible to end up with lost updates by allowing other concurrent queries to modify the property value at the same time. +For example, if you run the following queries by one hundred concurrent clients, it is very likely not to increment the property `n.prop` to 100, unless a write lock is acquired before reading the property value. +This is because all queries read the value of `n.prop` within their own transaction, and cannot see the incremented value from any other transaction that has not yet been committed. +In the worst-case scenario, the final value would be as low as 1 if all threads perform the read before any has committed their transaction. + +.Variable depending on results from reading the property in an earlier statement +==== [source, cypher, role="noheader"] ---- MATCH (n) @@ -69,10 +79,8 @@ SET n.prop = k + 1 ---- ==== -.Complex Cypher +.Circular dependency between properties read and written in the same query ==== -Circular dependency between properties read and written in the same query: - [source, cypher, role="noheader"] ---- MATCH (n) @@ -80,36 +88,36 @@ SET n += {propA: n.propB + 1, propB: n.propA + 1} ---- ==== +Workaround:: To ensure deterministic behavior also in the more complex cases, it is necessary to explicitly acquire a write lock on the node in question. In Cypher there is no explicit support for this, but it is possible to work around this limitation by writing to a temporary property. - -.Explicitly acquire a write lock +For example, the following query acquires a write lock for the node by writing to a *dummy* property (`n._dummy_`) before reading the requested value (`n.prop`). +When acquired, the write lock ensures that no other concurrent queries can modify the node until the transaction is committed or rolled back. +The dummy property is used only to acquire the write lock, therefore, it can be removed immediately after the lock is acquired. ++ +.Dummy property to acquire a write lock ==== -This example acquires a write lock for the node by writing to a dummy property before reading the requested value: - [source, cypher, role="noheader"] ---- MATCH (n:Example {id: 42}) -SET n._LOCK_ = true +SET n._dummy_ = true +REMOVE n._dummy_ WITH n.prop AS p // ... operations depending on p, producing k SET n.prop = k + 1 -REMOVE n._LOCK_ ---- ==== -The existence of the `+SET n._LOCK_+` statement before the read of the `n.prop` read ensures the lock is acquired before the read action, and no updates are lost due to enforced serialization of all concurrent queries on that specific node. - === Non-repeatable reads A non-repeatable read is when the same transaction reads the same data but gets inconsistent results. This can easily happen if reading the same data twice in a query and the data gets modified in-between by another concurrent query. -.Non-repeatable read -==== -The following example query shows that reading the same property twice can give inconsistent results. +For example, the following query shows that reading the same property twice can give inconsistent results. If there are other queries running concurrently, it is not guaranteed that `p1` and `p2` have the same value. +.Non-repeatable read +==== [source, cypher, role="noheader"] ---- MATCH (n:Example {id: 42}) @@ -132,17 +140,17 @@ Similarly, the entity may not appear at all if the property is changed to a prev This anomaly can only occur with operators that scan an index, or parts of an index, for example link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/operators/operators-detail/#query-plan-node-index-scan[`NodeIndexScan`] or link:{neo4j-docs-base-uri}/cypher-manual/current/planning-and-tuning/operators/operators-detail/#query-plan-directed-relationship-index-seek-by-range[`DirectedRelationshipIndexSeekByRange`]. -.Missing and double read -==== In the following query, each node `n` that has the property `prop` is expected to appear exactly once. However, concurrent updates that modify the `prop` property during index scanning may cause a node to appear multiple times or not at all in the result set. + +.Missing and double read +==== [source, cypher, role="noheader"] ---- MATCH (n:Example) WHERE n.prop IS NOT NULL RETURN n ---- ==== - == Locks When a write transaction occurs, Neo4j takes locks to preserve data consistency while updating. @@ -279,15 +287,13 @@ Setting `db.lock.acquisition.timeout` to `0` -- which is the default value -- di This feature cannot be set dynamically. -.Configure lock acquisition timeout +.Set the timeout to ten seconds ==== -Set the timeout to ten seconds. [source, parameters] ---- db.lock.acquisition.timeout=10s ---- ==== - [[deadlocks]] == Deadlocks @@ -319,6 +325,7 @@ Other code that requires synchronization should be synchronized in such a way th For example, running the following two queries in https://neo4j.com/docs/operations-manual/current/tools/cypher-shell/[Cypher-shell] at the same time will result in a deadlock because they are attempting to modify the same node properties concurrently: .Transaction A +==== [source, cypher, indent=0, role=nocopy noplay] ---- :begin @@ -327,8 +334,9 @@ WITH collect(n) as nodes CALL apoc.util.sleep(5000) MATCH (m:Test2) SET m.prop = 1; ---- - +==== .Transaction B +==== [source, cypher, indent=0, role=nocopy noplay] ---- :begin @@ -347,6 +355,8 @@ The transaction will be rolled back and terminated. Error: ForsetiClient[transac Client[6697] waits for [ForsetiClient[transactionId=6698, clientId=1]]] ---- +==== + [NOTE] ==== The Cypher clause `MERGE` takes locks out of order to ensure the uniqueness of the data, and this may prevent Neo4j's internal sorting operations from ordering transactions in a way that avoids deadlocks. diff --git a/modules/ROOT/pages/database-internals/index.adoc b/modules/ROOT/pages/database-internals/index.adoc index 1655c7102..69581e104 100644 --- a/modules/ROOT/pages/database-internals/index.adoc +++ b/modules/ROOT/pages/database-internals/index.adoc @@ -25,6 +25,8 @@ The following sections describe the transactional behavior in detail and how to * xref:database-internals/transaction-logs.adoc[] * xref:database-internals/checkpointing.adoc[] * xref:database-internals/store-formats.adoc[] +* xref:database-internals/neo4j-admin-store-info.adoc[] + [NOTE] ==== diff --git a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-store-info.adoc b/modules/ROOT/pages/database-internals/neo4j-admin-store-info.adoc similarity index 60% rename from modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-store-info.adoc rename to modules/ROOT/pages/database-internals/neo4j-admin-store-info.adoc index 4e6f89db0..68eb0e919 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-store-info.adoc +++ b/modules/ROOT/pages/database-internals/neo4j-admin-store-info.adoc @@ -53,7 +53,7 @@ The `neo4j-admin database info` command has the following options: | Description | Default -|--additional-config=footnote:[See xref:tools/neo4j-admin/index.adoc#_configuration[Tools -> Configuration] for details.] +|--additional-config=footnote:[See xref:neo4j-admin-neo4j-cli.adoc#_configuration[Neo4j Admin and Neo4j CLI -> Configuration] for details.] |Configuration file with additional configuration. | @@ -81,45 +81,59 @@ The `neo4j-admin database info` command has the following options: == Examples +The following examples show how to use the `neo4j-admin database info` command to display information about a database and its store format. +All examples assume that the Neo4j server is Enterprise Edition and that the database is offline. + .Invoke `neo4j-admin database info` against a database store ==== [source, shell] ---- -bin/neo4j-admin database info mygraph.db +bin/neo4j-admin database info healthcare ---- -Output: - +.Output +[results] ---- -Store format version: record-aligned-1.1 -Store format introduced in: 5.0.0 +Database name: healthcare +Database in use: false +Store format version: block-block-1.1 +Store format introduced in: 5.14.0 +Last committed transaction id:29 +Store needs recovery: false ---- ==== [role=enterprise-edition] .Invoke `neo4j-admin database info` against all databases ==== -The command can also be invoked against all databases, as follows: - -`neo4j-admin database info --from-path=` - [source, shell] ---- -bin/neo4j-admin database info data/databases +bin/neo4j-admin database info --from-path=../data/databases ---- -Output: - +.Output +[results] ---- -Database name: foo -Database in use: false -Store format version: record-aligned-1.1 -Store format introduced in: 5.0.0 -Last committed transaction id:2 -Store needs recovery: true - -Database name: bar -Database in use: true +Database name: healthcare +Database in use: false +Store format version: block-block-1.1 +Store format introduced in: 5.14.0 +Last committed transaction id:29 +Store needs recovery: false + +Database name: neo4j +Database in use: false +Store format version: block-block-1.1 +Store format introduced in: 5.14.0 +Last committed transaction id:27 +Store needs recovery: false + +Database name: system +Database in use: false +Store format version: record-aligned-1.1 +Store format introduced in: 5.0.0 +Last committed transaction id:213 +Store needs recovery: false ---- ==== @@ -133,22 +147,17 @@ When the command is invoked against several databases, if some are *online* they .Invoke `neo4j-admin database info` against a database and output JSON ==== -If you are parsing the results of this command you may use the `--format=json` option to receive the output as JSON. +If you are parsing the results of this command, you may use the `--format=json` option to receive the output as JSON. All the same fields are included and all values are strings. [source, shell] ---- -bin/neo4j-admin database info --from-path data/databases --format=json foo +bin/neo4j-admin database info --from-path ../data/databases --format=json foo ---- -Output: - +.Output +[results] ---- -{"databaseName":"foo", -"inUse":"false", -"storeFormat”:"record-aligned-1.1", -"storeFormatIntroduced”:"5.0.0", -"lastCommittedTransaction":"2", -"recoveryRequired":"true"} +{"databaseName":"healthcare","inUse":"false","storeFormat":"block-block-1.1","storeFormatIntroduced":"5.14.0","storeFormatSuperseded":null,"lastCommittedTransaction":"29","recoveryRequired":"false"} ---- ==== \ No newline at end of file diff --git a/modules/ROOT/pages/database-internals/store-formats.adoc b/modules/ROOT/pages/database-internals/store-formats.adoc index cc1adcea0..1491a2c4f 100644 --- a/modules/ROOT/pages/database-internals/store-formats.adoc +++ b/modules/ROOT/pages/database-internals/store-formats.adoc @@ -14,7 +14,7 @@ For more information on the deprecation and timeline for the eventual removal of [NOTE] ==== -For information on store formats in Neo4j 4.4, see link:https://neo4j.com/docs/operations-manual/4.4/tools/neo4j-admin/neo4j-admin-store-info/[Tools -> Neo4j Admin -> Display store information]. +For information on store formats in Neo4j 4.4, see link:https://neo4j.com/docs/operations-manual/4.4/tools/neo4j-admin/neo4j-admin-store-info/[Neo4j Admin and Neo4j CLI -> Neo4j Admin -> Display store information]. ==== [[store-format-overview]] @@ -23,7 +23,7 @@ For information on store formats in Neo4j 4.4, see link:https://neo4j.com/docs/o Here’s an overview of the available formats and their features: Block:: label:enterprise-edition[]+ -* Default format unless xref:configuration/configuration-settings.adoc##config_db.format[`db.format`] is specified. +* Default format unless xref:configuration/configuration-settings.adoc#config_db.format[`db.format`] is specified. * *Performance:* Fast queries; uses advanced data structures and inlining techniques for better data locality. * *Memory efficiency:* Optimized collocation of data, which allows more related data to be fetched by fewer read operations; enhancing resource utilization. Block format means a few pages need to be loaded to serve a query, i.e. fewer page faults and less IO. @@ -94,7 +94,7 @@ You can either set the store format when creating a new database or change the s `block` is the default format for all newly-created databases as long as they do not have the xref:configuration/configuration-settings.adoc#config_db.format[`db.format`] setting specified. + If you want to change it, you can set a new value for the xref:configuration/configuration-settings.adoc#config_db.format[`db.format`] configuration in the _neo4j.conf_ file. + -You can also create a new database on a specific store format by passing the new format as an argument to the command creating the database, for example, xref:tools/neo4j-admin/neo4j-admin-import.adoc#import-tool-full[`neo4j-admin database import full`] or xref:backup-restore/copy-database.adoc[`neo4j-admin database copy`] commands, or by using `storeFormat:` option in the Cypher command `CREATE DATABASE`. +You can also create a new database on a specific store format by passing the new format as an argument to the command creating the database, for example, xref:import.adoc#import-tool-full[`neo4j-admin database import full`] or xref:backup-restore/copy-database.adoc[`neo4j-admin database copy`] commands, or by using `storeFormat:` option in the Cypher command `CREATE DATABASE`. The following examples show how to create a new database on the `block` store format. However, the same applies to other formats. @@ -160,7 +160,7 @@ The following steps assume that you want to migrate the database called `mydb` t . Stop the database using the Cypher command `STOP DATABASE mydb`. . Change the store format of the stopped database using *one* of the following options: -* Migrate an existing database using xref:tools/neo4j-admin/migrate-database.adoc[`neo4j-admin database migrate`] command. +* Migrate an existing database using xref:database-administration/standard-databases/migrate-database.adoc[`neo4j-admin database migrate`] command. + [IMPORTANT] ==== @@ -280,7 +280,7 @@ SHOW DATABASES YIELD name, store ---- Additionally, you can use the `neo4j-admin database info` command to get detailed information about the store format of a database. -For details, see xref:tools/neo4j-admin/neo4j-admin-store-info.adoc[Display store information]. +For details, see xref:database-internals/neo4j-admin-store-info.adoc[Display store information]. [[store-formats-entity-limits]] == Store formats and entity limits diff --git a/modules/ROOT/pages/database-internals/transaction-logs.adoc b/modules/ROOT/pages/database-internals/transaction-logs.adoc index c21696754..e35afec7e 100644 --- a/modules/ROOT/pages/database-internals/transaction-logs.adoc +++ b/modules/ROOT/pages/database-internals/transaction-logs.adoc @@ -77,7 +77,7 @@ Old transaction logs cannot be safely archived or removed by external jobs since + Log pruning is called only after checkpoint completion to ensure at least one checkpoint and points to a valid place in the transaction log data. In reality, this means that all transaction logs created between checkpoints are kept for some time, and only after a checkpoint, the pruning strategy removes them. -For more details on how to speed up checkpointing, see xref:database-internals/checkpointing.adoc#transaction-logging-log-pruning[Configure log pruning]. +For more details on how to speed up checkpointing, see xref:database-internals/checkpointing.adoc#control-log-pruning[Control transaction log pruning]. To force a checkpoint, run the procedure xref:procedures.adoc#procedure_db_checkpoint[`CALL db.checkpoint()`]. + [NOTE] diff --git a/modules/ROOT/pages/database-internals/transaction-management.adoc b/modules/ROOT/pages/database-internals/transaction-management.adoc index 750b4cddd..6f39d9a4d 100644 --- a/modules/ROOT/pages/database-internals/transaction-management.adoc +++ b/modules/ROOT/pages/database-internals/transaction-management.adoc @@ -54,8 +54,7 @@ db.transaction.timeout=10s ==== Configuring transaction timeout does not affect transactions executed with custom timeouts (e.g., via the Java API or Neo4j Drivers), as the custom timeout overrides the value set for `db.transaction.timeout`. -Note that the timeout value can only be overridden to a value smaller than that configured by `db.transaction.timeout`. -You can set the transaction timeout to any value, even larger than configured by `db.transaction.timeout`. +Custom timeouts can be set to any value, even larger than configured by `db.transaction.timeout`. == Manage transactions @@ -63,4 +62,4 @@ You can set the transaction timeout to any value, even larger than configured by Transactions can be managed using the Cypher commands `SHOW TRANSACTIONS` and `TERMINATE TRANSACTIONS`. The `TERMINATE TRANSACTIONS` command can be combined with multiple `SHOW TRANSACTIONS` and `TERMINATE TRANSACTIONS` commands in the same query. -For more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/transaction-clauses/[Cypher manual -> Transaction commands]. \ No newline at end of file +For more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/transaction-clauses/[Cypher manual -> Transaction commands]. diff --git a/modules/ROOT/pages/docker/clustering.adoc b/modules/ROOT/pages/docker/clustering.adoc index 80484fac8..fffc9ea2e 100644 --- a/modules/ROOT/pages/docker/clustering.adoc +++ b/modules/ROOT/pages/docker/clustering.adoc @@ -3,9 +3,9 @@ [[docker-cc]] = Deploy a Neo4j cluster on multiple Docker hosts -Neo4j supports clustering in a containerized environment without an orchestration tool. -This section describes how to use Docker to set up a cluster across multiple machines. -For a tutorial on how to set up a cluster locally for testing purposes, see xref:tutorial/tutorial-clustering-docker.adoc[Deploy a Neo4j cluster in a Docker container]. +Neo4j supports clustering in a containerized environment without an orchestration tool. +This section describes how to use Docker to set up a cluster across multiple machines. +For a tutorial on how to set up a cluster locally for testing purposes, see xref:tutorial/tutorial-clustering-docker.adoc[Tutorials -> Deploying a Neo4j cluster in a Docker container]. [NOTE] ==== @@ -33,9 +33,9 @@ docker run --name=server1 --detach \ --publish=6000:6000 --publish=7000:7000 \ --hostname=public-address \ --env NEO4J_dbms_cluster_endpoints=server1-public-address:6000,server2-public-address:6000,server3-public-address:6000 \ - --env NEO4J_server_cluster_advertised_address=public-address:6000 \ - --env NEO4J_server_cluster.raft.advertised_address=public-address:7000 \ - --env NEO4J_server_default_advertised_address=public-address \ + --env NEO4J_server_cluster_advertised__address=public-address:6000 \ + --env NEO4J_server_cluster.raft.advertised__address=public-address:7000 \ + --env NEO4J_server_default_advertised__address=public-address \ --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ --env NEO4J_server_bolt_advertised__address=public-address:7687 \ --env NEO4J_server_http_advertised__address=public-address:7474 \ diff --git a/modules/ROOT/pages/docker/docker-compose-standalone.adoc b/modules/ROOT/pages/docker/docker-compose-standalone.adoc index ff464448a..24da7a205 100644 --- a/modules/ROOT/pages/docker/docker-compose-standalone.adoc +++ b/modules/ROOT/pages/docker/docker-compose-standalone.adoc @@ -13,7 +13,7 @@ For more information, see the https://docs.docker.com/compose/install/[Install D . Create a project folder where you will store your _docker-compose.yml_ file and run your Neo4j server. . Prepare your _docker-compose.yml_ file using the following example. -For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification]. +For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file[Docker Compose specification]. + .Example of a _docker-compose.yml_ file [source,yaml,subs="attributes+,+macros"] @@ -60,7 +60,7 @@ You can instead store your credentials in files and use them in your _docker-com neo4j/your_password ---- . Prepare your _docker-compose.yml_ file using the following example. -For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification]. +For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file[Docker Compose specification]. + .Example of a _docker-compose.yml_ file [source,yaml,subs="attributes+,+macros"] diff --git a/modules/ROOT/pages/docker/dump-load.adoc b/modules/ROOT/pages/docker/dump-load.adoc index 2784f82c9..ffb7c9df5 100644 --- a/modules/ROOT/pages/docker/dump-load.adoc +++ b/modules/ROOT/pages/docker/dump-load.adoc @@ -48,6 +48,6 @@ docker run --interactive --tty --rm \ ==== [NOTE] -For more information on the `neo4j-admin database dump and load` syntax and options, see xref:backup-restore/offline-backup.adoc#offline-backup-command-options[`neo4j-admin database dump`] and xref:backup-restore/restore-dump.adoc#restore-dump-command[`neo4j-admin database load`]. + -For more information on managing volumes, see https://docs.docker.com/storage/volumes/[the official Docker documentation^]. +For more information on the `neo4j-admin database dump and load` syntax and options, see xref:backup-restore/offline-backup.adoc#offline-backup-command-options[`neo4j-admin database dump`] and xref:backup-restore/restore-dump.adoc[`neo4j-admin database load`]. + +For more information on managing volumes, see https://docs.docker.com/storage/volumes/[the official Docker documentation]. ==== diff --git a/modules/ROOT/pages/docker/introduction.adoc b/modules/ROOT/pages/docker/introduction.adoc index 23e4ef7f5..86f33c4e1 100644 --- a/modules/ROOT/pages/docker/introduction.adoc +++ b/modules/ROOT/pages/docker/introduction.adoc @@ -94,7 +94,7 @@ docker run \ neo4j:{neo4j-version-exact} ---- -You can try out your Neo4j container by opening _http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser. +You can try out your Neo4j container by opening _\http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser. By default, Neo4j requires authentication and prompts you to log in with a username/password of `neo4j/neo4j` at the first connection. You are then prompted to set a new password. diff --git a/modules/ROOT/pages/docker/mounting-volumes.adoc b/modules/ROOT/pages/docker/mounting-volumes.adoc index 4bb6b4dcf..4a6643120 100644 --- a/modules/ROOT/pages/docker/mounting-volumes.adoc +++ b/modules/ROOT/pages/docker/mounting-volumes.adoc @@ -12,7 +12,7 @@ Storage can be mounted to a container in two ways: * A folder on the host file system. * A Docker volume -- a named storage location that is managed by Docker. -For instructions on _how_ to mount storage to a Docker container, refer to the official Docker documentation link:https://docs.docker.com/storage/bind-mounts/[Bind mounts^] and link:https://docs.docker.com/storage/volumes/[Volumes^]. +For instructions on _how_ to mount storage to a Docker container, refer to the official Docker documentation link:https://docs.docker.com/storage/bind-mounts/[Bind mounts] and link:https://docs.docker.com/storage/volumes/[Volumes]. Neo4j provides several mount points for storage to simplify using Neo4j in Docker. The following sections describe the mount points and how to use them. diff --git a/modules/ROOT/pages/docker/operations.adoc b/modules/ROOT/pages/docker/operations.adoc index 0bb51a825..1e5d3fb18 100644 --- a/modules/ROOT/pages/docker/operations.adoc +++ b/modules/ROOT/pages/docker/operations.adoc @@ -7,7 +7,7 @@ You can use the Neo4j tools when running Neo4j in a Docker container. [[docker-neo4j-admin]] == Use Neo4j Admin -The xref:tools/neo4j-admin/index.adoc[Neo4j Admin tool] can be run locally within a container using the following command: +The xref:neo4j-admin-neo4j-cli.adoc[`neo4j-admin` CLI] can be run locally within a container using the following command: [source, shell] ---- @@ -16,12 +16,12 @@ docker exec --interactive --tty neo4j-admin neo4j-admin database import incremental ---- -For more information about the commands' syntax and options, see xref:tools/neo4j-admin/neo4j-admin-import.adoc#import-tool-full[Full import] and xref:tools/neo4j-admin/neo4j-admin-import.adoc#import-tool-incremental[Incremental import]. +For more information about the commands' syntax and options, see xref:import.adoc#import-tool-full[Full import] and xref:import.adoc#import-tool-incremental[Incremental import]. [discrete] [[docker-import-prerequisites]] === Prerequisites * Verify that you have created the folders that you want to mount as volumes to the Neo4j docker container. -* Verify that the CSV files that you want to load into Neo4j are formatted as per xref:tools/neo4j-admin/neo4j-admin-import.adoc#import-tool-header-format[CSV header format]. +* Verify that the CSV files that you want to load into Neo4j are formatted as per xref:import.adoc#import-tool-header-format[CSV header format]. * Verify that you have added the CSV files to the folder that will be mounted to _/import_ in your container. [discrete] @@ -67,7 +67,7 @@ neo4j-admin database import full --nodes=Movies=/import/movies_header.csv,/impor [[docker-neo4j-memrec]] == Use Neo4j Admin for memory recommendations -The xref:tools/neo4j-admin/neo4j-admin-memrec.adoc[neo4j-admin server memory-recommendation] command with the argument `--docker` outputs environmental variables that can be passed to a Neo4j docker container. +The xref:configuration/neo4j-admin-memrec.adoc[neo4j-admin server memory-recommendation] command with the argument `--docker` outputs environmental variables that can be passed to a Neo4j docker container. The following example shows how `neo4j-admin server memory-recommendation --docker` provides a memory recommendation in a docker-friendly format. .Invoke `neo4j-admin server memory-recommendation --docker` @@ -96,7 +96,7 @@ NEO4J_server_jvm_additional='-XX:+ExitOnOutOfMemoryError' [[docker-neo4j-admin-report]] == Use Neo4j Admin report -The xref:tools/neo4j-admin/neo4j-admin-report.adoc[Neo4j Admin report tool] generates a report of the status of a running Neo4j database. + +The xref:monitoring/neo4j-admin-report.adoc[Neo4j Admin report tool] generates a report of the status of a running Neo4j database. + In a containerized environment, its command `neo4j-admin server report` must be invoked using the script `neo4j-admin-report`. This ensures that the reporter is running with all the necessary file permissions required to analyze the running Neo4j processes. This script takes all the arguments of the `neo4j-admin server report` command. @@ -142,14 +142,14 @@ The `$HOME/neo4j/reports` folder should now contain a zip file of reports. [[docker-cypher-shell]] == Use Cypher Shell -The xref:tools/cypher-shell.adoc[Neo4j Cypher Shell tool] can be run locally within a container using the following command: +The xref:cypher-shell.adoc[] can be run locally within a container using the following command: [source, shell] ---- docker exec --interactive --tty cypher-shell ---- -For more information about the `cypher-shell` syntax and options, see xref:tools/cypher-shell.adoc#cypher-shell-syntax[Syntax]. +For more information about the `cypher-shell` syntax and options, see xref:cypher-shell.adoc[]#cypher-shell-syntax[Syntax]. [[docker-cypher-shell-example]] === Retrieve data from a database in a Neo4j Docker container diff --git a/modules/ROOT/pages/docker/plugins.adoc b/modules/ROOT/pages/docker/plugins.adoc index decda2079..283f3f133 100644 --- a/modules/ROOT/pages/docker/plugins.adoc +++ b/modules/ROOT/pages/docker/plugins.adoc @@ -11,7 +11,7 @@ For instructions about plugins in general see xref:configuration/plugins.adoc[Co [[docker-plugins-procedures]] == Installing plugins -To install plugins, including link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/procedures#extending-neo4j-procedures[user-defined procedures], mount the folder or volume containing the plugin JARs to `/plugins`, for example: +To install plugins, including link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/procedures[user-defined procedures], mount the folder or volume containing the plugin JARs to `/plugins`, for example: [source, shell, subs="attributes"] ---- diff --git a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc b/modules/ROOT/pages/import.adoc similarity index 92% rename from modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc rename to modules/ROOT/pages/import.adoc index 275f6a36a..67deec253 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc +++ b/modules/ROOT/pages/import.adoc @@ -5,7 +5,7 @@ :rfc-4180: https://tools.ietf.org/html/rfc4180 `neo4j-admin database import` writes CSV data into Neo4j's native file format as fast as possible. + -Starting with version 5.26, Neo4j also provides support for the Parquet file format. +It also provides support for the Parquet file format. You should use this tool when: @@ -25,7 +25,7 @@ See link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/load-csv/[Cypher Ma [NOTE] ==== Change Data Capture does **not** capture any data changes resulting from the use of `neo4j-admin database import`. -See link:{neo4j-docs-base-uri}/cdc/current/get-started/self-managed/#non-tx-log-changes/[Change Data Capture -> Key considerations] for more information. +See link:{neo4j-docs-base-uri}/cdc/current/get-started/self-managed/#non-tx-log-changes[Change Data Capture -> Key considerations] for more information. ==== == Overview @@ -46,7 +46,7 @@ This section describes the `neo4j-admin database import` option. [TIP] ==== For information on `LOAD CSV`, see the link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/load-csv[Cypher Manual -> `LOAD CSV`]. -For in-depth examples of using the command `neo4j-admin database import`, refer to the xref:tutorial/neo4j-admin-import.adoc[Tutorials -> Neo4j Admin import]. +For in-depth examples of using the command `neo4j-admin database import`, refer to the xref:tutorial/neo4j-admin-import.adoc[Tutorials -> Importing data]. ==== These are some things you need to keep in mind when creating your input files: @@ -93,8 +93,8 @@ neo4j-admin database import full [-h] [--expand-commands] [--verbose] [--auto-sk [--format=] [--high-parallel-io=on|off|auto] [--id-type=string|integer|actual] [--input-encoding=] [--input-type=csv|parquet] [--max-off-heap-memory=] [--quote=] [--read-buffer-size=] - [--report-file=] [--schema=] [--threads=] --nodes=[