From f5d1f072fa6d3d940af3bdd8d34f537e662f5de6 Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Thu, 16 May 2024 16:11:19 +0900 Subject: [PATCH] docs: update upgrade doc (#958) Co-authored-by: Yiran --- docs/auto-imports.d.ts | 1 - docs/nightly/en/reference/sql/create.md | 1 - docs/nightly/en/user-guide/upgrade.md | 131 +++++++++++++++++++++++- docs/nightly/zh/reference/sql/create.md | 1 - docs/nightly/zh/user-guide/upgrade.md | 130 ++++++++++++++++++++++- 5 files changed, 252 insertions(+), 12 deletions(-) diff --git a/docs/auto-imports.d.ts b/docs/auto-imports.d.ts index cb9b8ec01..e0efe2bfd 100644 --- 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 index 9ac6d988b..1c4d282a8 100644 --- 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 index 80c69cdaa..ff6fa17e1 100644 --- 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 index f1a9aafcd..4e54a07f4 100644 --- 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 index 94f4d81f8..9e95545e9 100644 --- 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`。