Release 2.22.0

[timescale-automation]

2.22.0 (2025-09-02)

This release contains performance improvements and bug fixes since the 2.21.3 release. We recommend that you upgrade at the next available opportunity.

Highlighted features in TimescaleDB v2.22.0

• Sparse indexes on compressed hypertables can now be explicitly configured via ALTER TABLE rather than relying only on internal heuristics. Users can define indexes on multiple columns to improve query performance for their specific workloads.
• [Tech Preview] Continuous aggregates now support the timescaledb.invalidate_using option, enabling invalidations to be collected either via triggers on the hypertable or directly from WAL using logical decoding. Aggregates inherit the hypertable’s method if none is specified.
• UUIDv7 compression and vectorization are now supported. The compression algorithm leverages the timestamp portion for delta-delta compression while storing the random portion separately. The vectorized equality/inequality filters with bulk decompression deliver ~2× faster query performance. The feature is disabled by default (timescaledb.enable_uuid_compression) to simplify the downgrading experience, and will be enabled out of the box in the next minor release.
• Hypertables can now be partitioned by UUIDv7 columns, leveraging their embedded timestamps for time-based chunking. We’ve also added utility functions to simplify working with UUIDv7, such as generating values or extracting timestamps - e.g., uuid_timestamp() returns a PostgreSQL timestamp from a UUIDv7.
• SkipScan now supports multi-column indexes in not-null mode, improving performance for distinct and ordered queries across multiple keys.

Removal of the hypercore table access method
We made the decision to deprecate the hypercore table access method (TAM) with the 2.21.0 release. Hypercore TAM was an experiment and it did not show the performance improvements we hoped for. It is removed with this release. Upgrades to 2.22.0 and higher are blocked if TAM is still in use. Since TAM’s inception in 2.18.0, we learned that btrees were not the right architecture. Recent advancements in the columnstore, such as more performant backfilling, SkipScan, adding check constraints, and faster point queries, put the columnstore close to or on par with TAM without needing to store an additional index. We apologize for the inconvenience this action potentially causes and are here to assist you during the migration process.

Migration path

do $$
declare
   relid regclass;
begin
   for relid in
       select cl.oid from pg_class cl
       join pg_am am on (am.oid = cl.relam)
       where am.amname = 'hypercore'
   loop
       raise notice 'converting % to heap', relid::regclass;
       execute format('alter table %s set access method heap', relid);
   end loop;
end
$$;

Features

• #8247 Add configurable alter settings for sparse indexes
• #8306 Add option for invalidation collection using WAL for continuous aggregates
• #8340 Improve selectivity estimates for sparse minmax indexes, so that an index scan on a table in the columnstore is chosen more often when it's beneficial.
• #8360 Continuous aggregate multi-hypertable invalidation processing
• #8364 Remove hypercore table access method
• #8371 Show available timescaledb ALTER options when encountering unsupported options
• #8376 Change DecompressChunk custom node name to ColumnarScan
• #8385 UUID v7 functions for testing pre PG18
• #8393 Add specialized compression for UUIDs. Best suited for UUID v7, but still works with other UUID versions. This is experimental at the moment and backward compatibility is not guaranteed.
• #8398 Set default compression settings at compress time
• #8401 Support ALTER TABLE RESET for compression settings
• #8414 Vectorised filtering of UUID Eq and Ne filters, plus bulk decompression of UUIDs
• #8424 Block downgrade when orderby setting is NULL
• #8454 Remove internal unused index helper functions
• #8494 Improve job stat history retention policy
• #8496 Fix dropping chunks with foreign keys
• #8505 Add support for partitioning on UUIDv7
• #8513 Support multikey SkipScan when all keys are guaranteed to be non-null
• #8514 Concurrent continuous aggregates improvements
• #8528 Add the _timescaledb_functions.chunk_status_text helper function
• #8529 Optimize direct compress status handling

Bugfixes

• #8422 Don't require columnstore=false when using the TimescaleDB Apache 2 Edition
• #8493 Change log level of not null constraint message
• #8500 Fix uniqueness check with generated columns and hypercore
• #8545 Fix error in LOCF/Interpolate with out-of-order and repeated columns
• #8558 Error out on bad args when processing invalidation
• #8559 Fix timestamp out of range using end_offset=NULL on CAgg refresh policy

GUCs

• enable_multikey_skipscan: Enable SkipScan for multiple distinct keys, default: on
• enable_uuid_compression: Enable UUID compression functionality, default: off
• cagg_processing_wal_batch_size: Batch size when processing WAL entries, default: 10000
• cagg_processing_low_work_mem: Low working memory limit for continuous aggregate invalidation processing, default: 38.4MB
• cagg_processing_high_work_mem: High working memory limit for continuous aggregate invalidation processing, default: 51.2MB

Thanks

• @CodeTherapist for reporting an issue where foreign key checks did not work after several insert statements
• @moodgorning for reporting a bug in queries with LOCF/Interpolate using out-of-order columns
• @nofalx for reporting an error when using end_offset=NULL on CAgg refresh policy
• @pierreforstmann for fixing a bug that happened when dropping chunks with foreign keys
• @Zaczero for reporting a bug with CREATE TABLE WITH when using the TimescaleDB Apache 2 Edition

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.46%. Comparing base (de9fc28) to head (356a2ef).
⚠️ Report is 27 commits behind head on 2.22.x.

Additional details and impacted files

@@            Coverage Diff             @@
##           2.22.x    #8536      +/-   ##
==========================================
+ Coverage   82.37%   82.46%   +0.08%     
==========================================
  Files         248      248              
  Lines       47622    47594      -28     
  Branches    12102    12098       -4     
==========================================
+ Hits        39230    39249      +19     
- Misses       3501     3510       +9     
+ Partials     4891     4835      -56     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[CLAassistant]

All committers have signed the CLA.

[billy-the-fish]

A few nits.

[xinxinzhenhuai]

Can you please include this #8517 into the release?
I am seeing the regression tests failure posted in the PR

[brandonpurcell-dev]

I added a summary of highlighted features in the changelog and would like input. It would be good to get a review from Philip when he's back as well.