版本升级
概览
本指南提供 GreptimeDB 的升级说明,包括每个版本的兼容性信息和破坏性变更。升级前,请确保查看与你的升级路径相关的破坏性变更。
升级时,请查看当前版本之后、直到目标版本为止的各版本变更。查看中间版本的变更 不代表必须逐个安装这些版本;实际升级步骤请遵循下方支持的升级路径。
完整的版本历史和功能新增,请参见发行说明。
升级到 v1.3 的路径
从 v1.2 到 v1.3
如果你当前运行的是 v1.2,可以直接升级到 v1.3。升级前,请先查看 从 v1.2 升级到 v1.3,并完成 升级检查清单中的相关检查。
从 v1.1 或更早版本到 v1.3
如果你要从 v1.1 或更早版本升级到 v1.3,请先查看升级到 v1.2 的路径, 再处理 v1.3 的破坏性变更。
升级到 v1.2 的路径
从 v1.0 或 v1.1 到 v1.2
如果你当前运行的是 v1.0 或 v1.1,可以直接升级到 v1.2。升级前,请先查看 从 v1.0 或 v1.1 升级到 v1.2,并完成 升级检查清单中的相关检查。 如果当前版本是 v1.0,还需查看 v1.1 的 Metric Engine 变更。
从 v0.17 或更早版本到 v1.2
如果你要从 v0.17 或更早版本升级到 v1.2,请先查看下方适用的 v1.0 升级路径, 再处理 v1.2 的破坏性变更。
如果使用 Metric Engine,还需查看 v1.0 的压缩建议 和 v1.1 的 Metric Engine 变更。
升级到 v1.0 的路径
从 v0.16 到 v1.0
如果你当前运行的是 v0.16,可以直接升级到 v1.0。请参见从 v0.16 升级到 v1.0 了解所有相关的破坏性变更。
从 v0.17 到 v1.0
如果你当前运行的是 v0.17,可以直接升级到 v1.0。请参见从 v0.17 升级到 v1.0 了解破坏性变更。
从更早版本升级
重要提示: 本指南仅涵盖从 v0.16 及更高版本的升级。
如果你运行的版本早于 v0.16,必须先按照当前版本的升级文档升级到 v0.16。成功升级到 v0.16 后,再使用本指南升级到 v1.0。
各版本的破坏性变更
升级到 v1.3.1
以下变更从 v1.3.1 开始生效。从 v1.2 或更早版本升级时,还需完成 v1.3 的升级检查。
OTLP 日志表
自动创建的新日志表采用 greptime_log_v1,已有表保留原有映射。全部写入 Frontend 升级完成后,通过 X-Greptime-Log-Table-Name 指定新表以采用新 schema。避免新旧 Frontend 或 CREATE TABLE 并发创建同一张表。
Prometheus Remote Read
检查表中是否有非字符串标签列,Remote Read 会拒绝这类表;时间戳列和样本值列除外。按完整字符串和空标签匹配规则检查选择器。
数据库选择和管理权限
HTTP 请求覆盖数据库选择,以及 MySQL/PostgreSQL 的数据库选择操作,均检查访问权限。检查客户端的数据库名称和授权:
- MySQL 未选择可用数据库时,依赖数据库选择的语句返回错误
1046。执行前需选择有访问权限的数据库。 - PostgreSQL
SET search_path选择第一个存在且有访问权限的数据库;没有符合条件的数据库时,清除当前选择。 - 管理函数需要
ADMIN权限,通过SELECT调用时也会检查。检查调用脚本的权限。
JSON 日志解析
JSON 解析错误按 ignore_errors 策略处理,skip_error 单独控制 Pipeline 执行错误。按日志 API检查写入端的错误处理。
分布式部署和写入重试
保持 Datanode 时钟同步,复用节点 ID 前先停止旧进程。全部 Metasrv 节点升级后,进程 fencing 才完全生效。
写入在追加 WAL 期间遇到 leader lease 过期时,可能在已应用后返回可重试错误。向 append-only 表重试写入时,需处理可能产生的重复行。
手动配置的 sparse 主键
升级前,按受支持的 schema检查设置了 primary_key_encoding = 'sparse' 或旧选项 memtable.partition_tree.primary_key_encoding = 'sparse' 的表。不符合要求的 schema 可能在 schema 变更或重新打开时校验失败。升级前需测试迁移到受支持的配置;数据和主键编码不会自动迁移。由 Metric Engine 正常管理的表和普通 dense 表不受影响。
凭据脱敏
诊断配置和启动日志会对凭据脱敏或省略凭据。保留原始配置和密钥用于恢复,诊断输出不能用作凭据备份。
从 v1.2 升级到 v1.3
集群升级和回滚顺序
整个滚动升级期间保持 Metasrv 维护模式开启,全部组件升级完成后再关闭。v1.3 的 Batch GC 使用 packed 协议,不支持向旧协议回退;维护模式可防止它在 Metasrv 与 Datanode 版本混用时运行。
先升级全部 Datanode,再升级 Frontend。回滚时先回滚 Frontend,再回滚 Datanode;通过 Operator 管理的回滚也需要遵循此顺序。 v1.3 Frontend 的写入重试依赖 Datanode 返回逐条写入结果,与旧 Datanode 混用时可能重放已成功的写入,导致 append-mode 表出现重复行。v1.3 的 PromQL 执行计划也会使用旧 Datanode 不支持的函数。
查询和客户端兼容性
| 变化 | 升级前检查 |
|---|---|
| MySQL 文本协议将时间戳的小数秒截断到微秒;存储的纳秒值不变。 | 需要完整纳秒精度的客户端应在 SQL 中显式转换为字符串或整数。 |
| 未指定步长的 PromQL 子查询使用固定的 1 分钟步长。 | 需要其他步长时显式使用 [range:step]。 |
| PromQL 范围查询拒绝 range-vector 根表达式。 | 改用瞬时查询,或先将 range vector 归约为 instant vector。 |
整数输入的 median、approx_median 和 approx_percentile_cont 返回浮点数;精确中位数对偶数个输入插值。 | 检查视图、Flow 输出表及其他固定 schema 消费方的类型。 |
REPLACE(s, '', replacement) 返回原字符串;struct unnest 自动生成的列名发生变化。 | 检查空匹配字符串的用法,并为展开列指定别名。 |
PostgreSQL 结果元数据返回 REGCLASS、REGTYPE 等 OID 别名。 | 检查客户端对结果类型的处理。 |
json_get* 和 JSON2 字段访问遇到非法 JSONPath 时返回错误。 | 根路径可使用 $ 或空字符串;替换 .、$. 等非法路径。json_path_match 对非法路径仍返回 NULL。 |
SQL 表达式深度超过 128 时规划失败。 | 简化深度嵌套的生成式查询。 |
PromQL 向量匹配根据 on、ignoring、group_left 和 group_right 推导结果标签。若某个匹配组在要求唯一的一侧有多条序列,或匹配后产生重复的结果序列,查询会失败。不带 bool 的比较运算会保留 __name__,但未列出 __name__ 的一对一 on(...) 匹配除外。 | 检查使用向量匹配的查询、recording rule 和告警标签模板。 |
service.namespace 非空的 OTLP 指标使用 job="<service.namespace>/<service.name>",不再只使用 service.name 的值。即使禁用 otlp.experimental_enable_resource_info,该变化同样生效。已有数据不会重新打标签。 | 更新仪表盘选择器和告警规则。跨越升级时间点的查询可能需要同时匹配新旧两种标签值。 |
Prometheus HTTP API 样本字符串
Prometheus HTTP API 返回的样本值字符串格式可能变化,例如 "1" 变为 "1.0",但有限浮点数的数值不变。
依赖字符串比较的客户端和快照测试应改为先解析样本值,再比较数值。
OTLP 增量指标和保留的 temporality 标签
升级前应检查 OTLP 属性名是否与保留标签 otlp_aggregation_temporality 冲突。
向固定表结构写入增量指标时,还需满足表结构和标签要求。
如果已有浮点序列带有 otlp_aggregation_temporality="delta" 标签,升级后的 rate() 和 increase()
会按增量值计算,包括通过其他协议写入的数据。
升级前应检查这些序列的标签和查询;修改后续写入不会改变已存储的标签。
分区列的类型变更
升级前应检查涉及分区列类型变更的脚本。持久化分区表达式中使用的列不允许修改类型, 但可以提高时间戳精度,前提是所有分区边界均未超出新单位可表示的范围。 修改前应同时检查已有时间戳和分区边界是否超出范围,具体限制见修改列类型。
写入请求和 JSON2
Prometheus Remote Read、Remote Write 和 Loki protobuf/Snappy push 请求的解压后正文超过 512 MiB 时返回 HTTP 400。该解压限制不适用于 Loki JSON push 路径。
配置 max_in_flight_write_bytes 后,HTTP 准入还会计入解码后的正文和超出 Content-Length 的流式数据;配额不足时返回 HTTP 429 或 gRPC RESOURCE_EXHAUSTED。
压缩的 gRPC 请求在解码前按 max_recv_message_size 预留配额。按解压后的大小调整客户端批次和服务端配额。
JSON2 type hint 不再接受 nullable 和 default。指定类型的字段均可为 NULL,缺失值返回 NULL。
支持的类型为 STRING、BIGINT、BIGINT UNSIGNED、DOUBLE、BOOLEAN,以及别名 INT64、UINT64、FLOAT64。移除旧选项,并替换不受支持的类型。
JSON2 使用 flat SST;CREATE 和 ALTER 拒绝不兼容的 SST 格式。
Bulk 写入(包括 Arrow Flight DoPut)在写入 WAL 前按 region schema 校验。Arrow 类型不匹配、非空列含 NULL、列重复或列不存在的批次会被拒绝。
主键格式 SST 的 region 以前会转换部分数据表示,例如字符串字段使用 LargeUtf8、二进制字段使用 LargeBinary、时间戳带时区等,这类批次现在会被拒绝。每列都应使用 region 声明的 Arrow 类型发送。
Bulk 写入不支持 JSON2 列,这类批次在写入 WAL 前被拒绝。
Flow 镜像写入限制
Flow 镜像写入的待处理预算为 1,000,000 行,发往不同 Flownode 的副本分别计数。
达到预算时,普通表写入仍可能成功,但对应的 Flow 镜像批次会被丢弃,造成 Flow 输出缺失。
instant-TTL 写入在向 Datanode 发送前被拒绝;单批超过预算时,需要拆分批次。
监控 greptime_table_operator_mirror_pending_rows 和 greptime_operator_dist_mirror_dropped_rows。
配置和索引
- Mito 的默认
auto_flush_interval从30m改为10m。显式配置的全局值和表级值保持不变。 - 移除旧的 native histogram 实验开关;这些开关会被忽略,包括设为
false的情况。将prom_validation_mode从[http]移到[prom_store],保留原值。旧位置的配置会被忽略,回退到默认值strict;原来使用lossy或unchecked的写入可能因此被拒绝。 - 流式查询分析默认启用,旧配置项
experimental_enable_explain_analyze_stream被忽略,可移除。 - 重复的 region engine 配置会导致启动失败;每种引擎只保留一份配置。
- 通过 compaction 或
ADMIN BUILD_INDEX重建旧 fulltext bloom 索引。数据仍可读取,但旧索引在重建前不参与剪枝。回滚后,v2 索引同样退回扫描。Tantivy 的matches_term使用全表扫描,matches()行为不变。
UDDSketch 状态兼容性
uddsketch_state 和 uddsketch_merge 生成新的二进制格式。v1.3 可读取旧状态,v1.2.1 无法读取新状态。
需要回滚时保留升级前的状态数据,并避免将新生成的状态传给旧版本读取端。
VRL 默认禁用主机访问
影响: 使用受限 VRL 函数或参数的 pipeline
从 v1.3.0 起,pipeline.allow_vrl_host_access 默认值为 false。
使用受限函数或参数的现有 pipeline 在升级后首次从存储加载时会编译失败,
导致使用这些 pipeline 的写入请求失败。
需要的操作:
- 检查现有 pipeline 是否使用了受限的 VRL 函数或参数。
- 在升级前移除受限调用或参数。如果所有 pipeline 作者都可信,也可以在所有
Frontend 或单机服务的
[pipeline]配置中设置allow_vrl_host_access = true, 并重启相关服务。 - 在正式升级前,使用目标版本和计划采用的服务端配置,通过
POST /v1/pipelines/_dryrun验证受影响的 pipeline。
扫描内存计量变更
升级到 v1.3 后,即使配置没有修改,查询也可能因达到内存限制而失败。 升级前请检查以下设置:
| 现有配置 | 变化及建议操作 |
|---|---|
未配置 scan_memory_limit | 默认值从 unlimited 改为可用内存的 25%,并遵循容器内存限制。如需继续禁用扫描内存限制,请显式设为 "unlimited"。 |
已配置非零 scan_memory_limit | 新增的 scan_memory_mode 默认为 basic。如需继续统计扫描产生的批次,请使用 extended,并测试现有限制是否足够。 |
scan_memory_on_exhausted = "wait" 或 "wait(<duration>)" | 查询会立即失败,不再等待内存。请改为 "fail",并检查应用的错误处理逻辑。 |
extended 不会完全恢复旧行为:相同的限制可能导致以前能够成功的查询失败。
同时检查 query.memory_pool_size,因为查询现在可能更容易达到这一限制。
将 scan_memory_limit 设为 0 或 "unlimited" 仍然只会禁用扫描内存限制,
不会禁用查询内存限制或文件数量检查。
正式升级前,请按预期并发量测试典型查询,并检查使用
greptime_mito_scan_memory_usage_bytes 的告警。该指标不代表进程总内存。
配置详情见扫描内存计量。
从 v1.0 或 v1.1 升级到 v1.2
移除 PromQL holt_winters
影响: PromQL 查询解析
holt_winters 这个名字已被移除。它只是为向后兼容保留的别名,函数本身没有变化,
仍然可以通过 double_exponential_smoothing 使用 —— 这个名字在 v1.2 之前就已经
支持。
需要的操作:
-
在仪表盘、录制规则、告警规则和 API 调用方中搜索
holt_winters( -
把每处调用改名为
double_exponential_smoothing(...),参数和结果完全一致:# v1.2 之前
holt_winters(prom_series[10s], 0.5, 0.1)
# v1.2 及之后
double_exponential_smoothing(prom_series[10s], 0.5, 0.1) -
修改后在预发环境重新执行这些查询
拒绝 fill、fill_left 和 fill_right PromQL 修饰符
影响: 为避免错误查询计划而收紧 PromQL 兼容性
v1.2 升级了 PromQL 解析器,二元运算符修饰符 fill、fill_left 和 fill_right
因此首次在语法上变得合法,例如 metric_a + fill(0) metric_b。GreptimeDB 并未
实现它们所需的 outer join 语义,因此会直接拒绝这类用法(无论是直接使用还是嵌套
使用),而不是把它们当作普通的 inner join 来规划。
更早的版本根本无法解析这些修饰符,所以 v1.2 之前能正常工作的查询都不受影响。
这也与 SQL 的 RANGE ... FILL 子句无关,后者没有变化。
需要的操作:
- 在 PromQL 表达式中搜索
fill(、fill_left(和fill_right( - 重写受影响的查询,使其不再依赖这些修饰符
Pipeline 整数缩窄现在遵循 on_failure
影响: Pipeline 类型转换正确性
当 pipeline 把整型输入或数字字符串转换为无法容纳该值的声明整型时,该值不再按
模运算回绕,而是遵循该转换的 on_failure 策略。此前 -1 写入 uint8 会存成
255,256 写入 int8 会存成 0。
这适用于 int8、int16、int32、uint8、uint16 和 uint32,也适用于写入
int64 和 uint64 时的跨符号转换。本次发布中,浮点数转整数的行为保持不变。
需要的操作:
- 检查会写入窄整数类型字段的 pipeline,以及可能把负值写入无符号类型的 pipeline
- 如果这些 pipeline 依赖了回绕行为,请在升级前扩大目标类型,或显式配置
on_failure策略 - 使用
POST /v1/pipelines/_dryrun或有代表性的预发数据,验证边界值现在会 产生预期的错误、默认值或 null 结果
本地 SQL 文件访问现在受沙箱限制
影响: 读写本地文件的 COPY 与外部表工作流
单机部署现在会把本地 SQL 文件路径解析到 storage.copy_root
(默认 <data_home>/copy)之内;分布式部署则完全拒绝本地文件 SQL 访问。
需要的操作:
- 识别引用本地路径的
COPY语句和外部表 - 如果你使用单机部署,请将这些文件移动到沙箱目录下,或把
storage.copy_root指向专用目录,或将工作流迁移到对象存储 - 如果你运行的是分布式服务,请在升级前把本地文件工作流迁移到 S3、OSS、 GCS 或 AzBlob
- 详细迁移步骤请参见迁移本地 SQL 文件访问
移除 sparse_primary_key_encoding 配置
影响: Metric engine 配置清理
GreptimeDB 现在始终为 metric 表使用稀疏主键编码,sparse_primary_key_encoding
选项已被移除。配置文件中若仍保留该项,不会导致启动失败,该项会被忽略。
需要的操作:
- 从配置文件、Helm values 和自动化模板的
[region_engine.metric]块中移除sparse_primary_key_encoding。如果更早的experimental_sparse_primary_key_encoding还在,也一并删掉。 - 如果你之前设置过
sparse_primary_key_encoding = false,请注意 v1.2 已经不再提供关闭该行为的选项 - 使用清理后的配置在预发环境重启一次,确认部署已不再依赖这些被移除的设置