# TimescaleDB Time-Series Stack

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

- Category: Database Stacks
- Difficulty: intermediate
- Components: timescaledb, grafana, promscale, prometheus
- Tags: timescaledb, time-series, postgresql, iot, metrics
- Source: https://docker.recipes/databases/timescaledb-stack

## 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.

## 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

## Use cases

- IoT platforms collecting sensor data that needs correlation with device metadata and user information
- DevOps teams requiring long-term Prometheus metrics storage beyond default 15-day retention
- Financial services analyzing trading data, market feeds, and risk metrics with complex SQL queries
- Manufacturing companies monitoring equipment performance and correlating with maintenance schedules
- SaaS applications tracking user behavior metrics alongside customer relationship data
- Energy companies managing smart grid data with geographic and temporal analysis requirements
- Healthcare 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    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:
    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

volumes:
  timescale_data:
  prometheus_data:
  grafana_data:

networks:
  timescale-net:
    driver: bridge
```

## .env

```bash
# TimescaleDB
POSTGRES_USER=timescale
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=timescale

# Grafana
GRAFANA_PASSWORD=secure_grafana_password
```

## Usage notes

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

## 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

