故障排除

如果您在使用 TimescaleDB 时遇到问题，您可以尝试以下几件事。本节提供了一些常见错误的解决方案，以及输出有关您设置的诊断信息的方法。如果您需要更多指导，可以加入社区 Slack 群组 或在 TimescaleDB GitHub 上发布问题。

ALTER EXTENSION timescaledb UPDATE 命令必须是连接到数据库后执行的第一个命令。某些管理工具会在之前执行命令，这可能会中断该过程。您可能需要使用 psql 手动更新数据库。有关详细信息，请参阅更新文档。

如果您的 PostgreSQL 日志有此错误阻止其启动，您应该仔细检查 TimescaleDB 文件是否已安装到正确的位置。安装方法使用 pg_config 获取 PostgreSQL 的位置。但是，如果您在同一台机器上安装了多个版本的 PostgreSQL，则 pg_config 指向的位置可能不是您期望的版本。要检查 TimescaleDB 使用的版本

$ pg_config --version
PostgreSQL 12.3

复制

如果那是正确的版本，请仔细检查安装路径是否是您期望的路径。例如，对于通过 Homebrew 在 macOS 上安装的 PostgreSQL 11.0，它应该是 /usr/local/Cellar/postgresql/11.0/bin

$ pg_config --bindir
/usr/local/Cellar/postgresql/11.0/bin

复制

如果这些步骤中的任何一个都不是您期望的版本，您需要卸载不正确的 PostgreSQL 版本（如果可以），或者更新您的 PATH 环境变量，将正确的 pg_config 路径放在最前面，即通过预先添加完整路径

export PATH = /usr/local/Cellar/postgresql/11.0/bin:$PATH

复制

然后，重新安装 TimescaleDB，它应该会找到正确的安装路径。

如果错误在更新 TimescaleDB 版本后立即发生，并且提到的文件来自以前的版本，则可能是由于更新过程不完整。在更大的 PostgreSQL 服务器实例中，每个安装了 TimescaleDB 的数据库都需要使用 SQL 命令 ALTER EXTENSION timescaledb UPDATE; 进行更新，同时连接到该数据库。否则，数据库会查找以前版本的 timescaledb 文件。

有关更多信息，请参阅我们的更新文档。

您的计划任务可能会因各种原因停止运行。在自托管的 TimescaleDB 上，您可以通过重启后台工作进程来解决此问题

SELECT _timescaledb_internal.restart_background_workers();

复制

在 Timescale 和 TimescaleDB 托管服务上，通过执行以下操作之一来重启后台工作进程

• 运行 SELECT timescaledb_pre_restore()，然后运行 SELECT timescaledb_post_restore()。
• 关闭并重新启动服务。这可能会导致几分钟的停机时间，因为服务会从备份恢复并重放预写式日志。

如果后台工作进程配置不正确，您可能会在日志中看到此错误消息

"<TYPE_OF_BACKGROUND_JOB>": failed to start a background worker

复制

要修复此错误，请确保正确设置了 max_worker_processes、max_parallel_workers 和 timescaledb.max_background_workers。timescaledb.max_background_workers 应该等于数据库的数量加上并发后台工作进程的数量。max_worker_processes 应该等于 timescaledb.max_background_workers 和 max_parallel_workers 的总和。

有关更多信息，请参阅工作进程配置文档。

如果您在尝试压缩数据块时看到此错误消息，则可能是压缩超级表的权限已损坏。

tsdb=> SELECT compress_chunk('_timescaledb_internal._hyper_65_587239_chunk');
ERROR: role 149910 was concurrently dropped

复制

如果您在 TimescaleDB 2.5 之前删除了超级表的用户，则可能会导致这种情况。在这种情况下，用户将从 pg_authid 中删除，但不会从压缩表中撤销。

因此，压缩表包含引用数值而不是现有用户的权限项（请参阅下文了解如何从普通超级表查找压缩超级表）

tsdb=> \dp _timescaledb_internal._compressed_hypertable_2
                                 Access privileges
 Schema |     Name     | Type  |  Access privileges  | Column privileges | Policies
--------+--------------+-------+---------------------+-------------------+----------
 public | transactions | table | mats=arwdDxt/mats  +|                   |
        |              |       | wizard=arwdDxt/mats+|                   |
        |              |       | 149910=r/mats       |                   |
