docs: add compatibility to meta/README.md (databendlabs#14128)

* chore: fix renamed method in the comment guide

* docs: add compatibility to meta/README.md

src/meta/README.md

@@ -68,3 +68,99 @@ To add a new feature(add new type or update an type), the developer should do:
 
 - Add a compatibility test to ensure that compatibility will always be kept in
     future, a good example is: `src/meta/proto-conv/tests/it/v039_data_mask.rs`
+
+
+
+
+
+## Compatibility with Databend Query
+
+The following is an illustration of current query-meta compatibility:
+
+| `Meta\Query`     | [0.7.59, 0.8.80) | [0.8.80, 0.9.41) | [0.9.41, 1.1.34) | [1.1.34, +∞) |
+|:-----------------|:-----------------|:-----------------|:-----------------|:-------------|
+| [0.8.30, 0.8.35) | ✅                | ❌                | ❌                | ❌            |
+| [0.8.35, 0.9.23) | ✅                | ✅                | ✅                | ❌            |
+| [0.9.23, 0.9.42) | ❌                | ✅                | ✅                | ❌            |
+| [0.9.42, 1.1.32) | ❌                | ❌                | ✅                | ❌            |
+| [1.1.32, 1.2.63) | ❌                | ❌                | ✅                | ✅            |
+| [1.2.63, +∞)     | ❌                | ❌                | ✅                | ✅            |
+
+
+## Compatibility between databend-meta
+
+| Meta version      | Backward compatible with |
+|:------------------|:-------------------------|
+| [0.9.41, 1.2.212) | [0.9.41, 1.2.212)        |
+| [1.2.212, +∞)     | [0.9.41, +∞)             |
+
+
+- `1.2.53` Incompatible, rolling upgrade is allowed without snapshot transmitting.
+  Snapshot format changed thus during rolling upgrading,
+  it requires all node data to be up-to-date, ensure there is no need to replicate with snapshot.
+
+- `1.2.163` Feature: gRPC API: `kv_read_v1()` is added. For stream reading.
+
+- `1.2.212` Feature: raft API: `install_snapshot_v1()`. Compatible with old versions.
+  Rolling upgrade is supported.
+  In this version, databend-meta raft-server introduced a new API `install_snapshot_v1()`.
+  The raft-client will try to use either this new API or the original `install_snapshot()`.
+
+
+## Compatibility of databend-meta on-disk data
+
+The on-disk data of Databend-meta evolves over time while maintaining backward compatibility.
+
+### Identifying the versions
+
+Upon startup, Databend-meta will display the on-disk data version:
+
+For example, running `databend-meta --single` produces:
+
+```
+Databend Metasrv
+
+Version: v1.1.33-nightly-...
+Working DataVersion: V0
+
+On Disk Data:
+    Dir: ./.databend/meta
+    Version: version=V0, upgrading=None
+```
+
+- `Working DataVersion` denotes the version Databend-meta operates on.
+- `On Disk Data -- DataVersion` denotes the version of the on-disk data.
+
+The Working DataVersion must be greater than or equal to the on-disk DataVersion; otherwise, it will panic.
+
+The on-disk DataVersion must be compatible with the current Databend-meta version.
+If not, the system will prompt the user to downgrade Databend-meta and quit with a panic.
+
+### Automatic upgrade
+
+When `databend-meta` starting up, the on-disk is upgraded if it is compatible with the working DataVersion.
+The upgrade progress will be printed to `stderr` and to log file at INFO level, e.g.:
+
+```text
+Upgrade on-disk data
+    From: V0(2023-04-21: compatible with openraft v07 and v08, using openraft::compat)
+    To:   V001(2023-05-15: Get rid of compat, use only openraft v08 data types)
+Begin upgrading: version: V0, upgrading: V001
+Write header: version: V0, upgrading: V001
+Upgraded 167 records
+Finished upgrading: version: V001, upgrading: None
+Write header: version: V001, upgrading: None
+```
+
+If `databend-meta` crashes before upgrading finishes,
+it will clear partially upgraded data and resume the upgrade when it starts up again.
+
+### Backup data compatibility
+
+- The exported backup data **can only be imported** with the same version of `databend-metactl`.
+
+- The first line of the backup is the version, e.g.:
+  `["header",{"DataHeader":{"key":"header","value":{"version":"V100","upgrading":null}}}]`
+
+- **NO automatic upgrade** will be done when importing.
+  Automatic upgrade will only be done when `databend-meta` is brought up.

src/meta/proto-conv/tests/it/v002_share_account_meta.rs

@@ -28,7 +28,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v2_share_account_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v002_share_meta.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v2_share_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v002_table_meta.rs

@@ -34,7 +34,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v2_table_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v005_database_meta.rs

@@ -32,7 +32,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v5_database_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v005_share_meta.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v5_share_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v006_copied_file_info.rs

@@ -28,7 +28,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v6_copied_file_info() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v010_table_meta.rs

@@ -34,7 +34,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v10_table_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v012_table_meta.rs

@@ -35,7 +35,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v12_table_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v023_table_meta.rs

@@ -35,7 +35,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v23_table_meta() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v024_table_meta.rs

@@ -35,7 +35,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v24_table_meta() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v026_schema.rs

@@ -29,7 +29,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v26_schema() -> anyhow::Result<()> {
     let schema_v26 = [

src/meta/proto-conv/tests/it/v027_schema.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v27_schema() -> anyhow::Result<()> {
     let schema_v27 = [

src/meta/proto-conv/tests/it/v028_schema.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v28_schema() -> anyhow::Result<()> {
     let schema_v28 = [

src/meta/proto-conv/tests/it/v029_schema.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v29_schema() -> anyhow::Result<()> {
     let schema_v29 = [

src/meta/proto-conv/tests/it/v033_table_meta.rs

@@ -34,7 +34,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v33_table_meta() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v034_schema.rs

@@ -31,7 +31,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v34_schema() -> anyhow::Result<()> {
     let schema_v34 = [

src/meta/proto-conv/tests/it/v038_empty_proto.rs

@@ -26,7 +26,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v38_empty_proto() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![160, 6, 7, 168, 6, 1];

src/meta/proto-conv/tests/it/v039_data_mask.rs

@@ -27,7 +27,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v39_data_mask() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v040_table_meta.rs

@@ -34,7 +34,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v40_table_meta() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v044_table_meta.rs

@@ -35,7 +35,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v44_table_meta() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v045_background.rs

@@ -39,7 +39,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v44_background_task() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v048_background.rs

@@ -40,7 +40,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v48_background_task_case_2() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v049_network_policy.rs

@@ -27,7 +27,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v49_network_policy() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v050_user_info.rs

@@ -29,7 +29,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v50_user_info() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v051_obs_and_cos_storage.rs

@@ -29,7 +29,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v51_obs_stage() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v057_hdfs_storage.rs

@@ -28,7 +28,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v57_hdfs_storage() -> anyhow::Result<()> {
     let bytes = vec![

src/meta/proto-conv/tests/it/v058_udf.rs

@@ -30,7 +30,7 @@ use crate::common;
 // * or be removed when an old version is no longer supported. *
 // *************************************************************
 //
-// The message bytes are built from the output of `test_build_pb_buf()`
+// The message bytes are built from the output of `test_pb_from_to()`
 #[test]
 fn test_decode_v57_udf() -> anyhow::Result<()> {
     let bytes: Vec<u8> = vec![

src/meta/proto-conv/tests/it/v063_connection.rs

@@ -32,7 +32,7 @@ use crate::common;
 fn test_decode_v62_connection() -> anyhow::Result<()> {
     let user_defined_connection_v62 = vec![
         10, 7, 109, 121, 95, 99, 111, 110, 110, 18, 2, 115, 51, 26, 10, 10, 3, 107, 101, 121, 18,
-        3, 118, 97, 108, 160, 6, 62, 168, 6, 24,
+        3, 118, 97, 108, 160, 6, 63, 168, 6, 24,
     ];
     let want = || UserDefinedConnection {
         name: "my_conn".to_string(),
@@ -43,7 +43,7 @@ fn test_decode_v62_connection() -> anyhow::Result<()> {
     common::test_load_old(
         func_name!(),
         user_defined_connection_v62.as_slice(),
-        62,
+        63,
         want(),
     )?;
     Ok(())

src/meta/service/tests/it/tests/service.rs

@@ -94,9 +94,8 @@ pub fn next_port() -> u32 {
     29000u32 + (GlobalSequence::next() as u32)
 }
 
+/// It holds a reference to a MetaNode or a GrpcServer, for testing MetaNode or GrpcServer.
 pub struct MetaSrvTestContext {
-    // /// To hold a per-case logging guard
-    // logging_guard: (WorkerGuard, DefaultGuard),
     pub config: configs::Config,
 
     pub meta_node: Option<Arc<MetaNode>>,