persistence: update topic

Author: xuniq

doc/book/admin/backups.rst

@@ -37,15 +37,15 @@ that are made after the last snapshot are incremental backups. Therefore taking
 a backup is a matter of copying the snapshot and WAL files.
 
 1. Use ``tar`` to make a (possibly compressed) copy of the latest .snap and .xlog
-   files on the :ref:`memtx_dir <cfg_basic-memtx_dir>` and
-   :ref:`wal_dir <cfg_basic-wal_dir>` directories.
+   files on the :ref:`snapshot.dir <configuration_reference_snapshot_dir>` and
+   :ref:`wal.dir <configuration_reference_wal_dir>` directories.
 
 2. If there is a security policy, encrypt the .tar file.
 
 3. Copy the .tar file to a safe place.
 
 Later, restoring the database is a matter of taking the .tar file and putting
-its contents back in the ``memtx_dir`` and ``wal_dir`` directories.
+its contents back in the ``snapshot.dir`` and ``wal.dir`` directories.
 
 .. _admin-backups-hot_backup_vinyl_memtx:
 

doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml

@@ -0,0 +1,14 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            snapshot:
+              dir: 'var/lib/{{ instance_name }}/snapshots'
+              count: 10
+              by:
+                interval: 60
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'

doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml

@@ -0,0 +1,21 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            wal:
+              mode: 'write'
+              dir: 'var/lib/{{ instance_name }}/wals'
+              dir_rescan_delay: 3
+              cleanup_delay: 18000
+              max_size: 268435456
+              ext:
+                new: true
+                old: true
+                spaces:
+                  bands:
+                    new: false
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'

doc/code_snippets/snippets/config/instances.enabled/persistence_wal/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/concepts/atomic/thread_model.rst

@@ -69,7 +69,7 @@ There are also several supplementary threads that serve additional capabilities:
   Separate threads are required because each replica can point to a different position in the log and can run at different speeds.
 
 * There is a thread pool for ad hoc asynchronous tasks,
-  such as a DNS resolver or :ref:`fsync <cfg_binary_logging_snapshots-wal_mode>`.
+  such as a DNS resolver or :ref:`fsync <configuration_reference_wal_mode>`.
 
 * There are OpenMP threads used to parallelize sorting
   (hence, to parallelize building :ref:`indexes <concepts-data_model_indexes>`).

doc/concepts/configuration.rst

@@ -426,7 +426,8 @@ When the limit is reached, ``INSERT`` or ``UPDATE`` requests fail with :ref:`ER_
 Snapshots and write-ahead logs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``snapshot.dir`` and ``wal.dir`` options can be used to configure directories for storing snapshots and write-ahead logs.
+The :ref:`snapshot.dir <configuration_reference_snapshot_dir>` and :ref:`wal.dir <configuration_reference_wal_dir>`
+options can be used to configure directories for storing snapshots and write-ahead logs.
 For example, you can place snapshots and write-ahead logs on different hard drives for better reliability.
 
 .. code-block:: yaml
@@ -438,6 +439,7 @@ For example, you can place snapshots and write-ahead logs on different hard driv
         dir: '/media/drive2/wals'
 
 To learn more about the persistence mechanism in Tarantool, see the :ref:`Persistence <concepts-data_model-persistence>` section.
+Read more about snapshot and WAL configuration: :ref:`Persistence <configuration_persistence>`.
 
 
 
@@ -447,6 +449,7 @@ To learn more about the persistence mechanism in Tarantool, see the :ref:`Persis
 
     configuration/configuration_etcd
     configuration/configuration_code
+    configuration/configuration_persistence
     configuration/configuration_connections
     configuration/configuration_credentials
     configuration/configuration_authentication

doc/concepts/configuration/configuration_persistence.rst

