故障排除

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

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

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

$ pg_config --version
PostgreSQL 12.3

复制

如果这是正确的版本，请仔细检查安装路径是否是您期望的路径。例如，对于通过 macOS 上的 Homebrew 安装的 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 和 Managed Service for 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>;

复制

如果您怀疑您的性能问题是由于磁盘 I/O 缓慢造成的，您可以在运行上述 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 及更高版本上，因此执行这些语句所需的授权仅在 TimescaleDB Cloud for PostgreSQL 15 或更高版本上存在。

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

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

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