dorm.contrib.timescale

TimescaleDB lifecycle helpers — hypertable creation, retention and compression policies. PostgreSQL + timescaledb extension only.

API

dorm.contrib.timescale.create_hypertable(table: str, time_column: str, *, chunk_time_interval: str = '1 day', if_not_exists: bool = True, using: str = 'default') -> None

Convert table into a hypertable partitioned by time_column.

Parameters:

Name	Type	Description	Default
table	str	identifier of the source table (already created via normal dorm migrations).	required
time_column	str	name of the timestamp column used for partitioning.	required
chunk_time_interval	str	PG interval string controlling the partition width. Smaller intervals give finer-grained retention + better insert locality but more chunks overall. Default "1 day" matches the TimescaleDB recommendation for second-resolution event streams.	'1 day'
if_not_exists	bool	pass if_not_exists => TRUE so the helper is safe to call from idempotent migrations.	True
using	str	database alias.	'default'

dorm.contrib.timescale.add_retention_policy(table: str, *, drop_after: str, if_not_exists: bool = True, using: str = 'default') -> None

Schedule TimescaleDB's background retention job that drops chunks older than drop_after relative to the latest row.

Returns the job id Timescale assigns is not captured — the job survives across restarts; callers that need to introspect it can query timescaledb_information.jobs.

dorm.contrib.timescale.remove_retention_policy(table: str, *, if_exists: bool = True, using: str = 'default') -> None

Cancel a previously-installed retention policy on table.

dorm.contrib.timescale.add_compression_policy(table: str, *, compress_after: str, if_not_exists: bool = True, using: str = 'default') -> None

Schedule the background compression job that compresses chunks older than compress_after.

dorm.contrib.timescale.hypertables(*, using: str = 'default') -> list[str]

Return the names of every hypertable in the current DB.

Reads timescaledb_information.hypertables — the view that Timescale exposes for introspection. Returns an empty list when the extension isn't installed (the catalog view is missing → :class:RuntimeError from the driver — surfaced here as an empty list with a clear log warning so monitoring scripts can detect "extension not installed" without differentiating exception shapes).