Install Promscale using a pre-built Docker container
Docker images for the Promscale Connector and TimescaleDB (with the Promscale extension) are available on Docker Hub.
If you are upgrading from the previously used Alpine image follow these upgrade instructions at the end of this page.
The TimescaleDB images have a suffix that indicates the version of PostgreSQL
and TimescaleDB. For example, the tag pg14.2-ts2.6.1-latest
includes PostgreSQL
14.2
and TimescaleDB 2.6.1
. pg14-latest
is the latest image available for
PostgreSQL version 14. Reference the appropriate images when deploying Promscale
and follow the instructions provided by your container platform. If you are using
Kubernetes follow these instructions instead.
important
Running Promscale directly using docker run
is not recommended for production environments. This can be useful for testing purposes and is just provided as an example.
Install Promscale with Docker
Before you begin, you must have Docker installed on your local system. For packages and instructions, see the Docker installation documentation.
Installing Promscale using Docker run
- Use Docker to create a network for Promscale and TimescaleDB:
docker network create --driver bridge promscale
- Install TimescaleDB in a Docker container on a network named
promscale
. It also port forwards to port5432
on your local system:docker run --name timescaledb -e POSTGRES_PASSWORD=<password> \ -d -p 5432:5432 \ --network promscale \ timescale/timescaledb-ha:pg14-latest \ postgres -csynchronous_commit=off
- Run the Promscale Connector Docker container on a network named
promscale
. It also port forwards to port9201
on your local system:docker run --name promscale -d -p 9201:9201 \ --network promscale timescale/promscale:latest \ -db.password=<password> \ -db.port=5432 \ -db.name=postgres \ -db.host=timescaledb \ -db.ssl-mode=allow
After you have installed Promscale, you can ingest data. For instructions, see the send data section.
Upgrading from the previous alpine image
Previously, our recommended image was located at timescaledev/promscale-extension
.
It was based on the Alpine docker image for PostgreSQL.
Because of collation bugs and other issues we have now switched our recommendation to the Debian-based image above.
Our previous Alpine-based image will continue to be updated and supported until the end of 2022 but we encourage users to migrate to the timescale/timescaledb-ha
. All new installations should switch to the timescale/timescaledb-ha
image.
You can also migrate to Debian version by doing the following (please note: this can be a lengthy process and involves downtime):
Use
docker inspect
to determine the data volumes used by your database for the data directory.Shutdown all Promscale Connectors.
Shutdown the original database docker image while preserving the volume mount for the data directory. You will need to mount this same directory in the new image.
Change the ownership of the data-directory to the postgres user and group in the new image. For example:
docker run -v <data_dir_volume_mount>:/var/lib/postgresql/data timescale/timescaledb-ha:pg14-latest chown -R postgres:postgres /var/lib/postgresql/data
Start the new docker container with the same volume mounts as what the original container used.
Connect to the new database using psql and reindex all the data that has data that is collatable. This is necessary because the collation in the Alpine image is broken and so BTREE-based indexes will be incorrect until they are reindexed. It is extremely important to execute this step before ingesting new data to avoid data corruption. Note: This process can take a long time depending on how much indexed textual data the database has. You should use the following query to reindex all the necessary indexes:
DO $$DECLARE r record; BEGIN FOR r IN SELECT DISTINCT indclass FROM (SELECT indexrelid::regclass indclass, unnest(string_to_array(indcollation::text, ' ')) coll FROM pg_catalog.pg_index) sub INNER JOIN pg_catalog.pg_class c ON (c.oid = sub.indclass) WHERE coll !='0' AND c.relkind != 'I' LOOP EXECUTE 'REINDEX INDEX ' || r.indclass; END LOOP; END$$;
Restart the Promscale Connector
If you are using Kubernetes instead of plain docker you should:
- Shutdown the Promscale Connector pods
- Change the database pod to use the debian docker image and restart it.
- Execute jobs for the script in steps 4 and 6 above.
- Restart the Promscale Connector pods.
Found an issue on this page?
Report an issue!Keywords