Migrating TimescaleDB in Docker: The Missing Guide

TL;DR: Use TimescaleDB's documented path: pg_dump -Fc the whole database, then on the new container run CREATE EXTENSION timescaledb, SELECT timescaledb_pre_restore();, pg_restore, SELECT timescaledb_post_restore(); and ANALYZE. Source and target need the same PostgreSQL and TimescaleDB major versions. The traps sit around that path: the timescaledb-ha image keeps data in /home/postgres/pgdata/data (mount the wrong path and initdb overwrites your volume), a plain COPY hypertable TO STDOUT returns 0 rows, and restoring without timescaledb_pre_restore() is how hypertables and continuous aggregates come back broken.

How Does TimescaleDB Migration in Docker Differ from Standard PostgreSQL?

TimescaleDB stores time-series data in internal chunk tables under each hypertable, plus catalog tables that tie them together. A whole-database pg_dump captures all of it, but the restore has to run with TimescaleDB in "restoring" mode, or its triggers and background jobs fight the restore. That is what timescaledb_pre_restore() and timescaledb_post_restore() are for. Timescale's migration guide wraps every restore in them and recommends this approach for databases under about 100 GB.

Three traps will still destroy data if you skip them:

1. Volume mount mismatch — the timescale/timescaledb-ha image uses PGDATA=/home/postgres/pgdata/data, not /var/lib/postgresql/data. Mounting to the wrong path runs initdb and overwrites your volume.
2. Per-table COPY on a hypertable parent — a plain COPY table_name TO STDOUT returns 0 rows because the rows live in the chunks. If you move data table by table, use COPY (SELECT * FROM hypertable) TO STDOUT.
3. POSTGRES_* env vars are ignored on existing volumes — they only run during the initial initdb.

Which Migration Approach Should You Use?

Prerequisites

• A running TimescaleDB container (source)
• Docker installed on the target host
• Enough disk space for the dump (check your database sizes first)

Step 1: Assess Your Database

Before doing anything, understand what you're working with.

Check database sizes

docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT pg_database.datname, pg_size_pretty(pg_database_size(pg_database.datname))
FROM pg_database ORDER BY pg_database_size(pg_database.datname) DESC;"

Identify your hypertables

docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT hypertable_name FROM timescaledb_information.hypertables;"

Check table sizes and find bloat

docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT
  schemaname || '.' || tablename AS table,
  pg_size_pretty(pg_total_relation_size(schemaname || '.' || tablename)) AS total_size,
  pg_size_pretty(pg_relation_size(schemaname || '.' || tablename)) AS data_size,
  pg_size_pretty(pg_total_relation_size(schemaname || '.' || tablename) - pg_relation_size(schemaname || '.' || tablename)) AS index_size
FROM pg_tables
WHERE schemaname NOT IN ('pg_catalog', 'information_schema', '_timescaledb_catalog', '_timescaledb_config', '_timescaledb_internal')
ORDER BY pg_total_relation_size(schemaname || '.' || tablename) DESC
LIMIT 20;"

Count rows in hypertables

docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT 'events' AS tbl, count(*) FROM events
UNION ALL SELECT 'error_events', count(*) FROM error_events
UNION ALL SELECT 'status_checks', count(*) FROM status_checks;"

Save these counts — you'll need them to verify the migration.

Step 2: Clean Up Before Migrating

This step is optional. Large tables with old data slow a migration, so trim what you genuinely don't need. The table and column names below (session_replay_events, timestamp) are from the Temps control-plane database; substitute your own hypertable and time column.

# Check how much you can trim (example: session replay events older than 15 days)
docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT
  count(*) FILTER (WHERE timestamp < extract(epoch from now() - interval '15 days') * 1000) AS to_delete,
  count(*) FILTER (WHERE timestamp >= extract(epoch from now() - interval '15 days') * 1000) AS to_keep
FROM session_replay_events;"

# Optional and destructive: only if you really don't need the data
# (back up first; prefer deleting rows older than your cutoff over TRUNCATE)
# docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "TRUNCATE YOUR_TABLE;"

Step 3: Dump the Database with pg_dump

First, confirm both sides will run the same major versions. The new container must use the same PostgreSQL major version and the same TimescaleDB major version as the old one:

docker exec YOUR_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT version();
SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';"

Dump the database in custom format (-Fc), which pg_restore needs. pg_dump doesn't include roles, so dump those separately:

