> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TimescaleDB

> Ready-to-run TimescaleDB container template you can run directly or inherit to integrate a time-series database into your stack.

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

```bash theme={null}
monk load MANIFEST
```

2. Run TimescaleDB with defaults

```bash theme={null}
monk run timescaledb/timescaledb
```

3. 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:

```yaml theme={null}
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.

## Use by inheritance (recommended for apps)

Inherit the TimescaleDB runnable in your application and declare a connection. Example:

```yaml theme={null}
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:

```bash theme={null}
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

## Related templates

* 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:

```bash theme={null}
psql -h localhost -U postgres -d tsdb
```

* Ensure the host volumes are writable by the container user
* Check logs:

```bash theme={null}
monk logs -l 500 -f timescaledb/timescaledb
```

* For time-series specific queries, refer to TimescaleDB documentation for hypertable creation and optimization