---
name: TimescaleDB-HA Docker image facts
description: Empirically verified facts about timescale/timescaledb-ha used in TRM compose files
type: reference
---

# TimescaleDB-HA Docker image facts

**CORRECTED after task 1.1 live boot (2026-05-01).**

- **Image pinned in TRM**: `timescale/timescaledb-ha:pg16.6-ts2.17.2-all`
  - `:pg16-latest` does NOT exist on Docker Hub — it 404s at pull time.
  - The `-all` suffix here means "all extensions bundled" (TimescaleDB + PostGIS + more), NOT "all PG versions".
  - Always pin a concrete `pgX.Y-tsA.B.C-all` tag; floating tags are unreliable for this image.
- **PGDATA directory**: `/home/postgres/pgdata/data`
  - NOT `/pgdata`, NOT `/var/lib/postgresql/data`.
  - Setting `PGDATA=/pgdata` and mounting a volume to `/pgdata` causes initdb to fail with "could not change permissions of directory".
  - compose.dev.yaml correctly sets `PGDATA: /home/postgres/pgdata/data` and mounts to the same path.
- **PostGIS**: Binaries are bundled in the `-all` image but the extension is NOT auto-created on user databases.
  - Directus logs a benign warning: `PostGIS isn't installed. Geometry type support will be limited.`
  - Must be created explicitly: `CREATE EXTENSION IF NOT EXISTS postgis;` — lands in db-init Phase 2.
- **Environment variables**: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` (same as official postgres image).
- **Healthcheck**: `pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB` (double-$ in compose YAML to escape interpolation).
- **`psql` / `pg_isready` in the Directus container**: Installed via `apk add --no-cache postgresql16-client` in the Dockerfile (task 1.1). Available on PATH at runtime.