docker exec YOUR_CONTAINER pg_dump -U YOUR_USER -Fc -d YOUR_DB > /root/timescale_backup.dump
docker exec YOUR_CONTAINER pg_dumpall -U YOUR_USER --roles-only > /root/timescale_roles.sql
ls -lh /root/timescale_backup.dump

You may see warnings about circular foreign-key constraints on hypertables, chunks and continuous aggregates. TimescaleDB's catalog references itself, so these are expected for a TimescaleDB dump.

Step 4: Create the New Container

Create a fresh volume and container. Pay attention to the volume mount path — this is where most people get burned.

# Create a new volume
docker volume create timescaledb_data_v2

# Start the new container
docker run -d \
  --name timescaledb-new \
  --network YOUR_NETWORK \
  --restart unless-stopped \
  --shm-size 2g \
  -p 5453:5432 \
  -v timescaledb_data_v2:/home/postgres/pgdata/data \
  -e POSTGRES_USER=YOUR_USER \
  -e POSTGRES_PASSWORD='YOUR_PASSWORD' \
  -e POSTGRES_DB=YOUR_DB \
  -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 \
  -e TIMESCALEDB_TELEMETRY=off \
  --health-cmd 'pg_isready -U YOUR_USER -d YOUR_DB' \
  --health-interval 10s \
  --health-timeout 5s \
  --health-start-period 60s \
  --health-retries 5 \
  timescale/timescaledb-ha:pg18   # use the same Postgres major as your source

Critical: Volume Mount Path

If you mount to the wrong path, the entrypoint runs initdb and creates a fresh empty cluster. Your volume gets overwritten with a blank database and your data is gone.

Use a different port

Mount on a different port (e.g., 5453 instead of 5452) so both containers can coexist. This gives you an easy rollback path.

Wait for the container to be healthy:

docker inspect --format='{{.State.Health.Status}}' timescaledb-new

Step 5: Restore with timescaledb_pre_restore()

Recreate any roles your application needs, enable the extension, and put the database into restoring mode:

# Roles (errors such as "role already exists" for the POSTGRES_USER role are expected)
docker exec -i timescaledb-new psql -U YOUR_USER -d YOUR_DB < /root/timescale_roles.sql

docker exec timescaledb-new psql -U YOUR_USER -d YOUR_DB -c "
CREATE EXTENSION IF NOT EXISTS timescaledb;
SELECT timescaledb_pre_restore();"

timescaledb_pre_restore() switches the database into restoring mode and stops TimescaleDB's background workers, so the restore doesn't trip over its own triggers and jobs. Now restore the dump and switch the database back:

docker exec -i timescaledb-new pg_restore -U YOUR_USER --no-owner -v -d YOUR_DB < /root/timescale_backup.dump

docker exec timescaledb-new psql -U YOUR_USER -d YOUR_DB -c "SELECT timescaledb_post_restore();"
docker exec timescaledb-new psql -U YOUR_USER -d YOUR_DB -c "ANALYZE;"

Don't skip timescaledb_post_restore(): until it runs, background jobs such as continuous-aggregate refresh policies and compression stay stopped.

Step 6 (Fallback): Copy Hypertable Data Table by Table

Use this only when you can't do the full restore — for example, you're moving a few hypertables into a database that already has a schema. Create the hypertables on the new side first, then pipe the data across. Hypertable data lives in internal chunks, so you need COPY (SELECT * FROM ...) syntax — a plain COPY table_name TO ... returns 0 rows.

# events
docker exec OLD_CONTAINER psql -U YOUR_USER -d YOUR_DB \
  -c "COPY (SELECT * FROM events) TO STDOUT WITH CSV HEADER" | \
docker exec -i NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB \
  -c "COPY events FROM STDIN WITH CSV HEADER"

# error_events
docker exec OLD_CONTAINER psql -U YOUR_USER -d YOUR_DB \
  -c "COPY (SELECT * FROM error_events) TO STDOUT WITH CSV HEADER" | \
docker exec -i NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB \
  -c "COPY error_events FROM STDIN WITH CSV HEADER"

Repeat for every hypertable you're moving. If you get duplicate key errors, the table already has rows — truncate it on the new container first, then re-run the COPY.

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "TRUNCATE table_name;"

Step 7: Check Continuous Aggregates

After a full restore with pre/post restore, list the continuous aggregates and compare them with the old database:

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT view_name, materialized_only FROM timescaledb_information.continuous_aggregates;"

