Django TimescaleDB Example

This example uses ...

• Django as the “glue” between web browsers and a database¹

• Postgres with extension TimescaleDB as the web application database²

• Celery as a task queue powered by Redis

Tip

If you have any trouble getting setup, feel free to ask a question at django-timescaledb-example/discussions

---

Installation

• Clone this repository locally³

• Install Python⁴ & pipx⁵ and thus poetry⁶ & honcho⁷

• Install Postgres⁸ and thus TimescaleDB⁸

• Install Redis⁹

Important

For Windows try tporadowski/redis or zkteco-home/redis-windows. Celery is used alongside Redis as a task queue & may not run in which case you'll have to adapt **/tasks.py for Bogdanp/dramatiq

• Install this project's Python dependencies via ...

  poetry install

• Create a .env file from .env.dist to store credentials ...

  cp .env.dist .env

Warning

Create a complex secret key¹⁰ if you intend to deploy this web application

• Create a TimescaleDB database with user django via the Postgres CLI ...

  sh shell/createdb.sh

Important

For Windows adapt shell/createdb.sh for Command Prompt or PowerShell

Warning

Create a new role with a password if you go on to do something with this database

• Create a superuser to access the admin site ...

  poetry run python manage.py createsuperuser 

---

Run

• Launch Django, Redis & Celery ...

  honcho start

Tip

Go to http://localhost:8000 & you should see a running web application

---

How to ...

• Re-launch the database server ...

pg_ctl start -D .db/

• Launch a shell within your virtual environment so you don't need poetry run** to run Django commands like poetry run python manage.py ... ...

poetry shell

---

Footnotes

Footnotes

1. To display a web page it asks a database for the data it needs to render files that the browser interprets (HTML, CSS & JavaScript) so it can display a user interface ↩

2. TimescaleDB is an extension to the Postgres database which grants it timeseries capabilities. Postgres wasn't designed to handle timeseries workloads in which data is infrequently inserted and frequently queried in bulk. TimescaleDB adapts Postgres via "hypertables" which enable compression of many rows into "chunks" which are indexed by timestamps. Consequently, queries on ranges of timestamps are faster since Postgres can search "chunks" instead of rows & storage is cheaper. By compressing, TimescaleDB trades insert performance for query performance. ↩

3. I use git clone ...

   git clone git@github.com:rdmolony/rdmolony.github.io.git
   

   ... since I prefer to authenticate with GitHub via SSH ↩

4. I use nix ...

   nix profile install nixpkgs#python3
   

   ↩

5. I use nix ...

   nix profile install nixpkgs#pipx
   

   Why not use pip? Python ships with pip which installs dependencies "globally" which means that you can't easily install the same 3rd party library twice ↩

6. I use pipx ...

   pipx install poetry
   

   ↩

7. I use pipx ...

   pipx install honcho
   

   ↩

8. I use nix ...

   nix profile install --impure --expr 'with import <nixpkgs> {}; pkgs.postgresql.withPackages   (p: [ p.timescaledb ])'
   

   ↩ ↩²

9. I use nix ...

   nix profile install nixpkgs#redis
   

   ↩

10. Generate a SECRET_KEY ...

    poetry run python -c "
    from django.core.management.utils import get_random_secret_key
    print(get_random_secret_key())
    "
    

    ... & copy it into .env ↩