docker.recipes

TimescaleDB Time-Series Stack

intermediate

Time-series database optimized for fast ingest and complex queries with visualization.

Overview

TimescaleDB is an open-source time-series database built as a PostgreSQL extension, combining the reliability and SQL capabilities of PostgreSQL with specialized time-series optimizations like automatic partitioning and compression. Developed by Timescale Inc., it addresses the limitations of traditional databases when handling high-volume time-series data while maintaining full PostgreSQL compatibility. This stack integrates TimescaleDB with Promscale (a Prometheus-TimescaleDB connector), Prometheus for metrics collection, and Grafana for visualization, creating a comprehensive observability platform. The combination leverages Promscale to bridge Prometheus's excellent short-term metrics collection with TimescaleDB's superior long-term storage and SQL query capabilities. Organizations benefit from this architecture when they need both real-time monitoring capabilities and historical data analysis, particularly in environments where correlating metrics with relational data is crucial. The stack is ideal for engineering teams building observability platforms, IoT companies managing device telemetry, and financial institutions requiring complex time-series analytics with the flexibility of SQL queries.

Key Features

  • Automatic time-based partitioning (hypertables) for optimal query performance across large datasets
  • Native Prometheus integration via Promscale for long-term metrics storage and PromQL compatibility
  • 90%+ data compression using TimescaleDB's native compression algorithms
  • Full PostgreSQL compatibility allowing joins between time-series and relational data
  • Continuous aggregates for pre-computed rollups and faster dashboard queries
  • Multi-dimensional data model with Prometheus labels stored as TimescaleDB dimensions
  • Advanced SQL analytics capabilities including window functions and complex aggregations
  • Grafana's native TimescaleDB data source with optimized time-series visualizations

Common Use Cases

  • 1IoT platforms collecting sensor data that needs correlation with device metadata and user information
  • 2DevOps teams requiring long-term Prometheus metrics storage beyond default 15-day retention
  • 3Financial services analyzing trading data, market feeds, and risk metrics with complex SQL queries
  • 4Manufacturing companies monitoring equipment performance and correlating with maintenance schedules
  • 5SaaS applications tracking user behavior metrics alongside customer relationship data
  • 6Energy companies managing smart grid data with geographic and temporal analysis requirements
  • 7Healthcare systems storing patient monitoring data with integration to electronic health records

Prerequisites

  • Minimum 4GB RAM recommended (TimescaleDB 2GB + Prometheus 1GB + Grafana 512MB + system overhead)
  • Available ports 3000 (Grafana), 5432 (TimescaleDB), 9090 (Prometheus), and 9201 (Promscale)
  • Basic understanding of PostgreSQL, SQL queries, and time-series data concepts
  • Familiarity with Prometheus configuration and PromQL for metrics collection setup
  • Docker Compose environment with persistent volume support for production deployments
  • Network connectivity for Prometheus to scrape target applications and services

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  timescaledb: 
3    image: timescale/timescaledb:latest-pg16
4    ports: 
5      - "5432:5432"
6    environment: 
7      POSTGRES_USER: ${POSTGRES_USER}
8      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
9      POSTGRES_DB: ${POSTGRES_DB}
10    volumes: 
11      - timescale_data:/var/lib/postgresql/data
12    healthcheck: 
13      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
14      interval: 10s
15      timeout: 5s
16      retries: 5
17    networks: 
18      - timescale-net
19    restart: unless-stopped
20
21  promscale: 
22    image: timescale/promscale:latest
23    ports: 
24      - "9201:9201"
25    environment: 
26      PROMSCALE_DB_URI: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@timescaledb:5432/${POSTGRES_DB}?sslmode=disable
27    depends_on: 
28      timescaledb: 
29        condition: service_healthy
30    networks: 
31      - timescale-net
32    restart: unless-stopped
33
34  prometheus: 
35    image: prom/prometheus:latest
36    ports: 
37      - "9090:9090"
38    volumes: 
39      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
40      - prometheus_data:/prometheus
41    command: 
42      - '--config.file=/etc/prometheus/prometheus.yml'
43      - '--storage.tsdb.path=/prometheus'
44    networks: 
45      - timescale-net
46    restart: unless-stopped
47
48  grafana: 
49    image: grafana/grafana:latest
50    ports: 
51      - "3000:3000"
52    environment: 
53      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
54    volumes: 
55      - grafana_data:/var/lib/grafana
56    depends_on: 
57      - timescaledb
58      - prometheus
59    networks: 
60      - timescale-net
61    restart: unless-stopped
62
63volumes: 
64  timescale_data: 
65  prometheus_data: 
66  grafana_data: 
67
68networks: 
69  timescale-net: 
70    driver: bridge

.env Template

