From f3ae3adfaf51d4b21fdc46b2882c0a7f5d4fbf74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Leszczy=C5=84ski?= <2000michal@wp.pl>
Date: Wed, 26 Jun 2024 13:12:06 +0200
Subject: [PATCH] feat(docs): backup, add 3.3 tablets and desc schema docs

---
 docs/source/backup/index.rst         |  7 ++++++-
 docs/source/backup/specification.rst | 18 +++++++++++++-----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/docs/source/backup/index.rst b/docs/source/backup/index.rst
index 5e003210b1..0822bef3f8 100644
--- a/docs/source/backup/index.rst
+++ b/docs/source/backup/index.rst
@@ -44,9 +44,14 @@ Process
 The backup procedure consists of multiple steps executed sequentially.
 
 #. **Snapshot** - Take a snapshot of data on each node (according to backup configuration settings).
-#. (Optional) **Schema** - Upload the schema in CQL text format to the backup storage destination,
+
+   Note that ScyllaDB Manager stops `tablets <https://opensource.docs.scylladb.com/stable/architecture/tablets.html>`_  migration for the duration of this step.
+#. **Schema** - Upload the schema in CQL text format to the backup storage destination,
    this requires that you added the cluster with CQL username and password.
    If you didn't you can :ref:`update the cluster using sctool <cluster-update>` at any point in time.
+
+   Note that starting from ScyllaDB 6.0 and 2024.2 (and compatible ScyllaDB Manager 3.3),
+   mentioned CQL files are necessary for performing schema restoration (:ref:`sctool restore --restore-schema <sctool-restore>`).
 #. **Upload** - Upload the snapshot to the backup storage destination.
 #. **Manifest** - Upload the manifest file containing metadata about the backup.
 #. **Purge** - If the retention threshold has been reached, remove the oldest backup from the storage location.
diff --git a/docs/source/backup/specification.rst b/docs/source/backup/specification.rst
index 71ebfc8b37..fb255afeff 100644
--- a/docs/source/backup/specification.rst
+++ b/docs/source/backup/specification.rst
@@ -65,7 +65,15 @@ schema
 ......
 
 The schema directory contains text dumps of database schema.
-They are mainly for information purposes, for restore the backup ``system_schema`` keyspace shall be used.
+
+Starting from ScyllaDB 6.0 and 2024.2 (and compatible ScyllaDB Manager 3.3), they are required for the schema restoration.
+They have ``schema_with_internals.json.gz`` suffix and represent the output of ``DESCRIBE SCHEMA WITH INTERNALS`` CQL query,
+which returns rows in the format ``keyspace|type|name|CQL create statement`` in the correct order.
+
+For older ScyllaDB versions, those files are mainly for information purposes,
+for restore the backup ``system_schema`` keyspace shall be used.
+They have ``schema.tar.gz`` suffix and represent schema archive divided among keyspaces.
+
 To enable upload of the files make sure that the cluster is added with username and password flags.
 
 .. code-block:: none
@@ -73,15 +81,15 @@ To enable upload of the files make sure that the cluster is added with username
    schema
    └── cluster
        └── 3e99d4a8-67d2-45fe-87fb-87b1b90ea2dc
-           ├── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095541UTC_schema.tar.gz
-           ├── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095542UTC_schema.tar.gz
-           └── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095748UTC_schema.tar.gz
+           ├── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095541UTC_schema_with_internals.json.gz
+           ├── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095542UTC_schema_with_internals.json.gz
+           └── task_f70117d8-c10e-4e90-9606-2587936b3757_tag_sm_20210809095748UTC_schema_with_internals.json.gz
 
 The schema file path is structured as follows.
 
 .. code-block:: none
 
-   meta/cluster/<cluster ID>/task_<task ID>_tag_<snapshot tag>_schema.tar.gz
+   meta/cluster/<cluster ID>/task_<task ID>_tag_<snapshot tag>_schema_with_internals.json.gz
 
 sst
 ...