dmagda commented on a change in pull request #8258:
URL: https://github.com/apache/ignite/pull/8258#discussion_r492204178
##########
File path: docs/_docs/persistence/snapshots.adoc
##########
@@ -131,15 +134,18 @@ include::{javaCodeDir}/Snapshots.java[tags=create,
indent=0]
== Restoring From Snapshot
Currently, the data restore procedure has to be performed manually. In a
nutshell, you need to stop the cluster,
-replace persistence data and other files with the data from the snapshot, and
restart the nodes. The detailed procedure
-looks as follows:
+replace persistence data and other files with the data from the snapshot, and
restart the nodes. Prior to performing
Review comment:
It feels like we are saying too much in the opening paragraph.
Basically, we're listing some or most of the restore steps that are covered
down below.
How about shortening the opening paragraph to a single sentence and listing
all the steps in the numbered-list below?
_"Currently, the data restore procedure has to be performed manually. Follow
these step to restore a cluster from a snapshot:
1) Stop the cluster you intend to restore
2)..
N)
"_
##########
File path: docs/_docs/persistence/snapshots.adoc
##########
@@ -131,15 +134,18 @@ include::{javaCodeDir}/Snapshots.java[tags=create,
indent=0]
== Restoring From Snapshot
Currently, the data restore procedure has to be performed manually. In a
nutshell, you need to stop the cluster,
-replace persistence data and other files with the data from the snapshot, and
restart the nodes. The detailed procedure
-looks as follows:
+replace persistence data and other files with the data from the snapshot, and
restart the nodes. Prior to performing
+restore steps do not forget to cleanup the Write-ahead and Checkpoint files
related to the current cluster. They may
+trigger unnecessary crash-recovery procedures when the cluster starts from a
snapshot.
+
+The detailed procedure looks as follows:
. Stop the cluster you intend to restore
. Do the following on each node:
- - Remove all the files and directories under the
`$IGNITE_HOME/work/{node_id}` directory. Clean the
+ - Remove all the files and directories related to the `{nodeId}` under
your `$IGNITE_HOME/work/` directory. Clean the
link:link:persistence/native-persistence#configuring-persistent-storage-directory[`db/{node_id}`]
directory separately if
it's not located under the Ignite `work` dir.
- - Copy the files of belonging to a node with the `{node_id}` from the
snapshot into the `$IGNITE_HOME/work/{node_id}` directory.
+ - Copy the files of belonging to a node with the `{node_id}` from the
snapshot into the `$IGNITE_HOME/work/` directory.
Review comment:
A grammar mistake introduced by me earlier:
"copy the files of belogning to a node" - remove the "of" preposition.
##########
File path: docs/_docs/persistence/snapshots.adoc
##########
@@ -160,27 +166,27 @@ the topology and wait while the data gets rebalanced and
indexes are rebuilt.
== Consistency Guarantees
All snapshots are fully consistent in terms of concurrent cluster-wide
operations as well as ongoing changes with Ignite
-Persistence and other files on nodes.
+Persistence and files on nodes.
The cluster-wide snapshot consistency is achieved by triggering the
link:https://cwiki.apache.org/confluence/display/IGNITE/%28Partition+Map%29+Exchange+-+under+the+hood[Partition-Map-Exchange]
procedure. By doing that, the cluster will eventually get to the point in time
when all previously started transactions are completed, and new
-ones are paused. Once this happens, the cluster initiates the snapshot
creation procedure.
+ones are paused. Once this happens, the cluster initiates the snapshot
creation procedure. Primary and backup cache partitions
Review comment:
The "cache" is redundant in the sentence. We can simply say primary and
backup partitions. Plus, some people work with SQL tables and this reference to
caches can cause confusion.
Consider this version, it fixes some misprints and addresses the point above:
Once this happens, the cluster initiates the snapshot creation procedure.
The PME procedure ensures that the snapshot includes primary and backup in a
consistent state.
##########
File path: docs/_docs/persistence/snapshots.adoc
##########
@@ -160,27 +166,27 @@ the topology and wait while the data gets rebalanced and
indexes are rebuilt.
== Consistency Guarantees
All snapshots are fully consistent in terms of concurrent cluster-wide
operations as well as ongoing changes with Ignite
-Persistence and other files on nodes.
+Persistence and files on nodes.
The cluster-wide snapshot consistency is achieved by triggering the
link:https://cwiki.apache.org/confluence/display/IGNITE/%28Partition+Map%29+Exchange+-+under+the+hood[Partition-Map-Exchange]
procedure. By doing that, the cluster will eventually get to the point in time
when all previously started transactions are completed, and new
-ones are paused. Once this happens, the cluster initiates the snapshot
creation procedure.
+ones are paused. Once this happens, the cluster initiates the snapshot
creation procedure. Primary and backup cache partitions
+will also be inclued and fully consistent in created snapshots since the PME
procedure also awaits transaction completion
+on backup cache partitions too.
-The consistency between the primary Ignite Persistence files and their
snapshot copies is achieved by copying the primary
+The consistency between the Ignite Persistence files and their snapshot copies
is achieved by copying the original
files to the destination snapshot directory with tracking all concurrent
ongoing changes. The tracking of the changes
-might require extra space on your storage media.
-
+might require extra space on the Ignite Persistence storage media (up to the
current size of it).
Review comment:
"up to the current size of it" - what is the "it"? Are you talking about
the size of the persistence files or the storage media as a whole? Please
clarify this in place.
##########
File path: docs/_docs/persistence/snapshots.adoc
##########
@@ -160,27 +166,27 @@ the topology and wait while the data gets rebalanced and
indexes are rebuilt.
== Consistency Guarantees
All snapshots are fully consistent in terms of concurrent cluster-wide
operations as well as ongoing changes with Ignite
-Persistence and other files on nodes.
+Persistence and files on nodes.
Review comment:
It's unclear what are those other "files". In my version, I wanted to
say that all the changes with Ignite Persistence and other files are to be
consistently recorded to a snapshot. The "other files" imply some other files
that unrelated to persistence and it's not that important to mention here.
In the current version, we have just "files" (without "other"). And we
either need to return "other" or be more specific listing the names of those
files.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
