Add documentation for the upgrade feature (#1311)

core/src/main/java/com/scalar/db/api/Admin.java

@@ -440,8 +440,8 @@ void importTable(String namespace, String table, Map<String, String> options)
 
   /**
    * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
-   * ScalarDB version of your application environment.
+   * as indicated in the release notes, you will need to run this method after updating the ScalarDB
+   * version that your application environment uses.
    *
    * @param options options to upgrade
    * @throws ExecutionException if the operation fails

docs/api-guide.md

@@ -278,6 +278,16 @@ Map<String, String> options = ...;
 admin.repairTable("ns", "tbl", tableMetadata, options);
 ```
 
+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, as indicated in the release notes, you will need to run this method after updating the ScalarDB version that your application environment uses.
+
+```java
+// Upgrade the ScalarDB environment.
+Map<String, String> options = ...;
+admin.upgrade(options);
+```
+
 ### Specify operations for the Coordinator table
 
 The Coordinator table is used by the [Transactional API](#transactional-api) to track the statuses of transactions.

docs/schema-loader.md

@@ -93,6 +93,12 @@ Create/Delete schemas in the storage defined in the config file
                       The replication strategy, must be SimpleStrategy or
                         NetworkTopologyStrategy (supported in Cassandra)
       --ru=<ru>       Base resource unit (supported in DynamoDB, Cosmos DB)
+      --upgrade       Upgrades the ScalarDB environment to support the latest
+                        version of the ScalarDB API. Typically, as indicated in
+                        the release notes, you will need to run this command
+                        after updating the ScalarDB version that your
+                        application environment uses.
+
 ```
 
 For a sample properties file, see [`database.properties`](https://github.com/scalar-labs/scalardb/blob/master/conf/database.properties).
@@ -444,6 +450,14 @@ $ java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER>
 
 You can import an existing table in JDBC databases to ScalarDB by using the `--import` option and an import-specific schema file. For details, see [Importing Existing Tables to ScalarDB by Using ScalarDB Schema Loader](./schema-loader-import.md).
 
+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, as indicated in the release notes, you will need to run this command after updating the ScalarDB version that your application environment uses. When running the following command, be sure to replace the contents in the angle brackets as described:
+
+```console
+$ java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> --upgrade
+```
+
 ### Sample schema file
 
 The following is a sample schema. For a sample schema file, see [`schema_sample.json`](https://github.com/scalar-labs/scalardb/blob/master/schema-loader/sample/schema_sample.json).
@@ -639,9 +653,12 @@ dependencies {
 }
 ```
 
-### Create, alter, repair, or delete tables
+### Sample usage
+
+By using the `SchemaLoader` class, you can execute the same commands as the CLI:
 
-You can create, alter, delete, or repair tables that are defined in the schema by using Schema Loader. To do this, you can pass a ScalarDB properties file, schema, and additional options, if needed, as shown below:
+- To create, alter, delete, or repair tables that are defined in the schema, you can pass a ScalarDB properties file, schema, and additional options, if needed. 
+- To upgrade the environment, you can pass a ScalarDB properties and additional options, if needed.
 
 ```java
 public class SchemaLoaderSample {
@@ -671,6 +688,8 @@ public class SchemaLoaderSample {
     Map<String, String> reparationOptions = new HashMap<>();
     reparationOptions.put(DynamoAdmin.NO_BACKUP, "true");
 
+    Map<String, String> upgradeOptions = new HashMap<>(tableCreationOptions);
+
     // Create tables.
     SchemaLoader.load(configFilePath, schemaFilePath, tableCreationOptions, createCoordinatorTables);
 
@@ -683,6 +702,9 @@ public class SchemaLoaderSample {
     // Delete tables.
     SchemaLoader.unload(configFilePath, schemaFilePath, deleteCoordinatorTables);
 
+    // Upgrade the environment
+    SchemaLoader.upgrade(configFilePath, upgradeOptions);
+
     return 0;
   }
 }
@@ -718,6 +740,9 @@ SchemaLoader.repairAll(properties, serializedSchemaJson, reparationOptions, repa
 
 // Delete tables.
 SchemaLoader.unload(properties, serializedSchemaJson, deleteCoordinatorTables);
+
+// Upgrade the environment
+SchemaLoader.upgrade(properties, upgradeOptions);
 ```
 
 ### Import tables

docs/storage-abstraction.md

@@ -433,6 +433,16 @@ Map<String, String> options = ...;
 admin.repairTable("ns", "tbl", tableMetadata, options);
 ```
 
+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, as indicated in the release notes, you will need to run this method after updating the ScalarDB version that your application environment uses.
+
+```java
+// Upgrade the ScalarDB environment.
+Map<String, String> options = ...;
+admin.upgrade(options);
+```
+
 ### Implement CRUD operations
 
 The following sections describe CRUD operations.

schema-loader/src/main/java/com/scalar/db/schemaloader/SchemaLoader.java

@@ -598,8 +598,8 @@ private static void importTables(
 
   /**
    * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
-   * ScalarDB version of your application environment.
+   * as indicated in the release notes, you will need to run this method after updating the ScalarDB
+   * version that your application environment uses.
    *
    * @param configPath path to the ScalarDB config properties.
    * @param options specific options for upgrading.
@@ -613,8 +613,8 @@ public static void upgrade(Path configPath, Map<String, String> options)
 
   /**
    * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
-   * ScalarDB version of your application environment.
+   * as indicated in the release notes, you will need to run this method after updating the ScalarDB
+   * version that your application environment uses.
    *
    * @param configProperties ScalarDB config properties.
    * @param options specific options for upgrading.

schema-loader/src/main/java/com/scalar/db/schemaloader/command/SchemaLoaderCommand.java

@@ -100,8 +100,8 @@ private static class Mode {
     @Option(
         names = {"--upgrade"},
         description =
-            "Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will be requested, as indicated on the release notes, to run this command after"
-                + " updating the ScalarDB version of your application environment.",
+            "Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, as indicated in the release notes, you will need to run this command after"
+                + " updating the ScalarDB version that your application environment uses.",
         defaultValue = "false")
     boolean upgrade;
   }