(1 row)

复制

这意味着需要更新 pg_class 的 relacl 列并删除有问题的用户，但是无法通过数值删除用户。相反，您可以使用 _timescaledb_function 模式中的内部函数 repair_relation_acls

tsdb=> CALL _timescaledb_functions.repair_relation_acls();

复制

警告

这需要超级用户权限（因为您正在修改 pg_class 表），并且它会从所有表中删除 pg_authid 中不存在的任何用户，因此请谨慎使用。

超级表的权限通常也会损坏，但并非总是如此，因此最好查看压缩超级表以查看是否存在问题。要查找与关联的超级表（在本例中为 readings）对应的压缩超级表

tsdb=> select ht.table_name,
tsdb->        (select format('%I.%I', schema_name, table_name)::regclass
tsdb->           from _timescaledb_catalog.hypertable
tsdb->          where ht.compressed_hypertable_id = id) as compressed_table
tsdb->   from _timescaledb_catalog.hypertable ht
tsdb->  where table_name = 'readings';
  format  |                     format
----------+------------------------------------------------
 readings | _timescaledb_internal._compressed_hypertable_2
(1 row)

复制

PostgreSQL 的 EXPLAIN 功能允许用户了解 PostgreSQL 用于执行查询的底层查询计划。PostgreSQL 可以通过多种方式执行查询：例如，查询可以使用慢速顺序扫描或更高效的索引扫描来完成。计划的选择取决于在表上创建了哪些索引、PostgreSQL 拥有的关于您数据的统计信息以及各种计划器设置。EXPLAIN 输出让您知道 PostgreSQL 为特定查询选择的计划。PostgreSQL 有一个关于此功能的深入解释。

要了解超级表的查询性能，我们建议首先通过运行 VACUUM ANALYZE <your-hypertable>; 来确保计划器统计信息和表维护在超级表上是最新的。然后，我们建议运行以下版本的 EXPLAIN

EXPLAIN (ANALYZE on, BUFFERS on) <original query>;

复制

如果您怀疑您的性能问题是由于磁盘 IO 速度慢造成的，您可以通过在运行上述 EXPLAIN 之前使用 SET track_io_timing = 'on'; 启用 track_io_timing 变量来获得更多信息。

为了在请求支持和报告错误时提供帮助，TimescaleDB 包含一个 SQL 脚本，该脚本输出来自内部 TimescaleDB 表的元数据以及版本信息。该脚本在源代码分发包的 scripts/ 中可用，也可以单独下载。要使用它，请运行

psql [your connect flags] -d your_timescale_db < dump_meta_data.sql > dumpfile.txt

复制

然后检查 dump_file.txt，然后再将其与错误报告或支持问题一起发送。

默认情况下，后台工作进程不会打印很多关于执行的信息。这样做的原因是避免将大量调试信息写入 PostgreSQL 日志，除非必要。

为了帮助调试后台作业，可以在不重启服务器的情况下提高后台工作进程的日志级别，方法是设置 timescaledb.bgw_log_level GUC 并重新加载配置。

ALTER SYSTEM SET timescaledb.bgw_log_level TO 'DEBUG1';
SELECT pg_reload_conf();

复制

此变量默认设置为 log_min_messages 的值，通常为 WARNING。如果在配置文件中更改了 log_min_messages 的值，则在启动工作进程时，它将用于 timescaledb.bgw_log_level。

注意

默认情况下，ALTER SYSTEM 和 pg_reload_conf() 都需要超级用户权限，如果您希望非超级用户也能使用此功能，则需要向 pg_reload_conf() 授予 EXECUTE 权限，并向 timescaledb.bgw_log_level 授予 ALTER SYSTEM 权限。

由于 ALTER SYSTEM 权限仅存在于 PostgreSQL 15 及更高版本中，因此执行这些语句的必要授权仅存在于 PostgreSQL 15 或更高版本的 TimescaleDB Cloud 中。

每个级别打印的信息量因作业而异，但 DEBUG1 级别打印的信息当前如下所示。

每个级别打印的信息量因作业而异，但 DEBUG2 级别打印的信息当前如下所示。

请注意，当您将日志级别设置为 DEBUG2 时，也会打印级别 DEBUG1 的所有消息，这是正常的 PostgreSQL 行为。