Skip to content

Clarify migration paths between store formats #2687

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: 5.x
Choose a base branch
from
+42 −10
Open

Clarify migration paths between store formats #2687

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d143470
Clarify migration paths between store formats
NataliaIvakina Oct 28, 2025
5e56822
some additions
NataliaIvakina Oct 28, 2025
de43428
further additions
NataliaIvakina Oct 29, 2025
de17c45
Apply suggestions from code review
NataliaIvakina Oct 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 20 additions & 10 deletions modules/ROOT/pages/database-internals/store-formats.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ Neo4j's storage engine supports several store formats that describe how data is
Starting from 5.23, `block` format is the recommended format for Enterprise Edition due to its superior performance and scalability.
`block` format uses advanced data structures and inlining techniques to enhance data locality, which leads to better resource utilization.

`aligned` is the recommended format for Community Edition.
`aligned` is the default format for Community Edition starting with Neo4j 5.0.
Copy link
Collaborator Author

@NataliaIvakina NataliaIvakina Oct 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It's unclear in which version the aligned format became the default in CE. This is an an assumption.
In the section 'Available store formats' further down, we say that aligned is default in CE but we don't specify from which version.


`standard` and `high_limit` formats are deprecated starting from Neo4j 5.23.
It is not recommended to use these formats for new databases.
It is not recommended to use these formats for new databases or to migrate to them.
For more information on the deprecation and timeline for the eventual removal of these formats, see <<format-deprecations, Format deprecations>>.

[NOTE]
Expand All @@ -33,6 +33,9 @@ Supports the highest limits at the time of writing.
See <<block-format-limits, Block format entity limits>> for details. +
label:new[Introduced in 5.25] Supports token names (including label, property key, and relationship type names) of any length up to the GQL identifier max length of 16,383 characters.
* *Future-proofing:* Designed to be extended and improved without requiring store migrations. New features such as data types, or performance enhancements are available without rewriting the store.
* *Supported migration paths to other store formats:* Although it is not recommended, you can change your store format from `block` to `aligned`, `high_limit`, or `standard`.
Note that `high_limit` and `standard` formats are deprecated.
The `aligned` format has lower limits than `block`, so your graph must fit within those reduced limits.

Aligned::
* Default format in Community Edition and for all new databases in Enterprise Edition prior to Neo4j 5.22.
Expand All @@ -41,13 +44,8 @@ Aligned::
* *Property access:* Stores graph data in linked list-like structures on disk.
* *Entity limits:* Supports graphs within some limits.
See <<aligned-limits, Aligned format entity limits>> for details.

Standard:: label:deprecated[Deprecated in 5.23]
* *Performance:* Basic, foundational format.
* *Property access:* Stores graph data in linked list-like structures on disk.
* *Entity limits:* Supports graphs within some limits.
See <<standard-limits, Standard format entity limits>> for details.
* For information on deprecation and eventual removal, see <<format-deprecations, Format deprecations>>.
* *Supported migration paths to other store formats:* You can change your store format from `aligned` to `block` or `high_limit`.
Note that the `high_limit` format is deprecated, therefore, it is not recommended to migrate to it.

High_limit:: label:enterprise-edition[] label:deprecated[Deprecated in 5.23]
* *Performance:* Performs slightly worse than `standard` and requires more disk space, but allows more nodes and relationships.
Expand All @@ -56,6 +54,16 @@ High_limit:: label:enterprise-edition[] label:deprecated[Deprecated in 5.23]
* *Entity limits:* From the record formats, supports the highest limits at the time of writing.
For more information, see <<high-format-limits, High_limit format entity limits>>.
* For information on deprecation and eventual removal, see <<format-deprecations, Format deprecations>>.
* *Supported migration paths to other store formats:* You can migrate to the `block` format only.

Standard:: label:deprecated[Deprecated in 5.23]
* *Performance:* Basic, foundational format.
* *Property access:* Stores graph data in linked list-like structures on disk.
* *Entity limits:* Supports graphs within some limits.
See <<standard-limits, Standard format entity limits>> for details.
* For information on deprecation and eventual removal, see <<format-deprecations, Format deprecations>>.
* *Supported migration paths to other store formats:* You can change your store format from `standard` to `aligned`, `block`, or `high_limit`.
However, it is not recommended to migrate to the `high_limit` format as it is deprecated.

[[format-deprecations]]
== Format deprecations
Expand All @@ -81,7 +89,9 @@ The last version of Neo4j to include these formats will be an LTS release planne
+
. *How can I change the store format of my database?* +
For information on changing the store format of an existing database, see <<change-store-format, Changing the store format of existing databases>>.

+
. *From which store formats can I migrate, and to which formats?* +
For information about supported migration paths, refer to xref:tools/neo4j-admin/migrate-database.adoc#supported-migration-paths[Neo4j Admin -> Migrate a database].

[role="enterprise-edition"]
[[how-to-set-store-format]]
Expand Down
22 changes: 22 additions & 0 deletions modules/ROOT/pages/tools/neo4j-admin/migrate-database.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,28 @@ A migration to a higher `MAJOR` format version or another format is a manual act

The store format for new databases can be set with the xref:configuration/configuration-settings.adoc#config_db.format[`db.format`] configuration setting.

The below table shows supported migration paths between different Neo4j store formats.
However, the `standard` and `high_limit` store formats are deprecated starting with Neo4j 5.23, meaning that migration to these formats is not recommended from this version onward.

[[supported-migration-paths]]
.Migration paths between Neo4j store formats
[options="noheader"]
|===
.2+.>|*Store format* 4+^|*Migration paths*
^|To `block` ^|To `aligned` ^|To `high_limit` ^|To `standard`

|`block` footnote:1[The `block` format is the default in Enterprise Edition starting from Neo4j 5.22.] | |{check-mark} Not recommended |{check-mark} Not recommended |{check-mark} Not recommended

|`aligned` footnote:2[The `aligned` format is the default in Community Edition. In Enterprise Edition, it was default before Neo4j 5.22.] ^|{check-mark} | |{check-mark} Not recommended |

|`high_limit` footnote:3[label:enterprise[Enterprise Edition] The `high_limit` format is deprecated in 5.23.] ^|{check-mark} | | |

|`standard` footnote:4[label:community[Community Edition] The `standard` format is deprecated in 5.23.] ^|{check-mark} ^|{check-mark} |{check-mark} Not recommended |
|===

Before migrating from `block` to the `aligned` format, you have to ensure that your graph fits in the `aligned` since the `block` format has higher limits.
For details, see xref:database-internals/store-formats.adoc#store-formats-entity-limits[Database internals and transactional behavior -> Store formats].

== Syntax

The `neo4j-admin database migrate` has the following syntax:
Expand Down