Skip to content
Klutch.sh Docs

Deploying TimescaleDB

Introduction

TimescaleDB extends PostgreSQL with time-series superpowers and a familiar SQL interface. This guide shows you how to package TimescaleDB with a Dockerfile, configure secure credentials, attach persistent storage, and deploy it to Klutch.sh for low-latency access from your applications.

Prerequisites

  • GitHub repository containing your Dockerfile and optional init scripts.
  • Klutch.sh account with a project ready in the dashboard at klutch.sh/app.
  • TCP access expectations for database traffic.

Project structure

.
├── Dockerfile
└── init
    └── 001_bootstrap.sql

Sample Dockerfile

# Use the official TimescaleDB image built on PostgreSQL 15
FROM timescale/timescaledb:latest-pg15


# Optional: place your bootstrap SQL in /docker-entrypoint-initdb.d/
COPY init/*.sql /docker-entrypoint-initdb.d/


# Rely on Klutch.sh environment variables for secrets
ENV POSTGRES_DB=app_db \
    POSTGRES_USER=app_user


# Do not set POSTGRES_PASSWORD here—configure it as a secret in the dashboard
EXPOSE 5432
  • POSTGRES_PASSWORD (required) – strong password for the primary role.
  • POSTGRES_USER (optional) – defaults to postgres if not set.
  • POSTGRES_DB (optional) – defaults to the user name.
  • TIMESCALEDB_TELEMETRY (optional) – set to off if you want to disable telemetry.

Persistence

TimescaleDB needs durable storage. In Klutch.sh, add a persistent volume with:

  • Mount path: /var/lib/postgresql/data
  • Size: choose based on dataset growth and retention.

Networking

  • Protocol: TCP
  • Internal container port: 5432 (TimescaleDB default)
  • Clients connect to your app’s TCP endpoint (e.g., example-app.klutch.sh:8000) while Klutch.sh routes traffic to port 5432 inside the container.

Optional bootstrap SQL

init/001_bootstrap.sql

CREATE TABLE IF NOT EXISTS metrics (
  ts timestamptz NOT NULL,
  value double precision NOT NULL
);


SELECT create_hypertable('metrics', 'ts', if_not_exists => TRUE);

Add a simple readiness command in your deployment checks:

Terminal window
pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" -h 127.0.0.1 -p 5432

Deployment on Klutch.sh

  1. Push your Dockerfile and any init scripts to a GitHub repository.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Set traffic type to TCP and specify internal port 5432.
  5. Add environment variables (e.g., POSTGRES_USER, POSTGRES_DB, POSTGRES_PASSWORD) in the dashboard. Mark sensitive values as secrets.
  6. Attach a persistent volume at /var/lib/postgresql/data with an appropriate size.
  7. Deploy. Once live, connect from your app using the TCP endpoint (e.g., example-app.klutch.sh:8000) and the credentials you configured.

Verification

  • From a client or jump box, run:

    Terminal window
    PGPASSWORD="$POSTGRES_PASSWORD" psql "host=example-app.klutch.sh port=8000 dbname=$POSTGRES_DB user=$POSTGRES_USER sslmode=require" -c "SELECT NOW();"

  • Confirm hypertables exist:

    Terminal window
    psql "...connection string..." -c "\dt"

Next steps

  • Tune TimescaleDB config (e.g., chunk interval, retention policies) via SQL once deployed.
  • Enable regular backups from the mounted data path.
  • Add application-side connection pooling if your workload is bursty.