TimescaleDB

Overview

TimescaleDB is a time-series database built as a PostgreSQL extension. This template deploys a single-instance PostgreSQL 18 server with the TimescaleDB Community extension preloaded and auto-created, giving you hypertables, columnar compression, continuous aggregates, and retention policies alongside regular relational tables — all through any PostgreSQL client or ORM. Optional PgBouncer connection pooling and scheduled backups to AWS S3, GCS, or a self-hosted MinIO instance are included.

TimescaleDB is licensed under the Timescale License (TSL). It is free to self-host, including all Community features (compression, continuous aggregates, retention); the license only forbids reselling TimescaleDB itself as a managed database service.

TimescaleDB on Control Plane operates as a single-instance deployment, pinned to one replica. Do not scale up the replica count — PostgreSQL is a single-writer database, and additional replicas would run as isolated instances rather than a cluster.

What Gets Created

Stateful TimescaleDB Workload — A single-replica PostgreSQL 18 + TimescaleDB 2.28.3 container on port 5432. The extension is preloaded, created automatically in your database, and auto-tuned to the container’s resources at first boot.
Volume Set — Persistent storage for the database data directory, with optional autoscaling and 7-day snapshots.
Secret — A dictionary secret storing the database username and password, injected into the container at startup.
Identity & Policy — An identity bound to the workload with reveal access to the credentials secret, and scoped cloud storage access when backup is enabled.
PgBouncer Workload (optional) — A PgBouncer connection pooler deployed as a separate workload in front of TimescaleDB.
Backup Cron Workload (optional) — A scheduled pg_dumpall backup job that writes compressed SQL dumps to AWS S3, GCS, or MinIO.

This template does not create a GVC. You must deploy it into an existing GVC.

Installation

This template has no external prerequisites unless backup is enabled. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

image: timescale/timescaledb:2.28.3-pg18 # PostgreSQL 18 + TimescaleDB Community edition

resources:
  minCpu: 200m
  minMemory: 512Mi
  maxCpu: 500m
  maxMemory: 1024Mi # timescaledb-tune sizes shared_buffers/workers from this at first boot

config:
  username: username
  password: password
  database: test # TimescaleDB extension is created automatically in this database

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

internalAccess: # Sets the internal firewall scope - if set to none, replicas will not be able to reach each other
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads:  # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

publicAccess:
  enabled: false # exposes 5432 via a TCP load balancer; connections are unencrypted — prefer internal access

pgbouncer:
  enabled: false
  image: edoburu/pgbouncer:v1.25.1-p0
  poolMode: transaction # options: session, transaction, statement
  defaultPoolSize: 25   # number of real Postgres connections PgBouncer maintains
  maxClientConn: 1000   # maximum number of client connections PgBouncer accepts
  replicas: 1

  resources:
    cpu: 200m
    memory: 128Mi

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # PG18 client, matches server major
  schedule: "0 2 * * *"   # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # Options: aws, gcp, or minio

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-backup-cloudaccount
    policyName: my-backup-policy
    prefix: timescaledb/backups # folder name where your backups will be stored

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: timescaledb/backups # folder name where your backups will be stored

  minio: # Backup to a self-hosted MinIO workload (or any S3-compatible endpoint)
    endpoint: http://my-minio-workload:9000 # e.g. http://WORKLOAD_NAME:9000 for an internal MinIO template deployment
    bucket: my-backup-bucket
    accessKey: my-minio-username # matches the MinIO template's admin.username
    secretKey: my-minio-password # matches the MinIO template's admin.password
    prefix: timescaledb/backups # folder name where your backups will be stored

Image and Resources

image — The TimescaleDB image tag. Keep it in the default (Community) series; -oss tags remove compression, continuous aggregates, and retention.
resources.minCpu / resources.minMemory — Minimum CPU and memory guaranteed to the workload.
resources.maxCpu / resources.maxMemory — Maximum CPU and memory the workload can use. timescaledb-tune sizes shared_buffers and worker settings from maxMemory at first boot (for example, shared_buffers becomes ~25% of the memory limit).

Auto-tuning is captured only at first boot, when the data volume is empty. Raising resources.maxMemory on an existing deployment does not retune PostgreSQL — adjust settings manually with ALTER SYSTEM, or uninstall (which deletes the volume set) and reinstall.

Credentials

config.username — Database username. Change before deploying to production.
config.password — Database password. Change before deploying to production.
config.database — Name of the database created on startup. The TimescaleDB extension is created automatically inside it.