.env
1# TimescaleDB
2POSTGRES_USER=timescale
3POSTGRES_PASSWORD=secure_postgres_password
4POSTGRES_DB=timescale
5
6# Grafana
7GRAFANA_PASSWORD=secure_grafana_password

Usage Notes

  1. 1TimescaleDB at localhost:5432
  2. 2Promscale for Prometheus long-term storage
  3. 3Grafana at http://localhost:3000
  4. 4Use hypertables for time-series data

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

timescaledb
timescaledb:
  image: timescale/timescaledb:latest-pg16
  ports:
    - "5432:5432"
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: ${POSTGRES_DB}
  volumes:
    - timescale_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - timescale-net
  restart: unless-stopped
promscale
promscale:
  image: timescale/promscale:latest
  ports:
    - "9201:9201"
  environment:
    PROMSCALE_DB_URI: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@timescaledb:5432/${POSTGRES_DB}?sslmode=disable
  depends_on:
    timescaledb:
      condition: service_healthy
  networks:
    - timescale-net
  restart: unless-stopped
prometheus
prometheus:
  image: prom/prometheus:latest
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    - prometheus_data:/prometheus
  command:
    - "--config.file=/etc/prometheus/prometheus.yml"
    - "--storage.tsdb.path=/prometheus"
  networks:
    - timescale-net
  restart: unless-stopped
grafana
grafana:
  image: grafana/grafana:latest
  ports:
    - "3000:3000"
  environment:
    - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  depends_on:
    - timescaledb
    - prometheus
  networks:
    - timescale-net
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  timescaledb:
5    image: timescale/timescaledb:latest-pg16
6    ports:
7      - "5432:5432"
8    environment:
9      POSTGRES_USER: ${POSTGRES_USER}
10      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
11      POSTGRES_DB: ${POSTGRES_DB}
12    volumes:
13      - timescale_data:/var/lib/postgresql/data
14    healthcheck:
15      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
16      interval: 10s
17      timeout: 5s
18      retries: 5
19    networks:
20      - timescale-net
21    restart: unless-stopped
22
23  promscale:
24    image: timescale/promscale:latest
25    ports:
26      - "9201:9201"
27    environment:
28      PROMSCALE_DB_URI: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@timescaledb:5432/${POSTGRES_DB}?sslmode=disable
29    depends_on:
30      timescaledb:
31        condition: service_healthy
32    networks:
33      - timescale-net
34    restart: unless-stopped
35
36  prometheus:
37    image: prom/prometheus:latest
38    ports:
39      - "9090:9090"
40    volumes:
41      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
42      - prometheus_data:/prometheus
43    command:
44      - '--config.file=/etc/prometheus/prometheus.yml'
45      - '--storage.tsdb.path=/prometheus'
46    networks:
47      - timescale-net
48    restart: unless-stopped
49
50  grafana:
51    image: grafana/grafana:latest
52    ports:
53      - "3000:3000"
54    environment:
55      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
56    volumes:
57      - grafana_data:/var/lib/grafana
58    depends_on:
59      - timescaledb
60      - prometheus
61    networks:
62      - timescale-net
63    restart: unless-stopped
64
65volumes:
66  timescale_data:
67  prometheus_data:
68  grafana_data:
69
70networks:
71  timescale-net:
72    driver: bridge
73EOF
74
75# 2. Create the .env file
76cat > .env << 'EOF'
77# TimescaleDB
78POSTGRES_USER=timescale
79POSTGRES_PASSWORD=secure_postgres_password
80POSTGRES_DB=timescale
81
82# Grafana
83GRAFANA_PASSWORD=secure_grafana_password
84EOF
85
86# 3. Start the services
87docker compose up -d
88
89# 4. View logs
90docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/timescaledb-stack/run | bash

Troubleshooting

  • Promscale connection failed: Ensure TimescaleDB health check passes before Promscale starts, check database credentials in PROMSCALE_DB_URI
  • High memory usage in TimescaleDB: Enable compression on hypertables using SELECT add_compression_policy() and adjust shared_buffers in postgresql.conf
  • Prometheus remote write errors: Verify Promscale is accessible on port 9201 and add remote_write configuration pointing to http://promscale:9201/write
  • Grafana cannot connect to TimescaleDB: Use connection string postgres://username:password@timescaledb:5432/database and ensure TimescaleDB service is healthy
  • Slow query performance: Create proper time-based indexes on hypertables and use time-bucketing functions like time_bucket() for aggregations
  • Data retention issues: Configure data retention policies using SELECT add_retention_policy() for automated old data cleanup

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

timescaledbgrafanapromscaleprometheus

Tags

#timescaledb#time-series#postgresql#iot#metrics

Category

Database Stacks

Related Recipes

Ad Space