docs: update upgrade doc (#958)

Co-authored-by: Yiran <cuiyiran3@gmail.com>
GreptimeTeam · May 16, 2024 · f5d1f07 · f5d1f07
1 parent cfa2a47
commit f5d1f07
Show file tree

Hide file tree

Showing 5 changed files with 252 additions and 12 deletions.
diff --git a/docs/auto-imports.d.ts b/docs/auto-imports.d.ts
@@ -1,7 +1,6 @@
 /* eslint-disable */
 /* prettier-ignore */
 // @ts-nocheck
-// noinspection JSUnusedGlobalSymbols
 // Generated by unplugin-auto-import
 export {}
 declare global {

diff --git a/docs/nightly/en/reference/sql/create.md b/docs/nightly/en/reference/sql/create.md
@@ -84,7 +84,6 @@ Users can add table options by using `WITH`. The valid options contain the follo
 | Option | Description | Value |
 | ------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ttl` | The storage time of the table data | String value, such as `'60m'`, `'1h'` for one hour, `'14d'` for 14 days etc. Supported time units are: `s` / `m` / `h` / `d` |
-| `regions` | The region number of the table | Integer value, such as 1, 5, 10 etc. |
 | `storage` | The name of the table storage engine provider | String value, such as `S3`, `Gcs`, etc. It must be configured in `[[storage.providers]]`, see [configuration](/user-guide/operations/configuration#storage-engine-provider). |
 | `compaction.type` | Compaction strategy of the table | String value. Only `twcs` is allowed. |
 | `compaction.twcs.max_active_window_files` | Max num of files that can be kept in active writing time window | String value, such as '8'. Only available when `compaction.type` is `twcs`. You can refer to this [document](https://cassandra.apache.org/doc/latest/cassandra/managing/operating/compaction/twcs.html) to learn more about the `twcs` compaction strategy. |

diff --git a/docs/nightly/en/user-guide/upgrade.md b/docs/nightly/en/user-guide/upgrade.md
@@ -41,16 +41,15 @@ Here explains the meaning of some important options
 
 For a complete upgrade, you will need to execute this tools twice with each target options.
 
-## Example
+## Upgrade from 0.7.x
 
-Here is a complete example for upgrading from `v0.3.0` to `v0.4.0`.
+Here is a complete example for upgrading from `v0.7.x` to `v0.8.0`.
 
-In the following text, we assume that you have a Frontend's gRPC endpoint is available at `127.0.0.1:4001`. The output dir is `/tmp/greptimedb-export`.
 
 ### Export `CREATE TABLE`
 
 ```shell
-greptime cli export --addr '127.0.0.1:4001' --output-dir /tmp/greptimedb-export --target create-table
+greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export --target create-table
 ```
 
 If success, you will see something like this
@@ -67,10 +66,132 @@ And now the output directory structure is
 └── greptime-public.sql
 ```
 
+### Handle Breaking Changes
+:::warning NOTICE
+There are known breaking changes when attempting to upgrade from version 0.7.x.
+**You need to manually edit the exported SQL files (i.e., `/tmp/greptimedb-export/greptime-public.sql`). **
+:::
+
+#### Remove `regions` option in `WITH` clause
+
+Before:
+```sql
+CREATE TABLE foo (
+ host string,
+ ts timestamp DEFAULT '2023-04-29 00:00:00+00:00',
+ TIME INDEX (ts),
+ PRIMARY KEY(host)
+) ENGINE=mito 
+WITH(
+ regions=1
+);
+```
+
+After:
+```sql
+CREATE TABLE foo (
+ host string,
+ ts timestamp DEFAULT '2023-04-29 00:00:00+00:00',
+ TIME INDEX (ts),
+ PRIMARY KEY(host)
+) ENGINE=mito;
+```
+
+#### Rewrite the partition rule
+
+Before:
+```sql
+PARTITION BY RANGE COLUMNS (n) (
+ PARTITION r0 VALUES LESS THAN (1),
+ PARTITION r1 VALUES LESS THAN (10),
+ PARTITION r2 VALUES LESS THAN (100),
+ PARTITION r3 VALUES LESS THAN (MAXVALUE),
+)
+```
+
+After:
+```sql
+PARTITION ON COLUMNS (n) (
+ n < 1,
+ n >= 1 AND n < 10,
+ n >= 10 AND n < 100,
+ n >= 100
+)
+```
+
+#### Remove the internal columns
+
+Before:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "__table_id" INT UNSIGNED NOT NULL,
+ "__tsid" BIGINT UNSIGNED NOT NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("__table_id", "__tsid", "host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = '',
+ regions = 1
+);
+```
+
+After:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+#### Add missing Time Index constraint
+
+Before:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+After:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+ TIME INDEX ("ts")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+
 ### Export table data
 
 ```shell
-greptime cli export --addr '127.0.0.1:4001' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
+greptime cli export --addr '127.0.0.1:4000' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
 ```
 
 The log output is similar to the previous one. And the output directory structure is

diff --git a/docs/nightly/zh/reference/sql/create.md b/docs/nightly/zh/reference/sql/create.md
@@ -85,7 +85,6 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name
 | 选项 | 描述 | 值 |
 | ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ttl` | 表数据的存储时间 | 字符串值，例如 `'60m'`, `'1h'` 代表 1 小时， `'14d'` 代表 14 天等。支持的时间单位有：`s` / `m` / `h` / `d` |
-| `regions` | 表的 region 值 | 整数值，例如 1, 5, 10 etc. |
 | `storage` | 自定义表的存储引擎，存储引擎提供商的名字 | 字符串，类似 `S3`、`Gcs` 等。 必须在 `[[storage.providers]]` 列表里配置, 参考 [configuration](/user-guide/operations/configuration#存储引擎提供商)。 |
 | `compaction.type` | Compaction 策略 | 字符串值. 只支持 `twcs`。你可以阅读这篇[文章](https://cassandra.apache.org/doc/latest/cassandra/managing/operating/compaction/twcs.html)来了解 `twcs` compaction 策略 |
 | `compaction.twcs.max_active_window_files` | 当前活跃时间窗口内的最大文件数 | 字符串值，如 '8'。只在 `compaction.type` 为 `twcs` 时可用 |

diff --git a/docs/nightly/zh/user-guide/upgrade.md b/docs/nightly/zh/user-guide/upgrade.md
@@ -43,14 +43,14 @@ OPTIONS:
 
 ## 示例
 
-这一节将演示如何从 `v0.3.0` 升级到 `v0.4.0`。
+这一节将演示如何从 `v0.7.x` 升级到 `v0.8.0`。
 
-在下面的文本中，我们假设您的 Frontend 的 gRPC 端口为 `127.0.0.1:4001`。输出目录是 `/tmp/greptimedb-export`。
+在下面的文本中，我们假设您的 Frontend 的 HTTP 端口为 `127.0.0.1:4000`。输出目录是 `/tmp/greptimedb-export`。
 
 ### 导出 `CREATE TABLE`
 
 ```shell
-greptime cli export --addr '127.0.0.1:4001' --output-dir /tmp/greptimedb-export --target create-table
+greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export --target create-table
 ```
 
 如果成功，您将看到类似于以下内容的输出
@@ -70,7 +70,7 @@ greptime cli export --addr '127.0.0.1:4001' --output-dir /tmp/greptimedb-export
 ### 导出表数据
 
 ```shell
-greptime cli export --addr '127.0.0.1:4001' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
+greptime cli export --addr '127.0.0.1:4000' --database greptime-public --output-dir /tmp/greptimedb-export --target table-data
 ```
 
 日志输出与上面类似。输出目录的结构如下
@@ -86,6 +86,128 @@ greptime cli export --addr '127.0.0.1:4001' --database greptime-public --output-
 
 新的内容是 `greptime-public_copy_from.sql` 和 `greptime-public`。前者包含每个表的 `COPY FROM` 语句。后者包含每个表的数据。
 
+### 处理 Breaking Changes
+:::warning 注意
+从版本 0.7.x 升级时存在已知的 Breaking Changes。您需要手动编辑导出的 SQL 文件（即 /tmp/greptimedb-export/greptime-public.sql）
+:::
+
+#### 删除 `WITH` 从句中的 `regions` 选项
+
+修改前:
+```sql
+CREATE TABLE foo (
+ host string,
+ ts timestamp DEFAULT '2023-04-29 00:00:00+00:00',
+ TIME INDEX (ts),
+ PRIMARY KEY(host)
+) ENGINE=mito 
+WITH(
+ regions=1
+);
+```
+
+修改后:
+```sql
+CREATE TABLE foo (
+ host string,
+ ts timestamp DEFAULT '2023-04-29 00:00:00+00:00',
+ TIME INDEX (ts),
+ PRIMARY KEY(host)
+) ENGINE=mito;
+```
+
+#### 重写分区规则
+
+修改前:
+```sql
+PARTITION BY RANGE COLUMNS (n) (
+ PARTITION r0 VALUES LESS THAN (1),
+ PARTITION r1 VALUES LESS THAN (10),
+ PARTITION r2 VALUES LESS THAN (100),
+ PARTITION r3 VALUES LESS THAN (MAXVALUE),
+)
+```
+
+修改后:
+```sql
+PARTITION ON COLUMNS (n) (
+ n < 1,
+ n >= 1 AND n < 10,
+ n >= 10 AND n < 100,
+ n >= 100
+)
+```
+
+#### 删除内部列
+
+修改前:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "__table_id" INT UNSIGNED NOT NULL,
+ "__tsid" BIGINT UNSIGNED NOT NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("__table_id", "__tsid", "host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = '',
+ regions = 1
+);
+```
+
+修改后:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+
+#### 添加缺失的 Time Index 约束
+
+修改前:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+修改后:
+```sql
+CREATE TABLE IF NOT EXISTS "phy" (
+ "ts" TIMESTAMP(3) NOT NULL,
+ "val" DOUBLE NULL,
+ "host" STRING NULL,
+ "job" STRING NULL,
+ PRIMARY KEY ("host", "job")
+ TIME INDEX ("ts")
+)
+ENGINE=metric
+WITH(
+ physical_metric_table = ''
+);
+```
+
+
 ### 导入表结构和数据
 
 然后您需要执行上一步生成的 SQL 文件。首先是 `greptime-public.sql`。在之前的步骤中导出的 SQL 语句使用的是 PostgreSQL 方言，接下来的操作都将通过 [PG 协议](/user-guide/clients/postgresql.md)来进行。本文档假设客户端为 `psql`。