If one is missing from that list but exists as a regular view — which is what we got when we first replayed a plain-SQL pg_dumpall file with psql and no pre/post restore — or if you used the per-table fallback, recreate it.

Drop the regular view

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
DROP VIEW IF EXISTS events_hourly CASCADE;"

Use DROP VIEW here, not DROP MATERIALIZED VIEW — it exists as a regular view.

Recreate as a continuous aggregate

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
CREATE MATERIALIZED VIEW events_hourly
WITH (timescaledb.continuous) AS
SELECT
    time_bucket('1 hour', timestamp) AS bucket,
    project_id,
    COUNT(DISTINCT visitor_id) FILTER (WHERE visitor_id IS NOT NULL) AS unique_visitors,
    COUNT(DISTINCT session_id) AS unique_sessions,
    COUNT(*) FILTER (WHERE event_type = 'page_view') AS page_views,
    COUNT(*) AS total_events
FROM events
GROUP BY bucket, project_id
WITH NO DATA;

SELECT add_continuous_aggregate_policy('events_hourly',
    start_offset => INTERVAL '3 hours',
    end_offset => INTERVAL '1 hour',
    schedule_interval => INTERVAL '10 minutes');"

Run each CREATE MATERIALIZED VIEW as a separate command — they can't be batched in a single transaction.

Backfill historical data

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB \
  -c "CALL refresh_continuous_aggregate('events_hourly', NOW() - INTERVAL '30 days', NOW());"

Run each refresh separately — refresh_continuous_aggregate() cannot run inside a transaction block.

Step 8: Verify

Compare row counts between old and new:

# Old container
docker exec OLD_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT 'events' AS tbl, count(*) FROM events
UNION ALL SELECT 'error_events', count(*) FROM error_events
UNION ALL SELECT 'status_checks', count(*) FROM status_checks;"

# New container
docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT 'events' AS tbl, count(*) FROM events
UNION ALL SELECT 'error_events', count(*) FROM error_events
UNION ALL SELECT 'status_checks', count(*) FROM status_checks;"

Counts should match (small differences are expected if your app is writing to both).

Verify the hypertables came across:

docker exec NEW_CONTAINER psql -U YOUR_USER -d YOUR_DB -c "
SELECT hypertable_name, num_chunks FROM timescaledb_information.hypertables;"

Verify data is actually on the volume:

docker run --rm -v timescaledb_data_v2:/data alpine du -sh /data

This should show a size proportional to your database — not 70MB (which would indicate a fresh initdb).

Step 9: Swap to Production

Once verified, swap the new container to the production port:

docker stop OLD_CONTAINER
docker rename OLD_CONTAINER timescaledb-old

docker stop NEW_CONTAINER
docker rm NEW_CONTAINER

docker run -d \
  --name timescaledb-1 \
  --network YOUR_NETWORK \
  --restart unless-stopped \
  --shm-size 2g \
  -p 5452:5432 \
  -v timescaledb_data_v2:/home/postgres/pgdata/data \
  -e POSTGRES_USER=YOUR_USER \
  -e POSTGRES_PASSWORD='YOUR_PASSWORD' \
  -e POSTGRES_DB=YOUR_DB \
  -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 \
  -e TIMESCALEDB_TELEMETRY=off \
  --health-cmd 'pg_isready -U YOUR_USER -d YOUR_DB' \
  --health-interval 10s \
  --health-timeout 5s \
  --health-start-period 60s \
  --health-retries 5 \
  timescale/timescaledb-ha:pg18   # use the same Postgres major as your source

Step 10: Clean Up

Once everything is confirmed working:

# Remove old container
docker rm timescaledb-old

# Remove old volume (only after you're sure!)
docker volume rm YOUR_OLD_DATA_VOLUME   # the volume mounted by the old container (see `docker inspect timescaledb-old`)

# Keep the backup for a week
ls -lh /root/timescale_backup.dump

Post-Migration: Tune PostgreSQL

The timescaledb-ha image runs timescaledb_tune on first init, but the POSTGRES_* env vars for tuning (like POSTGRES_SHARED_BUFFERS) are likely ignored. Tune via SQL instead:

docker exec timescaledb-1 psql -U YOUR_USER -d YOUR_DB -c "
ALTER SYSTEM SET shared_buffers = '2GB';
ALTER SYSTEM SET max_connections = 200;
ALTER SYSTEM SET effective_cache_size = '3GB';
ALTER SYSTEM SET work_mem = '16MB';
ALTER SYSTEM SET maintenance_work_mem = '256MB';"

