diff --git a/core/src/main/java/com/scalar/db/api/Admin.java b/core/src/main/java/com/scalar/db/api/Admin.java index ee7f0d3eed..6f695af2c0 100644 --- 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 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 index 7faebacd6d..b5a7f0ac49 100644 --- 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 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 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 index 7c981fc910..3047b6a434 100644 --- 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= The replication factor (supported in Cassandra) --replication-strategy= @@ -387,9 +386,9 @@ $ java -jar scalardb-schema-loader-.jar --jdbc -j -u
{{ notice--info | markdownify }}
-### 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-.jar --config -f [--coordinator] --repair-all @@ -663,8 +662,8 @@ public class SchemaLoaderSample { Map indexCreationOptions = new HashMap<>(); indexCreationOptions.put(DynamoAdmin.NO_SCALING, "true"); - Map tableReparationOptions = new HashMap<>(); - indexCreationOptions.put(DynamoAdmin.NO_BACKUP, "true"); + Map reparationOptions = new HashMap<>(); + reparationOptions.put(DynamoAdmin.NO_BACKUP, "true"); // Create tables. SchemaLoader.load(configFilePath, schemaFilePath, tableCreationOptions, createCoordinatorTables); @@ -672,8 +671,8 @@ public class SchemaLoaderSample { // 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 index d221cfc353..4858b5681e 100644 --- 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 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 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 index a09e8a8237..854f9f7995 100644 --- 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 index b6ced1a4a3..ee06a4a2ac 100644 --- 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;