Django timescaledb
A database backend and tooling for Timescaledb.
This is a maintained fork of django-timescaledb, released on PyPI as django-timescaledb-ng. The original has had no PyPI release since 0.2.13 (February 2023). This fork is tested on Django 4.2 to 6.0 and Python 3.9 to 3.13. The import name is still timescale, so it replaces the original and the two cannot be installed together.
Based on gist from WeRiot.
Quick start
Install via pip
pip install django-timescaledb-ng
Use as DATABASE engine in settings.py:
Standard PostgreSQL
DATABASES = {
'default': {
'ENGINE': 'timescale.db.backends.postgresql',
...
},
}
PostGIS
DATABASES = {
'default': {
'ENGINE': 'timescale.db.backends.postgis',
...
},
}
If you already make use of a custom PostgreSQL db backend you can set the path in settings.py.
TIMESCALE_DB_BACKEND_BASE = "django.contrib.gis.db.backends.postgis"
Inherit from the TimescaleModel. A hypertable will automatically be created.
class TimescaleModel(models.Model):
"""
A helper class for using Timescale within Django, has the TimescaleManager and
TimescaleDateTimeField already present. This is an abstract class it should
be inheritted by another class for use.
"""
time = TimescaleDateTimeField(interval="1 day")
objects = TimescaleManager()
class Meta:
abstract = True
Implementation would look like this
from timescale.db.models.models import TimescaleModel
class Metric(TimescaleModel):
temperature = models.FloatField()
If you already have a table, you can either add time field of type TimescaleDateTimeField to your model or rename (if not already named time) and change type of existing DateTimeField (rename first then run makemigrations and then change the type, so that makemigrations considers it as change in same field instead of removing and adding new field). This also triggers the creation of a hypertable.
from timescale.db.models.fields import TimescaleDateTimeField
from timescale.db.models.managers import TimescaleManager
class Metric(models.Model):
time = TimescaleDateTimeField(interval="1 day")
objects = models.Manager()
timescale = TimescaleManager()
The name of the field is important as Timescale specific feratures require this as a property of their functions.
All public classes can also be imported from the package: import timescale.db.models as tsdb, then tsdb.TimescaleDateTimeField, tsdb.TimescaleManager, tsdb.TimeBucket and so on.
Primary keys, unique fields and foreign keys
TimescaleDB only accepts a unique index that includes the time column. This shapes what a hypertable model can have.
Primary key. Django’s default key on id becomes PRIMARY KEY (id, time) in the database. Django still uses id as the key. If the key already includes the time field (primary_key=True on the time field, or a CompositePrimaryKey that lists it), it is kept as it is. Before 0.4.0 the key was always dropped, so tables created by older versions have no primary key and no index on id. They are not changed.
Unique fields. unique=True on another field cannot work. Use a UniqueConstraint that includes the time field.
Foreign keys to a hypertable. Other models cannot have a ForeignKey or ManyToManyField to a hypertable model, unless it has db_constraint=False. A hypertable can have foreign keys to normal tables. One exception: when the time field is the primary key, TimescaleDB 2.32 accepts a foreign key to it and 2.13 does not, so the check leaves that case to the database.
Existing tables. A table that other tables reference by foreign key cannot be converted to a hypertable. TimescaleDB makes the time column NOT NULL, also for a field with null=True, so rows with no time value must be filled before the conversion.
manage.py check and makemigrations report the unique and foreign key cases as timescale.E001 and timescale.E002. To turn a check off, add its id to SILENCED_SYSTEM_CHECKS.
Tests with compression on TimescaleDB 2.13
On TimescaleDB 2.13.1, the table flush at the end of a TransactionTestCase fails when a compressed hypertable has a foreign key to another table: cannot truncate a table referenced in a foreign key constraint, with _compressed_hypertable_N in the detail line. TimescaleDB 2.32.0 does not have the problem; versions in between were not tested. On an affected version, set available_apps on the test case so that Django truncates with CASCADE, or use TestCase.
Reading Data
“TimescaleDB hypertables are designed to behave in the same manner as PostgreSQL database tables for reading data, using standard SQL commands.”
As such the use of the Django’s ORM is perfectally suited to this type of data. By leveraging a custom model manager and queryset we can extend the queryset methods to include Timescale functions.
Time Bucket More Info
Metric.timescale.filter(time__range=date_range).time_bucket('time', '1 hour')
# expected output
<TimescaleQuerySet [{'bucket': datetime.datetime(2020, 12, 22, 11, 0, tzinfo=<UTC>)}, ... ]>
Buckets start at midnight UTC. To move the boundary, pass offset (an interval string or a timedelta) or origin (a datetime), not both:
# daily buckets that start at 06:00 UTC
Metric.timescale.time_bucket('time', '1 day', offset='6 hours')
Time Bucket Gap Fill More Info
from metrics.models import *
from django.db.models import Count, Avg
from django.utils import timezone
from datetime import timedelta
ranges = (timezone.now() - timedelta(days=2), timezone.now())
(Metric.timescale
.filter(time__range=ranges)
.time_bucket_gapfill('time', '1 day', ranges[0], ranges[1], datapoints=240)
.annotate(Avg('temperature')))
# expected output
<TimescaleQuerySet [{'bucket': datetime.datetime(2020, 12, 21, 21, 24, tzinfo=<UTC>), 'temperature__avg': None}, ...]>
Empty buckets are None. Locf fills them with the last value before the gap, Interpolate with a straight line between the neighbours. Both go around an aggregate:
from timescale.db.models import Locf, Interpolate
(Metric.timescale
.filter(time__range=ranges)
.time_bucket_gapfill('time', '1 day', ranges[0], ranges[1])
.annotate(carried=Locf(Avg('temperature')), line=Interpolate(Avg('temperature'))))
The prev and next arguments of the SQL interpolate function are not supported, so an empty first or last bucket stays None.
Histogram More Info
from metrics.models import *
from django.db.models import Count
from django.utils import timezone
from datetime import timedelta
ranges = (timezone.now() - timedelta(days=3), timezone.now())
(Metric.timescale
.filter(time__range=ranges)
.values('device')
.histogram(field='temperature', min_value=50.0, max_value=55.0, num_of_buckets=10)
.annotate(Count('device')))
# expected output
<TimescaleQuerySet [{'histogram': [0, 0, 0, 87, 93, 125, 99, 59, 0, 0, 0, 0], 'device__count': 463}]>
Metadata
Release files for django-timescaledb-ng 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_timescaledb_ng-0.4.0.tar.gz | 19.6 kB | Without provenance | Details for django_timescaledb_ng-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_timescaledb_ng-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for django_timescaledb_ng-0.4.0-py3-none-any.whl |
Total release size: 46.9 kB
Release files / django_timescaledb_ng-0.4.0.tar.gz
| Download URL | django_timescaledb_ng-0.4.0.tar.gz |
|---|---|
| Size | 19.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4af10887590675d1614c67f540293bde9f753360e3bb9af97be92f9fd905078a
|
|
BLAKE2b-256 checksum How to use checksums |
984bff957d3564e66fc24029c8a0638cef07c18c087d0bed7c5c7bb05aedd17f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / django_timescaledb_ng-0.4.0-py3-none-any.whl
| Download URL | django_timescaledb_ng-0.4.0-py3-none-any.whl |
|---|---|
| Size | 27.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cb7949b24da12b38885f01634e32c779c1afe7ce6174344e10a6ec29a04a8208
|
|
BLAKE2b-256 checksum How to use checksums |
6b444c968f944da31fe91db174d3f7b7d05f81bd296b78e8ddabe75574b86585
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for django-timescaledb-ng 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.