TimescaleDB从1.7.5升级至2.x版本报错问题咨询

核心问题 #

TimescaleDB 1.x到2.x属于大版本迭代，没有直接的跨版本升级路径，必须按官方要求的阶梯式升级：先升到1.x分支的最终稳定版，再过渡到2.x的首个兼容版本，最后升级到最新版。你遇到的ping_data_node函数不存在、无升级路径报错，都是因为跳过了中间过渡版本导致的。

无数据丢失的升级步骤 #

步骤1：升级到1.x分支最终稳定版（1.7.6）

1. 停止当前容器：

   docker stop <你的PostgreSQL容器名>
   

2. 拉取匹配PostgreSQL 12的TimescaleDB 1.7.6镜像：

   docker pull timescale/timescaledb:1.7.6-pg12
   

3. 用新镜像启动容器，挂载原有数据卷（确保数据目录映射和原容器一致）：

   docker run -d \
     --name timescaledb-1.7.6 \
     -v <你的数据卷路径>:/var/lib/postgresql/data \
     -e POSTGRES_PASSWORD=<你的数据库密码> \
     timescale/timescaledb:1.7.6-pg12
   

4. 进入容器执行扩展升级：

   docker exec -it timescaledb-1.7.6 psql -U postgres
   

   在SQL终端执行：

   ALTER EXTENSION timescaledb UPDATE TO '1.7.6';
   

   验证版本：

   SELECT extversion FROM pg_extension WHERE extname='timescaledb';
   

   确认输出为1.7.6即可。

步骤2：升级到2.x首个兼容过渡版本（2.1.1）

1. 停止1.7.6版本容器：

   docker stop timescaledb-1.7.6
   

2. 拉取对应镜像：

   docker pull timescale/timescaledb:2.1.1-pg12
   

3. 启动新容器并挂载原数据卷：

   docker run -d \
     --name timescaledb-2.1.1 \
     -v <你的数据卷路径>:/var/lib/postgresql/data \
     -e POSTGRES_PASSWORD=<你的数据库密码> \
     timescale/timescaledb:2.1.1-pg12
   

4. 进入容器完成升级：

   docker exec -it timescaledb-2.1.1 psql -U postgres
   

   执行SQL：

   ALTER EXTENSION timescaledb UPDATE TO '2.1.1';
   

   验证版本确认升级成功。

步骤3：升级到最新稳定版

1. 停止2.1.1版本容器，拉取PostgreSQL 12兼容的最新TimescaleDB镜像：

   docker pull timescale/timescaledb:latest-pg12
   

2. 启动容器并挂载原数据卷，进入SQL终端执行：

   ALTER EXTENSION timescaledb UPDATE;
   

   验证版本即可完成最终升级。

修复pg_dump/pg_restore失败的方案 #

如果之前用备份恢复失败，是因为1.x的备份包含2.x不兼容的系统对象，正确流程如下：

1. 在1.7.6版本容器中导出数据（排除系统权限和TimescaleDB内部对象）：

   docker exec timescaledb-1.7.6 pg_dump -U postgres -d <你的数据库名> --no-owner --no-privileges > db_dump.sql
   

2. 在新的2.x容器中创建空数据库，先初始化TimescaleDB扩展：

   CREATE DATABASE <新数据库名>;
   \c <新数据库名>
   CREATE EXTENSION timescaledb;
   

3. 导入备份数据：

   docker exec -i timescaledb-2.x psql -U postgres -d <新数据库名> < db_dump.sql
   

关键注意事项 #

• 所有操作前必须备份数据卷，可通过以下命令快速备份：

  docker volume create tsdb-backup
  docker run --rm -v <你的数据卷路径>:/src -v tsdb-backup:/dst busybox cp -a /src/. /dst/.
  

• 必须使用和PostgreSQL 12严格匹配的TimescaleDB镜像，不要跨PostgreSQL版本升级。
• 如果是分布式部署（含数据节点），需先升级所有数据节点，再升级访问节点，否则会出现ping_data_node函数不存在的报错。

内容的提问来源于stack exchange，提问作者vicky