repository·main·Indexed 12 days ago
https://github.com/timescale/timescaledbA PostgreSQL extension for high-performance real-time analytics on time-series and event data. Features include hypertables, continuous aggregates, and optimized support for UUIDv7 in version 2.24+. Supports direct loading to columnstore via timescaledb.enable_direct_compress_copy and specialized time-series functions like time_bucket and to_uuidv7_boundary().
FastLanes is a mostly header-only C library that implements bit-packing inspired by the FastLanes compression layout. It is designed as a building block for higher-level compression algorithms rather than a standalone compression tool.
Key characteristics:
The TimescaleDB TSL library provides specialized implementations for time-series data management. Key functional areas include:
Vector ADT is a dynamic implementation designed to store any type. It manages memory automatically, handling the growing and shrinking of memory allocations as elements are added or removed.void pointers, these ADTs use C macros. This approach is chosen to improve performance and provide better type safety, following standard PostgreSQL conventions.TimescaleDB recommends an OOP-like approach for modularity and code reuse.
Key patterns include:
typedef struct Shape
{
int color;
void (*draw)(Shape *, Canvas *); // Virtual function pointer
} Shape;
typedef struct Circle
{
Shape shape; // Base class as first member for upcasting
float diameter;
} Circle;
void
shape_draw(Shape *shape)
{
Canvas *c = canvas_open();
shape->draw(shape, c);
canvas_close(c);
}
void
circle_draw(Shape *shape, Canvas *canvas)
{
Circle *circle = (Circle *) shape; // Downcasting
/* draw circle logic */
}
Circle blue_circle = {
.shape = {
.color = BLUE,
.draw = circle_draw,
},
.diameter = 10.1,
};The optimizer identifies candidates for SkipScan by looking for specific plan patterns, typically involving a Unique node sitting atop an Index Scan or a Merge Append of multiple Index Scans.
Compatible patterns include:
Unique -> Index ScanUnique -> Merge Append -> Index Scan (multiple)When these patterns are found, the optimizer knows the index is sorted with the distinct keys first. It then transforms the plan to use a Custom Scan (SkipScan) which injects qualifiers into the Index Scan to skip repeated values. The Unique node is preserved in the plan to ensure the targetlist projection remains compatible with PostgreSQL's expectations.
The Loader is a core component of TimescaleDB with two primary responsibilities:
Versioned Library Loading: It ensures the correct versioned shared library is loaded for each database. Since a single Postgres instance can host multiple databases with different TimescaleDB versions, the loader maps each database to its specific library (e.g., a database with version 0.8.0 will load timescaledb-0.8.0.so).
Launcher and Scheduler Management: It starts a background process called the launcher at server startup. The launcher manages individual schedulers (one per database). These schedulers check for the TimescaleDB extension and, if found, manage the scheduling of background jobs for that specific database. The launcher also manages a counter to ensure background worker usage does not exceed the configured worker_processes limit.
When writing or modifying SQL scripts for extension updates or downgrades in TimescaleDB, follow these constraints to ensure compatibility with the extension's internal C structures and security model:
search_path is locked to pg_catalog, pg_temp via header.sql. You must use fully qualified names for all objects (except those in pg_catalog). Use the @extschema@ placeholder to refer to the target installation schema (which defaults to public).search_path for Functions: Always set an explicit search_path for functions to prevent issues. Note that setting an explicit search_path prevents SQL function inlining and transaction control for procedures; in these cases, you must use fully qualified object references and operators within the function body.CREATE OR REPLACE for Updates: While installation scripts use CREATE to prevent users from pre-creating objects, update scripts should use CREATE OR REPLACE to allow for modifications to existing definitions.When SkipScan is active, the execution plan follows a pattern where a Custom Scan (SkipScan) wraps an underlying Index Scan. The SkipScan node iteratively restarts the Index Scan by updating the index condition to skip over previously seen values.
An example of the planned tree structure is:
Custom Scan (SkipScan) on table
-> Index Scan using table_key_idx on table
Index Cond: (key > NULL)After each iteration, the key > NULL condition is replaced with key > [next value returned], allowing the engine to skip repeated values in the index.
TimescaleDB links module loading and activation to the license Grand Unified Configuration (GUC). The system uses a single license GUC to determine which capabilities to enable. For example, an apache license key will not load Timescale-specific modules, whereas a timescale key will.
Activation is managed via check and assign hooks on the license GUC:
check: Validates the license type.assign: Sets the capabilities-struct in the module if required.This mechanism ensures that users cannot accidentally activate features for which they do not have a valid license.