Skip to main content

​
Overview

This template provides a production‑ready TimescaleDB instance as a Monk runnable. You can:
  • Run it directly to get a managed TimescaleDB container with sensible defaults
  • Inherit it in your own runnable to seamlessly add a time-series database to your stack
TimescaleDB is an open-source time-series database built on PostgreSQL. It provides automatic partitioning, native compression, continuous aggregates, and full SQL support, making it ideal for storing and analyzing time-series data while maintaining PostgreSQL compatibility.

​
What this template manages

  • TimescaleDB container (PostgreSQL with TimescaleDB extension)
  • Network service on port 5432
  • Persistent volumes for data storage
  • Automatic time-series data partitioning
  • PostgreSQL-compatible API

​
Quick start (run directly)

  1. Load templates
monk load MANIFEST
  1. Run TimescaleDB with defaults
monk run timescaledb/timescaledb
  1. Customize credentials (recommended via inheritance)
Running directly uses the defaults defined in this template’s variables. Secrets added with monk secrets add will not affect this runnable unless you inherit it and reference those secrets.
  • Preferred: inherit and replace variables with secret("...") as shown below.
  • Alternative: fork/clone and edit the variables in timescaledb/timescaledb.yaml, then monk load MANIFEST and run.
Once started, connect to localhost:5432 (or the runnable hostname inside Monk networks) using any PostgreSQL client.

​
Configuration

Key variables you can customize in this template: 
variables:
  timescaledb-image-tag: "latest-pg15"  # container image tag
  postgres-password: "..."               # PostgreSQL password
  postgres-user: "postgres"              # PostgreSQL user
  postgres-db: "tsdb"                    # default database
  max-connections: "100"                 # max concurrent connections
Data is persisted under ${monk-volume-path}/timescaledb on the host. Inherit the TimescaleDB runnable in your application and declare a connection. Example: 
namespace: myapp
tsdb:
  defines: runnable
  inherits: timescaledb/timescaledb
api:
  defines: runnable
  containers:
    api:
      image: myorg/iot-api
  connections:
    database:
      runnable: tsdb
      service: timescaledb
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-port:
      value: "5432"
    database-user:
      value: <- secret("postgres-user")
    database-password:
      value: <- secret("postgres-password")
    database-name:
      value: <- secret("postgres-db")
Then set the secrets and run your app: 
monk secrets add -g postgres-user="tsuser"
monk secrets add -g postgres-password="STRONG_PASSWORD"
monk secrets add -g postgres-db="timeseries"
monk run myapp/api

​
Ports and connectivity

  • Service: timescaledb on TCP port 5432 (PostgreSQL wire protocol)
  • From other runnables in the same process group, use connection-hostname("\<connection-name>") to resolve the DB host.

​
Persistence

  • Data path: ${monk-volume-path}/timescaledb:/var/lib/postgresql/data
  • TimescaleDB stores all hypertables and regular PostgreSQL tables in this directory
  • Automatic partitioning and compression are managed internally

​
Features

  • Time-series database built on PostgreSQL
  • Full SQL support with time-series extensions
  • Automatic partitioning (hypertables)
  • Native compression
  • Continuous aggregates for real-time analytics
  • Data retention policies
  • PostgreSQL compatibility (use existing tools and libraries)

​
Use cases

TimescaleDB excels at:
  • IoT sensor data collection
  • Application performance monitoring (APM)
  • Financial tick data
  • Logistics and fleet tracking
  • Industrial telemetry
  • Any high-volume time-series data workload
  • Use pgadmin/ for web-based database administration
  • Combine with grafana/ for time-series visualization
  • Integrate with telegraf/ for metrics collection

​
Troubleshooting

  • TimescaleDB is fully PostgreSQL-compatible, use psql to test:
psql -h localhost -U postgres -d tsdb
  • Ensure the host volumes are writable by the container user
  • Check logs:
monk logs -l 500 -f timescaledb/timescaledb
  • For time-series specific queries, refer to TimescaleDB documentation for hypertable creation and optimization