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/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/snapshot/instances.yml

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

doc/code_snippets/snippets/config/instances.enabled/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/wal/instances.yml

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

doc/concepts/configuration.rst

@@ -429,7 +429,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
@@ -450,6 +451,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_authentication
     .. configuration/configuration_migrating

doc/concepts/configuration/configuration_persistence.rst

@@ -0,0 +1,181 @@
+..  _configuration_persistence:
+
+Persistence
+===========
+
+**Example on GitHub**: `persistence <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/persistence>`_
+
+To ensure data persistence, Tarantool provides the abilities to:
+
+*   record each data change request into a write-ahead log (WAL) file (``.xlog`` files)
+*   take snapshots 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
+-----------------------
+
+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/snapshot/config.yaml
+    :language: yaml
+    :start-at: snapshot:
+    :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_chackpoint_daemon:
+
+Configure the checkpoint daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Tarantool, the :ref:`checkpoint daemon <configuration_reference_checkpoint_daemon>` (snapshot daemon) is a constantly
+running :ref:`fiber <app-fibers>`. The checkpoint daemon
+takes new snapshots every :ref:`snapshot.by.interval seconds.
+After the number of snapshots reaches the :ref:`snapshot.count <configuration_reference_snapshot_count>` size,
+the daemon activates Tarantool garbage collection that deletes the old snapshots 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 garbage collector deletes the old WALl files.
+
+The configuration of the checkpoint daemon might look as follows:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/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.
+
+..  _configuration_persistence_wal:
+
+Configure the write-ahead log
+-----------------------------
+
+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/wal/config.yaml
+    :language: yaml
+    :start-at: instance001
+    :end-at: 'write'
+    :dedent:
+
+The ``write`` mode
+The ``fsync`` mode
+
+An exclusion from this is when the instance is processing data that can be freely rejected.
+For example, when Tarantool is used for caching, WAL can be disabled to reduce i/o load.
+
+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/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 checks 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/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/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/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/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.

doc/dev_guide/internals/file_formats.rst

@@ -10,11 +10,12 @@ Data persistence and the WAL file format
 
 To maintain data persistence, Tarantool writes each data change request (insert,
 update, delete, replace, upsert) into a write-ahead log (WAL) file in the
-:ref:`wal_dir <cfg_basic-wal_dir>` directory. A new WAL file is created
-when the current one reaches the :ref:`wal_max_size <cfg_binary_logging_snapshots-wal_max_size>` size.
+:ref:`wal_dir <cfg_basic-wal_dir>` directory.
 Each data change request gets assigned a continuously growing 64-bit log sequence
 number. The name of the WAL file is based on the log sequence number of the first
 record in the file, plus an extension ``.xlog``.
+A new WAL file is created
+when the current one reaches the :ref:`wal_max_size <cfg_binary_logging_snapshots-wal_max_size>` size.
 
 Apart from a log sequence number and the data change request (formatted as in
 :ref:`Tarantool's binary protocol <internals-box_protocol>`),

doc/enterprise/flight_recorder.rst

@@ -17,8 +17,8 @@ to :ref:`crashing <admin-disaster_recovery>` a Tarantool instance.
 
 .. _enterprise-flight-recorder_enable:
 
-Enabling the flight recorder
-----------------------------
+Enable the flight recorder
+--------------------------
 
 The flight recorder is disabled by default and can be enabled and configured for
 a specific Tarantool instance.
@@ -33,7 +33,7 @@ configuration option to ``true``.
 
 
 After ``flightrec.enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file  ``current.ttfr``.
-This file is stored in the ``snapshot.dir`` directory.
+This file is stored in the :ref:`snapshot.dir <configuration_reference_snapshot_dir>` directory.
 By default, the directory is ``var/lib/{{ instance_name }}/<file_name>.ttfr``.
 
 If the instance crashes and reboots, Tarantool rotates the flight recording:
@@ -49,8 +49,8 @@ Tarantool continues writing to the existing ``current.ttfr`` file after restart.
 
 .. _enterprise-flight-recorder_configure:
 
-Configuring a flight recorder
------------------------------
+Configure a flight recorder
+---------------------------
 
 When the flight recorder is enabled, you can set the options related to :ref:`logging <cfg_logging-log>`,
 :ref:`metrics <metrics-reference>`, and storing the :ref:`request and response <internals-requests_responses>` data.

doc/enterprise/wal_extensions.rst

@@ -1,4 +1,4 @@
-.. _wal_extensions:
+..  _wal_extensions:
 
 WAL extensions
 ==============
@@ -8,47 +8,49 @@ For example, you can enable storing an old and new tuple for each CRUD operation
 This information might be helpful for implementing a CDC (Change Data Capture) utility
 that transforms a data replication stream.
 
-.. _wal_extensions_configuration:
+..  _wal_extensions_configuration:
 
 Configuration
 -------------
 
-To configure WAL extensions, use the ``wal.ext`` :ref:`configuration property <configuration_reference_wal>`.
-Inside the ``wal_ext`` block, you can enable storing old and new tuples as follows:
+WAL extensions are disabled by default.
+To configure them, use the :ref:`wal.ext.* <configuration_reference_wal_ext>` configuration options.
+Inside the ``wal.ext`` block, you can enable storing old and new tuples as follows:
 
-*   Set the ``old`` and ``new`` options to ``true`` to store old and new tuples in a write-ahead log for all spaces.
+*   To store old and new tuples in a write-ahead log for all spaces, set the
+    :ref:`wal.ext.old <configuration_reference_wal_ext_old>` and `wal.ext.new <configuration_reference_wal_ext_new>`
+    options to ``true``:
 
-    ..  code-block:: lua
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence/config.yaml
+        :language: yaml
+        :start-at: wal:
+        :end-at: old: true
+        :dedent:
 
-        box.cfg {
-            wal_ext = { old = true, new = true }
-        }
+*   To adjust these options for specific spaces, specify the :ref:`wal.ext.spaces <configuration_reference_wal_ext_spaces>` option:
 
-*   To adjust these options for specific spaces, use the ``spaces`` option.
+    ..  code-block:: yaml
 
-    ..  code-block:: lua
+        wal:
+          ext:
+            old: true
+            new: true
+            spaces:
+              space1:
+                old: false
+              space2:
+                new: false
 
-        box.cfg {
-            wal_ext = {
-                old = true, new = true,
-                spaces = {
-                    space1 = { old = false },
-                    space2 = { new = false }
-                }
-            }
-        }
-
-
-    The configuration for specific spaces has priority over the global configuration,
-    so only new tuples are added to the log for ``space1`` and only old tuples for ``space2``.
+    The configuration for specific spaces has priority over the configuration in the ``wal.ext.new`` and ``wal.ext.old``
+    options.
+    It means that only new tuples are added to the log for ``space1`` and only old tuples for ``space2``.
 
 Note that records with additional fields are :ref:`replicated <replication-architecture>` as follows:
 
 *   If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped.
 *   If a replica and master have different configurations for WAL records, a master's configuration is ignored.
 
-
-.. _wal_extensions_example:
+..  _wal_extensions_example:
 
 Example
 -------