Update documentation for the repair feature (scalar-labs#1300)

Co-authored-by: Josh Wong <joshua.wong@scalar-labs.com>
Torch3333 · Nov 30, 2023 · ce54066 · ce54066
1 parent b169502
commit ce54066
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 24 deletions.
diff --git a/core/src/main/java/com/scalar/db/api/Admin.java b/core/src/main/java/com/scalar/db/api/Admin.java
@@ -361,19 +361,23 @@ default boolean tableExists(String namespace, String table) throws ExecutionExce
   }
 
   /**
-   * Repair a namespace which may be in an unknown state.
+   * Repair a namespace that may be in an unknown state, such as the namespace exists in the
+   * underlying storage but not its ScalarDB metadata or vice versa. This will re-create the
+   * namespace and its metadata if necessary.
    *
-   * @param namespace an existing namespace
+   * @param namespace a namespace
    * @param options options to repair
    * @throws ExecutionException if the operation fails
    */
   void repairNamespace(String namespace, Map<String, String> options) throws ExecutionException;
 
   /**
-   * Repair a table which may be in an unknown state.
+   * Repair a table that may be in an unknown state, such as the table exists in the underlying
+   * storage but not its ScalarDB metadata or vice versa. This will re-create the table, its
+   * secondary indexes, and their metadata if necessary.
    *
-   * @param namespace an existing namespace
-   * @param table an existing table
+   * @param namespace a namespace
+   * @param table a table
    * @param metadata the metadata associated to the table to repair
    * @param options options to repair
    * @throws ExecutionException if the operation fails

diff --git a/docs/api-guide.md b/docs/api-guide.md
@@ -250,6 +250,34 @@ You can get table metadata as follows:
 TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");
 ```
 
+### Repair a namespace
+
+If a namespace is in an unknown state, such as the namespace exists in the underlying storage but not its ScalarDB metadata or vice versa, this method will re-create the namespace and its metadata if necessary.
+
+You can repair the namespace as follows:
+
+```java
+// Repair the namespace "ns" with options.
+Map<String, String> options = ...;
+admin.repairNamespace("ns", options);
+```
+
+### Repair a table
+
+If a table is in an unknown state, such as the table exists in the underlying storage but not its ScalarDB metadata or vice versa, this method will re-create the table, its secondary indexes, and their metadata if necessary.
+
+You can repair the table as follows:
+
+```java
+// Repair the table "ns.tbl" with options.
+TableMetadata tableMetadata =
+    TableMetadata.newBuilder()
+        ...
+        .build();
+Map<String, String> options = ...;
+admin.repairTable("ns", "tbl", tableMetadata, options);
+```
+
 ### Specify operations for the Coordinator table
 
 The Coordinator table is used by the [Transactional API](#transactional-api) to track the statuses of transactions.

diff --git a/docs/schema-loader.md b/docs/schema-loader.md
@@ -82,10 +82,9 @@ Create/Delete schemas in the storage defined in the config file
                       Path to the schema json file
       --no-backup     Disable continuous backup (supported in DynamoDB)
       --no-scaling    Disable auto-scaling (supported in DynamoDB, Cosmos DB)
-      --repair-all    Repair tables : it repairs the table metadata of
-                               existing tables. When using Cosmos DB, it
-                               additionally repairs stored procedure attached
-                               to each table
+      --repair-all    Repair namespaces and tables that are in an unknown
+                        state: it re-creates namespaces, tables, secondary
+                        indexes, and their metadata if necessary.          
       --replication-factor=<replicaFactor>
                       The replication factor (supported in Cassandra)
       --replication-strategy=<replicationStrategy>
@@ -387,9 +386,9 @@ $ java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER>
 
 <div class="notice--info">{{ notice--info | markdownify }}</div>
 
-### Repair tables
+### Repair namespaces and tables
 
-You can repair the table metadata of existing tables by using the properties file. To repair table metadata of existing tables, run the following command, replacing the contents in the angle brackets as described:
+You can repair namespaces and tables by using the properties file. The reason for repairing namespaces and tables is because they can be in an unknown state, such as a namespace or table exists in the underlying storage but not its ScalarDB metadata or vice versa. Repairing the namespaces, the tables, the secondary indexes, and their metadata requires re-creating them if necessary. To repair them, run the following command, replacing the contents in the angle brackets as described:
 
 ```console
 $ java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> [--coordinator] --repair-all 
@@ -663,17 +662,17 @@ public class SchemaLoaderSample {
     Map<String, String> indexCreationOptions = new HashMap<>();
     indexCreationOptions.put(DynamoAdmin.NO_SCALING, "true");
 
-    Map<String, String> tableReparationOptions = new HashMap<>();
-    indexCreationOptions.put(DynamoAdmin.NO_BACKUP, "true");
+    Map<String, String> reparationOptions = new HashMap<>();
+    reparationOptions.put(DynamoAdmin.NO_BACKUP, "true");
 
     // Create tables.
     SchemaLoader.load(configFilePath, schemaFilePath, tableCreationOptions, createCoordinatorTables);
 
     // Alter tables.
     SchemaLoader.alterTables(configFilePath, alteredSchemaFilePath, indexCreationOptions);
 
-    // Repair tables.
-    SchemaLoader.repairTables(configFilePath, schemaFilePath, tableReparationOptions, repairCoordinatorTables);
+    // Repair namespaces and tables.
+    SchemaLoader.repairAll(configFilePath, schemaFilePath, reparationOptions, repairCoordinatorTables);
 
     // Delete tables.
     SchemaLoader.unload(configFilePath, schemaFilePath, deleteCoordinatorTables);
@@ -692,8 +691,8 @@ SchemaLoader.load(configFilePath, serializedSchemaJson, tableCreationOptions, cr
 // Alter tables.
 SchemaLoader.alterTables(configFilePath, serializedAlteredSchemaFilePath, indexCreationOptions);
 
-// Repair tables.
-SchemaLoader.repairTables(configFilePath, serializedSchemaJson, tableReparationOptions, repairCoordinatorTables);
+// Repair namespaces and tables.
+SchemaLoader.repairAll(configFilePath, serializedSchemaJson, reparationOptions, repairCoordinatorTables);
 
 // Delete tables.
 SchemaLoader.unload(configFilePath, serializedSchemaJson, deleteCoordinatorTables);
@@ -708,8 +707,8 @@ SchemaLoader.load(properties, serializedSchemaJson, tableCreationOptions, create
 // Alter tables.
 SchemaLoader.alterTables(properties, serializedAlteredSchemaFilePath, indexCreationOptions);
 
-// Repair tables.
-SchemaLoader.repairTables(properties, serializedSchemaJson, tableReparationOptions, repairCoordinatorTables);
+// Repair namespaces and tables.
+SchemaLoader.repairAll(properties, serializedSchemaJson, reparationOptions, repairCoordinatorTables);
 
 // Delete tables.
 SchemaLoader.unload(properties, serializedSchemaJson, deleteCoordinatorTables);

diff --git a/docs/storage-abstraction.md b/docs/storage-abstraction.md
@@ -405,6 +405,34 @@ You can get table metadata as follows:
 TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");
 ```
 
+### Repair a namespace
+
+If a namespace is in an unknown state, such as the namespace exists in the underlying storage but not its ScalarDB metadata or vice versa, this method will re-create the namespace and its metadata if necessary.
+
+You can repair the namespace as follows:
+
+```java
+// Repair the namespace "ns" with options.
+Map<String, String> options = ...;
+    admin.repairNamespace("ns", options);
+```
+
+### Repair a table
+
+If a table is in an unknown state, such as the table exists in the underlying storage but not its ScalarDB metadata or vice versa, this method will re-create the table, its secondary indexes, and their metadata if necessary.
+
+You can repair the table as follows:
+
+```java
+// Repair the table "ns.tbl" with options.
+TableMetadata tableMetadata =
+    TableMetadata.newBuilder()
+        ...
+        .build();
+Map<String, String> options = ...; 
+admin.repairTable("ns", "tbl", tableMetadata, options);
+```
+
 ### Implement CRUD operations
 
 The following sections describe CRUD operations.

diff --git a/schema-loader/src/main/java/com/scalar/db/schemaloader/SchemaLoader.java b/schema-loader/src/main/java/com/scalar/db/schemaloader/SchemaLoader.java
@@ -285,7 +285,10 @@ private static void unload(
   }
 
   /**
-   * Repair namespaces and tables defined in the schema that are in an unknown state.
+   * Repair namespaces and tables defined in the schema that are in an unknown state, such as the
+   * namespace or table exists in the underlying storage but not its ScalarDB metadata or vice
+   * versa. This will re-create the namespaces, the tables, the secondary indexes, and their
+   * metadata if necessary.
    *
    * @param configProperties ScalarDB config properties
    * @param serializedSchemaJson serialized json string schema.
@@ -305,7 +308,10 @@ public static void repairAll(
   }
 
   /**
-   * Repair namespaces and tables defined in the schema file that are in an unknown state.
+   * Repair namespaces and tables defined in the schema that are in an unknown state, such as the
+   * namespace or table exists in the underlying storage but not its ScalarDB metadata or vice
+   * versa. This will re-create the namespaces, the tables, the secondary indexes, and their
+   * metadata if necessary.
    *
    * @param configProperties ScalarDB properties.
    * @param schemaPath path to the schema file.
@@ -325,7 +331,10 @@ public static void repairAll(
   }
 
   /**
-   * Repair namespaces and tables defined in the schema that are in an unknown state.
+   * Repair namespaces and tables defined in the schema that are in an unknown state, such as the
+   * namespace or table exists in the underlying storage but not its ScalarDB metadata or vice
+   * versa. This will re-create the namespaces, the tables, the secondary indexes, and their
+   * metadata if necessary.
    *
    * @param configPath path to the ScalarDB config.
    * @param serializedSchemaJson serialized json string schema.
@@ -345,7 +354,10 @@ public static void repairAll(
   }
 
   /**
-   * Repair namespaces and tables defined in the schema file that are in an unknown state.
+   * Repair namespaces and tables defined in the schema that are in an unknown state, such as the
+   * namespace or table exists in the underlying storage but not its ScalarDB metadata or vice
+   * versa. This will re-create the namespaces, the tables, the secondary indexes, and their
+   * metadata if necessary.
    *
    * @param configPath path to the ScalarDB config.
    * @param schemaPath path to the schema file.

diff --git a/schema-loader/src/main/java/com/scalar/db/schemaloader/command/SchemaLoaderCommand.java b/schema-loader/src/main/java/com/scalar/db/schemaloader/command/SchemaLoaderCommand.java
@@ -79,7 +79,7 @@ private static class Mode {
     @Option(
         names = {"--repair-all"},
         description =
-            "Repair namespaces and tables that are in an unknown state: it recreates namespaces, tables, secondary indexes and their metadata if necessary.",
+            "Repair namespaces and tables that are in an unknown state: it re-creates namespaces, tables, secondary indexes, and their metadata if necessary.",
         defaultValue = "false")
     boolean repairAll;