TimescaleDB + Grafana

Key Features

• Automatic time-based partitioning (hypertables) for optimal query performance across large datasets
• Full PostgreSQL compatibility allowing use of existing PostgreSQL tools, extensions, and ORMs
• Continuous aggregates for real-time materialized views that automatically update as new data arrives
• Data compression achieving 90%+ storage reduction using TimescaleDB's columnar compression
• Native PostgreSQL data source integration in Grafana with optimized time-series query support
• Advanced Grafana templating with dashboard variables for dynamic filtering across time ranges and dimensions
• Built-in data retention policies for automatic deletion of old data based on time or storage constraints
• Time_bucket() functions for efficient time-based aggregations and downsampling in visualizations

Common Use Cases

• 1IoT sensor data collection and monitoring with contextual device metadata and real-time dashboards
• 2Financial market data storage combining tick data with reference information and trading analytics
• 3Infrastructure monitoring for long-term storage of Prometheus metrics with custom business dashboards
• 4Application performance monitoring with database-backed alerting and historical trend analysis
• 5Energy management systems tracking consumption patterns with billing integration and forecasting
• 6Manufacturing process monitoring combining sensor readings with production schedules and quality metrics
• 7Smart city applications aggregating traffic, weather, and utility data with public-facing dashboards

Prerequisites

• Minimum 2.5GB available RAM (2GB for TimescaleDB, 512MB for Grafana) for production workloads
• Docker and Docker Compose installed with sufficient disk space for time-series data growth
• Ports 3000 (Grafana) and 5432 (TimescaleDB) available on the host system
• Basic SQL knowledge for creating hypertables and time-series queries in TimescaleDB
• Understanding of time-series data concepts like timestamps, metrics, and aggregation windows
• Familiarity with PostgreSQL connection parameters for configuring Grafana data sources

docker-compose.yml

1services: 
2  timescaledb: 
3    image: timescale/timescaledb:latest-pg16
4    container_name: timescaledb
5    restart: unless-stopped
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    ports: 
13      - "5432:5432"
14    networks: 
15      - timescale-network
16
17  grafana: 
18    image: grafana/grafana:latest
19    container_name: grafana
20    restart: unless-stopped
21    environment: 
22      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
23    volumes: 
24      - grafana_data:/var/lib/grafana
25    ports: 
26      - "3000:3000"
27    depends_on: 
28      - timescaledb
29    networks: 
30      - timescale-network
31
32volumes: 
33  timescale_data: 
34  grafana_data: 
35
36networks: 
37  timescale-network: 
38    driver: bridge

.env Template

1POSTGRES_USER=postgres
2POSTGRES_PASSWORD=changeme
3POSTGRES_DB=timeseries
4GRAFANA_PASSWORD=admin

Usage Notes

Individual Services(2 services)

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

timescaledb:
  image: timescale/timescaledb:latest-pg16
  container_name: timescaledb
  restart: unless-stopped
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: ${POSTGRES_DB}
  volumes:
    - timescale_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"
  networks:
    - timescale-network

grafana:
  image: grafana/grafana:latest
  container_name: grafana
  restart: unless-stopped
  environment:
    GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  ports:
    - "3000:3000"
  depends_on:
    - timescaledb
  networks:
    - timescale-network

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  timescaledb:
5    image: timescale/timescaledb:latest-pg16
6    container_name: timescaledb
7    restart: unless-stopped
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    ports:
15      - "5432:5432"
16    networks:
17      - timescale-network
18
19  grafana:
20    image: grafana/grafana:latest
21    container_name: grafana
22    restart: unless-stopped
23    environment:
24      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
25    volumes:
26      - grafana_data:/var/lib/grafana
27    ports:
28      - "3000:3000"
29    depends_on:
30      - timescaledb
31    networks:
32      - timescale-network
33
34volumes:
35  timescale_data:
36  grafana_data:
37
38networks:
39  timescale-network:
40    driver: bridge
41EOF
42
43# 2. Create the .env file
44cat > .env << 'EOF'
45POSTGRES_USER=postgres
46POSTGRES_PASSWORD=changeme
47POSTGRES_DB=timeseries
48GRAFANA_PASSWORD=admin
49EOF
50
51# 3. Start the services
52docker compose up -d
53
54# 4. View logs
55docker compose logs -f

One-Liner

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

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

Troubleshooting