@@ -0,0 +1,186 @@
+..  _configuration_persistence:
+
+Persistence
+===========
+
+To ensure data persistence, Tarantool provides the abilities to:
+
+*   record each data change request into a :ref:`write-ahead log <internals-wal>` (WAL) file (``.xlog`` files)
+*   take :ref:`snapshots <internals-snapshot>` that contain on-disk copy of the entire data set for a given moment (``.snap`` files)
+
+During the recovery process, Tarantool can load the latest snapshot file and then read the requests from the WAL files,
+produced after this snapshot was made.
+
+To learn more about the persistence mechanism in Tarantool, see the :ref:`Persistence <concepts-data_model-persistence>` section.
+The formats of WAL and snapshot files are described in detail in the :ref:`File formats <internals-data_persistence>` section.
+
+..  _configuration_persistence_snapshot:
+
+Configure the snapshots
+-----------------------
+
+**Example on GitHub**: `snapshot <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot>`_
+
+This section describes how to define snapshot settings in the :ref:`snapshot <configuration_reference_snapshot>` section of a YAML configuration.
+
+..  _configuration_persistence_snapshot_dir:
+
+Specify a directory for snapshot files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To configure a directory where the snapshot files are stored, use the :ref:`snapshot.dir <configuration_reference_snapshot_dir>`
+configuration option.
+The example below shows how to specify a snapshot directory for ``instance001`` explicitly:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml
+    :language: yaml
+    :start-at: instance001:
+    :end-at: 'var/lib/{{ instance_name }}/snapshots'
+    :dedent:
+
+By default, WAL files and snapshot files are stored in the same directory ``var/lib/{{ instance_name }}``.
+However, you can specify different directories for them.
+For example, you can place snapshots and write-ahead logs on different hard drives for better reliability:
+
+..  code-block:: yaml
+
+    instance001:
+      snapshot:
+        dir: '/media/drive1/snapshots'
+      wal:
+        dir: '/media/drive2/wals'
+
+..  _configuration_persistence_checkpoint_daemon:
+
+Configure the automatic snapshot creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Tarantool, it is possible to set automatic :ref:`snapshot creation </reference/reference_lua/box_snapshot>`.
+To enable it, the :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>` option is used.
+The option sets up the :ref:`checkpoint daemon <configuration_reference_checkpoint_daemon>` (snapshot daemon), which is
+a constantly running :ref:`fiber <app-fibers>`.
+The checkpoint daemon takes new snapshots every ``snapshot.by.interval`` seconds.
+When the number of snapshots reaches the limit of :ref:`snapshot.count <configuration_reference_snapshot_count>` size,
+the daemon activates Tarantool garbage collector after the new snapshot is taken.
+Tarantool garbage collector deletes the oldest snapshot file and any associated WAL files.
+
+The :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>` option defines the maximum size in bytes
+for of all WAL files created since the last snapshot taken.
+Once this size is exceeded, the checkpoint daemon takes a snapshot and deletes the old WAL files.
+
+The configuration of the checkpoint daemon might look as follows:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml
+    :language: yaml
+    :start-at: count:
+    :end-at: 60
+    :dedent:
+
+If the ``snapshot.by.interval`` option is set to zero, the checkpoint daemon is disabled.
+If the ``snapshot.count`` option is set to zero, the checkpoint daemon does not delete old snapshots.
+
+..  _configuration_persistence_wal:
+
+Configure the write-ahead log
+-----------------------------
+
+**Example on GitHub**: `wal <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/persistence_wal>`_
+
+This section describes how to define WAL settings in the :ref:`wal <configuration_reference_wal>` section of a YAML configuration.
+
+..  _configuration_persistence_wal_mode:
+
+Set the WAL mode
+~~~~~~~~~~~~~~~~
+
+To be able to recover data in case of a possible instance restart, enable recording to the write-ahead log.
+To do it, set the :ref:`wal.mode <configuration_reference_wal_mode>` configuration option to ``write`` or ``fsync``.
+The example below shows how to specify the ``write`` WAL mode for ``instance001``:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
+    :language: yaml
+    :start-at: instance001
+    :end-at: 'write'
+    :dedent:
+
+The ``write`` mode enables WAL and writes the data without waiting the data to be flushed to the storage device.
+The ``fsync`` mode enables WAL and ensures that the record is written to the storage device.
+
+To turn the WAL writer off, set the ``wal.mode`` option to ``none``.
+
+..  _configuration_persistence_wal_dir:
+
+Specify a directory for WAL files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To configure a directory where the WAL files are stored, use the :ref:`wal.dir <configuration_reference_wal_dir>` configuration option.
+The example below shows how to specify a directory for ``instance001`` explicitly:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
+    :language: yaml
+    :start-at: wal:
+    :end-at: 'var/lib/{{ instance_name }}/wals'
+    :dedent:
+
+
+..  _configuration_persistence_wal_rescan:
+
+Set an interval between scans
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If case of :ref:`replication <replication>` or :ref:`hot standby <index-hot_standby>` mode,
+Tarantool scans for changes in the WAL files every :ref:`wal.dir_rescan_delay <configuration_reference_wal_dir_rescan_delay>`
+seconds. The example below shows how to specify the interval between scans:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
+    :language: yaml
+    :start-at: dir_rescan_delay
+    :end-before: cleanup_delay
+    :dedent:
+
+..  _configuration_persistence_wal_maxsize:
+
+Set a maximum size for the WAL file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new WAL file is created when the current one reaches the :ref:`wal.max_size <configuration_reference_wal_max_size>`
+size. The configuration for this option might look as follows:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
+    :language: yaml
+    :start-at: max_size
+    :end-at: 268435456
+    :dedent:
+
+..  _configuration_persistence_wal_rescan:
+
+Set a delay for the garbage collector
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Tarantool, the :ref:`checkpoint daemon <configuration_reference_checkpoint_daemon>` (snapshot daemon)
+takes new snapshots at the given interval (see :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>`).
+After an instance restart, the daemon activates the Tarantool garbage collector that deletes the old WAL files.
+
+To delay the immediate deletion of WAL files, use the :ref:`wal.cleanup_delay <configuration_reference_wal_cleanup_delay>`
+configuration option. The delay eliminates possible erroneous situations when the master deletes WALs
+needed by :ref:`replicas <replication-roles>` after restart.
+As a consequence, replicas sync with the master faster after its restart and
+don't need to download all the data again.
+
+In the example, the delay is set to 5 hours (18000 seconds):
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
+    :language: yaml
+    :start-at: cleanup_delay
+    :end-at: 18000
+    :dedent:
+
+..  _configuration_persistence_wal_ext:
+
+Specify the WAL extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Tarantool Enterprise, you can store an old and new tuple for each crud operation performed.
+The detailed description and examples of the WAL extensions are provided in the :ref:`WAL extensions <wal_extensions>` section.
+
+See also: :ref:`wal.ext.* <configuration_reference_wal_ext>` configuration options.

doc/concepts/data_model/operations.rst

@@ -150,7 +150,7 @@ resource usage of each function.
                 important than the others.
         *   -   WAL settings
             -   The important setting for the write-ahead log is
-                :ref:`wal_mode <cfg_binary_logging_snapshots-wal_mode>`.
+                :ref:`wal.mode <configuration_reference_wal_mode>`.
                 If the setting causes no writing or
                 delayed writing, this factor is unimportant. If the
                 setting causes every data-change request to wait

doc/concepts/data_model/persistence.rst

@@ -12,7 +12,7 @@ In such case, Tarantool restores the data from WAL files
 by reading them and redoing the requests.
 This is called the "recovery process".
 You can change the timing of the WAL writer or turn it off by setting
-the :ref:`wal_mode <cfg_binary_logging_snapshots-wal_mode>`.
+the :ref:`wal.mode <configuration_reference_wal_mode>`.
 
 Tarantool also maintains a set of :ref:`snapshot files <internals-snapshot>`.
 These files contain an on-disk copy of the entire data set for a given moment.
@@ -24,19 +24,20 @@ After creating a new snapshot, the earlier WAL files can be removed to free up s
 To force immediate creation of a snapshot file, use the
 :doc:`box.snapshot() </reference/reference_lua/box_snapshot>` function.
 To enable the automatic creation of snapshot files, use Tarantool's
-:ref:`checkpoint daemon <book_cfg_checkpoint_daemon>`.
-The checkpoint daemon sets intervals for forced checkpoints. It makes sure that the states
+:ref:`checkpoint daemon <configuration_persistence_checkpoint_daemon>`.
+The checkpoint daemon sets intervals for forced snapshots. It makes sure that the states
 of both memtx and vinyl storage engines are synchronized and saved to disk,
 and automatically removes earlier WAL files.
 
 Snapshot files can be created even if there is no WAL file.
 
 ..  NOTE::
 
-     The memtx engine makes only regular checkpoints with the interval set in
-     :ref:`checkpoint daemon <book_cfg_checkpoint_daemon>` configuration.
+     The memtx engine takes only regular snapshots with the interval set in
+     the checkpoint daemon configuration.
 
      The vinyl engine runs checkpointing in the background at all times.
 
 See the :ref:`Internals <internals-data_persistence>` section for more details
 about the WAL writer and the recovery process.
+To learn more about the configuration of the checkpoint daemon and WAL, check the :ref:`Persistence <configuration_persistence>` page.