Upgrade TimescaleDB running in Docker

If you originally installed TimescaleDB using Docker, you can upgrade from within the Docker container. This allows you to upgrade to the latest TimescaleDB version while retaining your data.

The timescale/timescaledb-ha* images have the files necessary to run previous versions. Patch releases only contain bugfixes so should always be safe. Non-patch releases may rarely require some extra steps. These steps are mentioned in the release notes for the version of TimescaleDB that you are upgrading to.

After you upgrade the docker image, you run ALTER EXTENSION for all databases using TimescaleDB.

The examples in this page use a Docker instance called timescaledb. If you have given your Docker instance a different name, replace it when you issue the commands.

When you start your upgraded Docker container, you need to be able to point the new Docker image to the location that contains the data from your previous version. To do this, you need to work out where the current mount point is. The current mount point varies depending on whether your container is using volume mounts, or bind mounts.

To upgrade TimescaleDB within Docker, you need to download the upgraded image, stop the old container, and launch the new container pointing to your existing data.

Upgrading TimescaleDB within Docker

1. Pull the latest TimescaleDB image. This command pulls the image for TimescaleDB 2.17.x running on PostgreSQL 17. If you're using another PostgreSQL version, look for the relevant tag in the TimescaleDB HA Docker Hub repository.

   docker pull timescale/timescaledb-ha:pg17

   Copy

2. Stop the old container, and remove it:

   docker stop timescaledb
   docker rm timescaledb

   Copy

3. Launch a new container with the upgraded Docker image, pointing to the existing mount point. Make sure you copy the correct command, based on your mount point type.

   For volume mounts:

4. Connect to the upgraded instance using psql with the -X flag:

   docker exec -it timescaledb psql -U postgres -X

   Copy

5. At the psql prompt, use the ALTER command to upgrade the extension:

   ALTER EXTENSION timescaledb UPDATE;

   Copy

6. Update the TimescaleDB Toolkit extension. Toolkit is packaged with TimescaleDB's HA Docker image, and includes additional hyperfunctions to help you with queries and data analysis:

   CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit;
   ALTER EXTENSION timescaledb_toolkit UPDATE;

   Copy

Note

If you have multiple databases, you need to update each database separately.