docs: add upgrade note for using InfluxDB protocol (#963)

GreptimeTeam · May 20, 2024 · f7b806b · f7b806b
1 parent a7d3ffd
commit f7b806b
Show file tree

Hide file tree

Showing 2 changed files with 110 additions and 35 deletions.
diff --git a/docs/nightly/en/user-guide/upgrade.md b/docs/nightly/en/user-guide/upgrade.md
@@ -45,9 +45,10 @@ For a complete upgrade, you will need to execute this tools twice with each targ
 
 Here is a complete example for upgrading from `v0.7.x` to `v0.8.0`.
 
-
 ### Export `CREATE TABLE`
 
+Assuming the HTTP service port of the old database is `4000`.
+
 ```shell
 greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export --target create-table
 ```
@@ -82,7 +83,7 @@ CREATE TABLE foo (
     TIME INDEX (ts),
     PRIMARY KEY(host)
 ) ENGINE=mito 
-WITH(
+WITH( # Delete 
     regions=1
 );
 ```
@@ -130,7 +131,7 @@ CREATE TABLE IF NOT EXISTS "phy" (
   "__tsid" BIGINT UNSIGNED NOT NULL,
   "host" STRING NULL,
   "job" STRING NULL,
-  PRIMARY KEY ("__table_id", "__tsid", "host", "job")
+  PRIMARY KEY ("__table_id", "__tsid", "host", "job") # Modify this line
 )
 ENGINE=metric
 WITH(
@@ -179,14 +180,43 @@ CREATE TABLE IF NOT EXISTS "phy" (
   "host" STRING NULL,
   "job" STRING NULL,
   PRIMARY KEY ("host", "job")
-  TIME INDEX ("ts")
+  TIME INDEX ("ts") # Add this line
 )
 ENGINE=metric
 WITH(
   physical_metric_table = ''
 );
 ```
 
+#### Update the create table statement for tables written using the InfluxDB protocol
+
+Related [issue](https://github.com/GreptimeTeam/greptimedb/pull/3794)
+
+Before:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+  "ts" TIMESTAMP(6) NOT NULL, # Modify to TIMESTAMP(9)
+  "val" DOUBLE NULL,
+  "host" STRING NULL,
+  "job" STRING NULL,
+  PRIMARY KEY ("host", "job"),
+  TIME INDEX ("ts")
+)
+ENGINE=mito;
+```
+
+After:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+  "ts" TIMESTAMP(9) NOT NULL,
+  "val" DOUBLE NULL,
+  "host" STRING NULL,
+  "job" STRING NULL,
+  PRIMARY KEY ("host", "job"),
+  TIME INDEX ("ts")
+)
+ENGINE=mito;
+```
 
 ### Export table data
 
@@ -231,6 +261,14 @@ And then import the data
 psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptime-public_copy_from.sql
 ```
 
+### Known Issues
+
+#### The upgrade tool will still export physical table data from v0.7.0
+When importing v0.7.0 data into v0.8.0, the database may encounter the following error. This error can be safely ignored as it does not affect data integrity.
+```
+psql:/tmp/greptimedb-export/greptime-public_copy_from.sql:2: ERROR:  Alter request to physical region is forbidden
+```
+
 ### Clean up
 
 At this step all the data is migrated. You can check the data in the new cluster.
@@ -241,10 +279,10 @@ After confirming that the data is correct, you can clean up the old cluster and
 
 This section gives a recommended overall process for upgrading GreptimeDB smoothly. You can skip this section if your environment can go offline on the upgrade progress.
 
-1. Create a brand new v0.4 cluster
-2. Export and import `create-table`
-3. Switch workload to the new cluster
-4. Export and import table data
+1. Create a brand new v0.8.0 cluster.
+2. Use the v0.8.0 CLI tool to export and import `create-table`.
+3. Switch the workload to the new cluster.
+4. Use the v0.8.0 CLI tool to export and import `table-data`.
 
 Caveats
 - Changes to table structure between step 2 and 3 will be lost

diff --git a/docs/nightly/zh/user-guide/upgrade.md b/docs/nightly/zh/user-guide/upgrade.md
@@ -41,11 +41,11 @@ OPTIONS:
 
 对于完整的升级，您需要使用每个目标选项两次执行此工具。
 
-## 示例
+## 从 0.7.x 升级
 
 这一节将演示如何从 `v0.7.x` 升级到 `v0.8.0`。
 
-在下面的文本中，我们假设您的 Frontend 的 HTTP 端口为 `127.0.0.1:4000`。输出目录是 `/tmp/greptimedb-export`。
+在下面的文本中，我们假设您的数据库的 HTTP 端口为 `127.0.0.1:4000`。
 
 ### 导出 `CREATE TABLE`
 
@@ -67,25 +67,6 @@ greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export
 └── greptime-public.sql
 ```
 
-### 导出表数据
-
-```shell
-greptime cli export --addr '127.0.0.1:4000' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
-```
-
-日志输出与上面类似。输出目录的结构如下
-
-```plaintext
-/tmp/greptimedb-export
-├── greptime-public
-│   ├── up.parquet
-│   └── other-tables.parquet
-├── greptime-public_copy_from.sql
-└── greptime-public.sql
-```
-
-新的内容是 `greptime-public_copy_from.sql` 和 `greptime-public`。前者包含每个表的 `COPY FROM` 语句。后者包含每个表的数据。
-
 ### 处理 Breaking Changes
 :::warning 注意
 从版本 0.7.x 升级时存在已知的 Breaking Changes。您需要手动编辑导出的 SQL 文件（即 /tmp/greptimedb-export/greptime-public.sql）
@@ -101,7 +82,7 @@ CREATE TABLE foo (
     TIME INDEX (ts),
     PRIMARY KEY(host)
 ) ENGINE=mito 
-WITH(
+WITH( # 删除
     regions=1
 );
 ```
@@ -149,7 +130,7 @@ CREATE TABLE IF NOT EXISTS "phy" (
   "__tsid" BIGINT UNSIGNED NOT NULL,
   "host" STRING NULL,
   "job" STRING NULL,
-  PRIMARY KEY ("__table_id", "__tsid", "host", "job")
+  PRIMARY KEY ("__table_id", "__tsid", "host", "job") # 修改此处
 )
 ENGINE=metric
 WITH(
@@ -199,14 +180,62 @@ CREATE TABLE IF NOT EXISTS "phy" (
   "host" STRING NULL,
   "job" STRING NULL,
   PRIMARY KEY ("host", "job")
-  TIME INDEX ("ts")
+  TIME INDEX ("ts") # 添加在此处
 )
 ENGINE=metric
 WITH(
   physical_metric_table = ''
 );
 ```
 
+#### 为 InfluxDB 协议的表更新建表语句
+
+相关 [issue](https://github.com/GreptimeTeam/greptimedb/pull/3794)
+
+修改前:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+  "ts" TIMESTAMP(6) NOT NULL, # 修改此处
+  "val" DOUBLE NULL,
+  "host" STRING NULL,
+  "job" STRING NULL,
+  PRIMARY KEY ("host", "job"),
+  TIME INDEX ("ts")
+)
+ENGINE=mito;
+```
+
+修改后:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+  "ts" TIMESTAMP(9) NOT NULL,
+  "val" DOUBLE NULL,
+  "host" STRING NULL,
+  "job" STRING NULL,
+  PRIMARY KEY ("host", "job"),
+  TIME INDEX ("ts")
+)
+ENGINE=mito;
+```
+
+### 导出表数据
+
+```shell
+greptime cli export --addr '127.0.0.1:4000' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
+```
+
+日志输出与上面类似。输出目录的结构如下
+
+```plaintext
+/tmp/greptimedb-export
+├── greptime-public
+│   ├── up.parquet
+│   └── other-tables.parquet
+├── greptime-public_copy_from.sql
+└── greptime-public.sql
+```
+
+新的内容是 `greptime-public_copy_from.sql` 和 `greptime-public`。前者包含每个表的 `COPY FROM` 语句。后者包含每个表的数据。
 
 ### 导入表结构和数据
 
@@ -232,6 +261,14 @@ psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptime-public.sql
 psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptime-public_copy_from.sql
 ```
 
+### 已知问题
+
+#### 升级工具依然会导出 0.7.0 中的物理表数据
+在将 v0.7.0 的数据导入至 v0.8.0 时，数据库可能会出现以下错误。可直接忽略，该错误并不会影响数据的完整性。
+```
+psql:/tmp/greptimedb-export/greptime-public_copy_from.sql:2: ERROR:  Alter request to physical region is forbidden
+```
+
 ### 清理
 
 到这一步，所有的数据都已经迁移完毕。您可以在新集群中检查数据。
@@ -242,10 +279,10 @@ psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptime-public_copy_from.sql
 
 该部分给出了一个推荐的整体流程，以便平滑升级 GreptimeDB。如果您的环境可以在升级过程中离线，可以跳过此部分。
 
-1. 创建一个全新的 v0.4 集群 
-2. 导出并导入 `create-table`
+1. 创建一个全新的 v0.8.0 集群 
+2. 使用 v0.8.0 版本的 cli 工具导出并导入 `create-table`
 3. 将工作负载切换到新集群
-4. 导出并导入 `table-data`
+4. 使用 v0.8.0 版本的 cli 工具导出并导入 `table-data`
 
 注意