These values are only applied on first startup when the data directory is empty. Updating them after the initial deployment has no effect on the running database. To change credentials or the database name on an existing instance, use PostgreSQL’s native commands (e.g. ALTER USER, ALTER DATABASE).

Storage

volumeset.capacity — Initial volume size in GiB (minimum 10).
volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
- maxCapacity — Maximum volume size in GiB.
- minFreePercentage — Trigger a scale-up when free space drops below this percentage.
- scalingFactor — Multiply the current capacity by this factor when scaling up.

Internal Access

internalAccess.type — Controls which workloads can connect to TimescaleDB on port 5432:

Type	Description
`none`	No internal access allowed
`same-gvc`	Allow access from all workloads in the same GVC
`same-org`	Allow access from all workloads in the same organization
`workload-list`	Allow access only from specific workloads listed in `workloads`

internalAccess.workloads — When type is workload-list, the list of workload links (e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME) allowed to connect.

Public Access

publicAccess.enabled — When true, exposes port 5432 through a TCP load balancer and assigns a public *.cpln.app canonical endpoint.

Public access is unencrypted — the image ships no TLS certificates, so connections over the public endpoint are plaintext. Keep publicAccess.enabled: false and use internal access unless you accept plaintext connections.

PgBouncer Connection Pooling

PgBouncer is an optional connection pooler that sits in front of TimescaleDB and multiplexes application connections into a smaller pool of real database connections. This reduces connection overhead and protects the database from exhaustion under high concurrency. When enabled, PgBouncer is deployed as a separate workload and becomes the primary connection endpoint for your applications:

RELEASE_NAME-pgbouncer.GVC_NAME.cpln.local:5432

pgbouncer.enabled — Enable or disable PgBouncer.
pgbouncer.poolMode — Controls how connections are reused:

Mode	Description
`transaction`	Connection held only for the duration of a transaction, then returned to the pool. Best for most web and API workloads. Not compatible with session-level features (`SET` variables, temporary tables, advisory locks).
`session`	Connection held for the entire client session. Compatible with all PostgreSQL features but provides less reuse.
`statement`	Connection returned after every statement. Transactions are not supported. Rarely used.

pgbouncer.defaultPoolSize — Number of real database connections PgBouncer maintains per pool (default: 25).
pgbouncer.maxClientConn — Maximum number of client connections PgBouncer accepts (default: 1000).
pgbouncer.replicas — Number of PgBouncer instances. PgBouncer is stateless and can be scaled horizontally for high-throughput workloads.
pgbouncer.resources.cpu / pgbouncer.resources.memory — Resources allocated to each PgBouncer replica.

PgBouncer shares the same credentials and identity as the TimescaleDB workload — no additional secrets or IAM configuration is required. The userlist.txt and pgbouncer.ini are generated automatically from your config.username, config.password, and config.database values at startup.

Backup

Backup is disabled by default. When enabled, a cron workload runs pg_dumpall on the configured schedule and uploads a compressed SQL dump to AWS S3, GCS, or a MinIO-compatible endpoint.

backup.enabled — Enable scheduled backups.
backup.image — The backup container image. Match its tag to the server major version — 18.1.0 for the default PostgreSQL 18 image, 17.1.0 for a PostgreSQL 17 image.
backup.schedule — Cron expression for backup frequency (default: daily at 2am UTC).
backup.provider — aws, gcp, or minio.
backup.resources.cpu / backup.resources.memory — Resources for the backup cron container.

Complete the backup prerequisites for your provider before enabling backup.

Connecting

What	Value
Internal (same GVC)	`RELEASE_NAME-timescaledb.GVC_NAME.cpln.local:5432`
Via PgBouncer (when enabled)	`RELEASE_NAME-pgbouncer.GVC_NAME.cpln.local:5432` — use this as your application endpoint
Public (when enabled)	The `status.canonicalEndpoint` of the `RELEASE_NAME-timescaledb` workload, port `5432` (unencrypted)
Credentials	`config.username` / `config.password`

Using TimescaleDB

Any PostgreSQL client or ORM works unchanged. Turn a regular table into a hypertable (automatically partitioned by time) and query it with time buckets:

CREATE TABLE metrics (time timestamptz NOT NULL, device text, value double precision);
SELECT create_hypertable('metrics', by_range('time'));

INSERT INTO metrics VALUES (now(), 'sensor-1', 23.5);

SELECT time_bucket('1 hour', time) AS bucket, device, avg(value)
FROM metrics
GROUP BY bucket, device
ORDER BY bucket;

From here you can add columnar compression, continuous aggregates, and retention policies — all Community features included in the default image.

