Timescale Cloud Community

Status: tested against querycop HEAD on 2026-05-20. Endpoint conventions cited as of 2026-05.

Timescale Cloud is the managed service for TimescaleDB, a PostgreSQL extension for time-series workloads. From the wire- protocol standpoint it’s vanilla PostgreSQL plus the TimescaleDB-specific functions; from the operational standpoint it differs from the other managed PG offerings in a few ways:

Each Timescale Cloud service gets a dedicated hostname + port (not the conventional 5432). The port is part of the service’s identity and is the same for the life of the service.
Auth is PostgreSQL password only — there is no IAM / OAuth-equivalent at the data-plane wire. The IAM auth section is intentionally omitted from this page.
TLS uses publicly-trusted roots (Let’s Encrypt), so the OS root bundle that ships with the Querycop container verifies the chain.

TL;DR

For a Timescale Cloud service with password auth, the production-ready config is:

Env var	Value
`GATEKEEPER_BACKEND_HOST`	`<service-id>.<random>.tsdb.cloud.timescale.com`
`GATEKEEPER_BACKEND_PORT`	`<service-specific port, typically a 5-digit high port>` (from the dashboard)
`GATEKEEPER_BACKEND_TLS_MODE`	`verify-full`
`GATEKEEPER_BACKEND_TLS_CA_FILE`	`/etc/ssl/certs/ca-certificates.crt` (OS root bundle — Let’s Encrypt-issued certs chain to publicly-trusted roots)
`GATEKEEPER_BACKEND_TLS_SERVER_NAME`	(unset — derived from `BACKEND_HOST`, which matches the cert SAN)

The default service account on a new Timescale Cloud service is tsdbadmin and the default database is tsdb. Both can be changed by creating additional roles / databases once you’re connected.

Prerequisites

A running Timescale Cloud service. The hostname, port, default user, default database, and password are visible in the dashboard under Services → <your service> → Connection info. The dashboard exposes the credentials once on service creation; rotate via the Operations tab if needed.
Network reachability from the Querycop host to the service’s hostname + port over the public internet. Timescale Cloud’s enterprise plans support VPC peering (AWS) for private connectivity, but the cookbook’s recipe assumes the standard public endpoint.
The OS root CA bundle on disk at a known path. Timescale Cloud’s endpoints serve Let’s Encrypt-issued certs, which chain to ISRG Root X1 / X2, so any current distro bundle works. Typical paths:
- Debian / Ubuntu / the debian:trixie-slim-based Querycop runtime image: /etc/ssl/certs/ca-certificates.crt
- Alpine (after apk add ca-certificates): /etc/ssl/certs/ca-certificates.crt
- RHEL / Fedora / Amazon Linux: /etc/pki/tls/certs/ca-bundle.crt
Querycop’s verify-ca / verify-full modes require an explicit GATEKEEPER_BACKEND_TLS_CA_FILE path — the implicit-system-pool fallback is deliberately not supported, so an explicit path needs to land in the env even when the file you’re pointing at IS the OS root bundle.
Querycop with backend TLS support (GATEKEEPER_BACKEND_TLS_*).

Password auth

Timescale Cloud’s data-plane auth is a PostgreSQL password. Querycop forwards the client’s password unchanged.

Step 1: Point `BACKEND_TLS_CA_FILE` at the OS root bundle

Timescale Cloud’s endpoint certs are publicly-issued Let’s Encrypt certs. The OS root bundle that ships with the Querycop container already contains ISRG Root X1 / X2 and verifies the chain — no Timescale-specific bundle to download.

Querycop’s verify-ca / verify-full modes require GATEKEEPER_BACKEND_TLS_CA_FILE to be set explicitly (the implicit system-pool fallback is deliberately not supported — see backend_tls.go validation). For the Querycop runtime container (Debian-based) point it at the OS bundle:

export GATEKEEPER_BACKEND_TLS_CA_FILE=/etc/ssl/certs/ca-certificates.crt

On Alpine the same path works after apk add ca-certificates. On RHEL / Fedora / Amazon Linux, use /etc/pki/tls/certs/ca-bundle.crt.

If you want to pin tighter than the OS bundle (defense-in-depth against a future Let’s Encrypt issuer change), download just ISRG Root X1 and point at that instead — see the Neon page for the recipe.

Step 2: Configure Querycop

# Required: the service-specific hostname + port from the dashboard
export GATEKEEPER_BACKEND_HOST=abc12345.xyz9876.tsdb.cloud.timescale.com
export GATEKEEPER_BACKEND_PORT=33445    # whatever the dashboard shows for this service

# Required: full TLS verification against the OS root bundle.
# CA_FILE must be set explicitly — Querycop rejects verify-ca /
# verify-full at startup if it's empty.
export GATEKEEPER_BACKEND_TLS_MODE=verify-full
export GATEKEEPER_BACKEND_TLS_CA_FILE=/etc/ssl/certs/ca-certificates.crt
# SERVER_NAME explicitly NOT set — Querycop derives it from
# BACKEND_HOST, which matches the SAN on the Let's Encrypt cert.

# Standard Querycop runtime
export GATEKEEPER_LISTEN_PORT=15432
export GATEKEEPER_API_PORT=8080
export ADMIN_API_KEY=$(openssl rand -hex 16)

querycop

Step 3: Connect the client

The defaults on a new service are user tsdbadmin and database tsdb:

PGPASSWORD='<dashboard password>' psql \
  -h 127.0.0.1 -p 15432 \
  -U tsdbadmin -d tsdb \
  -c 'select 1'

For application connections, create a per-app role + database in the service and use those credentials — same flow as any PostgreSQL deployment.

verify-full is the right default. require (no certificate verification) is evaluation-only. disable is not an appropriate choice — Timescale Cloud endpoints are reached over the public internet, and disable would put the password on the open wire.

Smoke test

# Terminal 1: bring up Querycop with the env above.
docker compose up -d  # or `querycop` directly

# Terminal 2: connect via psql.
PGPASSWORD='<dashboard password>' psql \
  -h 127.0.0.1 -p 15432 \
  -U tsdbadmin -d tsdb \
  -c 'select 1'
#  ?column?
# ----------
#         1
# (1 row)

A green select 1 means proxy-side TLS, backend TLS, and password auth all worked. If you see something else:

backend dial failed: connect: connection refused → BACKEND_PORT is wrong. Re-check the dashboard’s Connection info — Timescale Cloud uses service-specific ports, NOT 5432.
backend TLS negotiation failed: x509: certificate signed by unknown authority → BACKEND_TLS_CA_FILE is empty, points at a wrong path, or the OS root bundle is stale. Switch to a base image with current roots, or pin to ISRG Root X1 explicitly.
password authentication failed for user "tsdbadmin" → wrong password (rotated since you saved it, or you’re connecting to a service you didn’t expect).

Gotchas

Per-service custom port, not 5432

The most common first-setup stumble specific to Timescale Cloud. Each service is provisioned with its own hostname AND its own port — typically a 5-digit high port assigned at service creation. The port is stable for the lifetime of the service.

If you set BACKEND_PORT=5432 by reflex, the dial fails immediately with connection refused.

The listen port on Querycop’s client-side (GATEKEEPER_LISTEN_PORT) can be whatever you like — your apps dial Querycop on that familiar port and don’t care that the upstream is on a different one.

Quick + dirty: TimescaleDB-specific features pass through

TimescaleDB is a PostgreSQL extension, not a fork — hypertables, continuous aggregates, compression policies, and the tsdb_*-prefixed functions all ride on top of the standard PG wire protocol. From Querycop’s perspective they look like normal SQL (CREATE TABLE, SELECT … FROM hypertable_view, etc.), so they pass through without special handling.

What Querycop’s policy / risk-scoring engine sees:

SELECT … FROM <hypertable> → text-protocol SELECT, scored like any read.
CALL add_continuous_aggregate_policy(...) → text-protocol CALL, scored against your policy.
SELECT compress_chunk(<chunk>) → text-protocol SELECT, scored.

There is no Querycop-specific Timescale carve-out today. If you want, say, a policy that exempts SELECT compress_chunk(...) from risk-scoring during scheduled maintenance windows, you’d write that as a normal RBAC / time-window rule in docs/rbac-policy-guide.md. Same shape as any other SQL-pattern policy.

Client→proxy TLS vs proxy→Timescale TLS are SEPARATE legs

Leg	Configured by	Default
Client → Querycop	`GATEKEEPER_PROXY_TLS_CERT` / `_KEY`	OFF — plaintext unless you put TLS material in front
Querycop → Timescale	`GATEKEEPER_BACKEND_TLS_*` (this page)	`prefer` (default) — upgrade to `verify-full` per recipe

In this cookbook the proxy→DB leg is verify-full. The client→proxy leg is your call.

Because Timescale Cloud auth is a PostgreSQL password, that password traverses the client→proxy leg unchanged (Querycop forwards it). Don’t run app→Querycop in plaintext over a non-loopback network unless the network itself is trusted (service-mesh-encrypted, etc.).

Password rotation is dashboard-driven

Timescale Cloud doesn’t expose programmatic password rotation in the data plane (no ALTER USER … IDENTIFIED BY … flow that persists outside the SQL session). Rotation means:

Rotate the password from the dashboard (Service → Operations → Reset password).
Roll the new password into the client’s secrets store.
Recycle the app’s connection pool.

Querycop holds no password state of its own — it just forwards whatever the client sent.

IPv6 / dual-stack

Timescale Cloud’s *.tsdb.cloud.timescale.com endpoints resolve both A and AAAA records in most regions. If the Querycop host has broken IPv6 routing (a common DNS64 / NAT64 gotcha), connections can intermittently fail depending on which address family Go’s resolver picks.

Workarounds:

GODEBUG=netdns=go+v4 on the Querycop process forces IPv4.
Fix the IPv6 routing if you can — Timescale Cloud’s IPv6 path is a peer of the IPv4 path, not a degraded sibling.

Service-port allow-listing on outbound firewalls

If your Querycop host runs behind an outbound firewall or egress proxy that allow-lists by (host, port), remember that the Timescale Cloud service uses a non-standard high port. A rule that allows 5432 outbound will NOT cover the Timescale endpoint — you need a rule for the specific port the dashboard assigned.

Run a one-shot nc -vz <host> <port> from the Querycop host to verify before configuring Querycop, especially if you’ve seen connection refused despite the dashboard saying the service is running.

Cross-links

docs/configuration.md §1.5 — backend TLS reference
docs/rbac-policy-guide.md — RBAC policy setup (Timescale features are normal SQL patterns)
Timescale docs: Connecting to a service
Timescale docs: Security in Timescale Cloud