docker restart timescaledb-1

Then verify:

docker exec timescaledb-1 psql -U YOUR_USER -d YOUR_DB -c "
SHOW shared_buffers; SHOW max_connections; SHOW work_mem;"

Running TimescaleDB on Temps

Temps is a free, self-hosted deployment platform (MIT / Apache 2.0) that runs on TimescaleDB itself: its control-plane database stores analytics events, traces, proxy logs and metrics in hypertables. If you'd rather not hand-roll the container side, Temps' managed PostgreSQL can run the timescale/timescaledb-ha:pg18 # use the same Postgres major as your source image or gotempsh/timescaledb-walg:pg18, which adds WAL-G. With a WAL-G image, scheduled backups take a base backup plus a continuous WAL archive to your S3 target, and you can restore into a new service or to a point in time. Moving an existing database into a Temps-managed service is still the pg_dump / pre-restore / pg_restore procedure above.

Temps also handles git-push deployments, web analytics, session replay, error tracking and uptime monitoring in one binary, without per-seat fees. Install it with:

curl -fsSL https://temps.sh/deploy.sh | bash

If you're weighing TimescaleDB against ClickHouse for analytics data in the first place, see TimescaleDB vs ClickHouse; for routine dumps, see how to back up PostgreSQL in Docker automatically.

Lessons Learned

1. Use the documented restore path. pg_dump -Fc, then timescaledb_pre_restore(), pg_restore, timescaledb_post_restore() and ANALYZE, with matching PostgreSQL and TimescaleDB major versions on both sides.

2. Always verify your volume mount path. The timescale/timescaledb-ha image uses /home/postgres/pgdata/data, not /var/lib/postgresql/data. Getting this wrong means initdb runs and overwrites your volume.

3. Don't COPY from a hypertable parent. Plain COPY table_name TO STDOUT returns 0 rows because data lives in internal chunks. Use COPY (SELECT * FROM hypertable) TO STDOUT when moving tables individually.

4. Check continuous aggregates after the restore. If one came back as a regular view, drop it and recreate it with the WITH (timescaledb.continuous) clause, then refresh each one separately — refresh_continuous_aggregate() cannot run inside a transaction block.

5. Keep the old container until you've fully verified. Don't docker rm it until you've compared row counts and confirmed the application works.

6. POSTGRES_* tuning env vars may be ignored. The timescaledb-ha image runs timescaledb_tune which writes directly to postgresql.conf. Use ALTER SYSTEM SET for reliable configuration.

7. Always use a different port for the new container. Running both old and new simultaneously makes rollback trivial — just stop the new one and start the old one.

FAQ

How do you migrate a TimescaleDB database to a new Docker container?

Dump it with pg_dump -Fc, start the new container with the same PostgreSQL and TimescaleDB major versions, run CREATE EXTENSION IF NOT EXISTS timescaledb; and SELECT timescaledb_pre_restore();, restore with pg_restore --no-owner, then run SELECT timescaledb_post_restore(); and ANALYZE;. That is the procedure in Timescale's migration guide.

What do timescaledb_pre_restore() and timescaledb_post_restore() do?

timescaledb_pre_restore() puts the database into restoring mode and stops TimescaleDB's background workers so pg_restore can load the catalog, hypertables and chunks without triggers and jobs interfering. timescaledb_post_restore() turns restoring mode off and restarts the background workers, so refresh, compression and retention policies run again.

What is the correct volume path for timescale/timescaledb-ha?

The timescale/timescaledb-ha image stores data at /home/postgres/pgdata/data. The standard timescale/timescaledb image uses /var/lib/postgresql/data. Mounting to the wrong path runs initdb and silently creates an empty database, overwriting your data.

Why does COPY from a TimescaleDB hypertable return 0 rows?

Hypertable data is stored in internal chunk tables. A plain COPY hypertable TO STDOUT reads only the parent table, which has no rows — all rows live in the chunks. Use COPY (SELECT * FROM hypertable) TO STDOUT to scan across all chunks.

Do continuous aggregates survive a pg_dump restore?

They are part of the database that pg_dump captures, and Timescale's documented pre/post-restore procedure migrates the entire database. Check timescaledb_information.continuous_aggregates afterwards anyway: when we replayed a plain-SQL pg_dumpall file with psql and no pre/post restore, our aggregates came back as regular views and had to be recreated with CREATE MATERIALIZED VIEW ... WITH (timescaledb.continuous).