Backup Prerequisites

AWS S3

Before enabling backup with provider: aws, complete the following in your AWS account:

Create a bucket

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create an IAM policy

Create an IAM policy with the JSON below, replacing YOUR_BUCKET_NAME, then set backup.aws.policyName to the policy’s name and backup.aws.prefix to the folder path for backups.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:DeleteObjectVersion",
                "s3:AbortMultipartUpload"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

GCS

Before enabling backup with provider: gcp, complete the following in your GCP account:

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project. Set backup.gcp.cloudAccountName to its name — access is keyless, with no stored credentials.

Grant the Storage Admin role (roles/storage.objectAdmin scoped to the bucket also works) to the GCP service account created for the Cloud Account. Set backup.gcp.prefix to the folder path for backups.

MinIO

Before enabling backup with provider: minio, ensure your MinIO instance (or any S3-compatible endpoint) is accessible:

Create a bucket

Create a bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint

Set backup.minio.endpoint to the S3 API address including the port. For the minio marketplace template deployed in the same GVC, use http://WORKLOAD_NAME:9000.

Set credentials

Set backup.minio.accessKey and backup.minio.secretKey to credentials with access to the bucket. For the MinIO template, these match the admin.username and admin.password values. Set backup.minio.prefix to the folder path for backups.

MinIO backup requires no Control Plane Cloud Account — credentials are passed directly to the backup job.

Restoring a Backup

Restoring a TimescaleDB dump is not the vanilla PostgreSQL procedure. The target server must run the same TimescaleDB extension version as the dump, and the replay must be wrapped in timescaledb_pre_restore() and timescaledb_post_restore(). Run the following from a client with access to the backup bucket and to a fresh database:

Restore replays a full-cluster dump. Run it against a fresh instance, not a database that already holds data you want to keep.

AWS S3:

export PGPASSWORD="PASSWORD"

psql -h RELEASE_NAME-timescaledb.GVC_NAME.cpln.local -U USERNAME -d DATABASE \
  -c "SELECT timescaledb_pre_restore();"

aws s3 cp "s3://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql -h RELEASE_NAME-timescaledb.GVC_NAME.cpln.local -p 5432 -U USERNAME -d postgres

psql -h RELEASE_NAME-timescaledb.GVC_NAME.cpln.local -U USERNAME -d DATABASE \
  -c "SELECT timescaledb_post_restore();"

unset PGPASSWORD

For GCS, replace the download with gsutil cp "gs://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" -. For MinIO, add --endpoint-url "http://MINIO_ENDPOINT:9000" to the aws s3 cp command and export the MinIO access and secret keys as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Important Notes

Change config.password before installing. Credentials are written into the data directory at first boot; changing the value later does not change the database password.
Do not scale this workload. It is single-writer PostgreSQL, pinned to one replica. Additional replicas would run as isolated instances, not a cluster.
Auto-tuning is captured at first boot only. timescaledb-tune sizes memory settings from the container limit when the volume is empty; raising resources.maxMemory later does not retune.
Public access is unencrypted. The image ships no TLS certificates — keep publicAccess.enabled: false unless you accept plaintext connections.
Keep the image tag in the default (Community) series. -oss tags remove compression, continuous aggregates, and retention policies. If you pin a different pgXX server image, match backup.image to the same major (17.1.0 for PostgreSQL 17).
Uninstall deletes the volume set. A final snapshot is kept for 7 days; enable backups if the data matters long-term.

External References

TimescaleDB Documentation

Official TimescaleDB documentation

Hypertables

Hypertables, compression, continuous aggregates, and retention

PgBouncer Documentation

PgBouncer configuration reference

TimescaleDB Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Resources

Credentials

Storage

Internal Access

Public Access

PgBouncer Connection Pooling

Backup

Connecting

Using TimescaleDB

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Important Notes

External References

TimescaleDB Documentation

Hypertables

PgBouncer Documentation

TimescaleDB Template

​Overview

​What Gets Created

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Credentials

​Storage

​Internal Access

​Public Access

​PgBouncer Connection Pooling

​Backup

​Connecting

​Using TimescaleDB

​Backup Prerequisites

​AWS S3

​GCS

​MinIO

​Restoring a Backup

​Important Notes

​External References

TimescaleDB Documentation

Hypertables

PgBouncer Documentation

TimescaleDB Template

Overview

What Gets Created

Installation

Configuration

Image and Resources

Credentials

Storage

Internal Access

Public Access

PgBouncer Connection Pooling

Backup

Connecting

Using TimescaleDB

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Important Notes

External References