diff --git a/_partials/_plan_upgrade.mdx b/_partials/_plan_upgrade.mdx new file mode 100644 index 000000000000..20dd61909c77 --- /dev/null +++ b/_partials/_plan_upgrade.mdx @@ -0,0 +1,19 @@ +You can upgrade your on-premise TimescaleDB installation in-place. This means +that you do not need to dump and restore your data. However, it is still +important that you plan for your upgrade ahead of time. + +Before you upgrade: + +* Read [the release notes][relnotes] for the TimescaleDB version you are + upgrading to. +* Check which PostgreSQL version you are currently running. You might need to + [upgrade to the latest PostgreSQL version][upgrade-pg] + before you begin your TimescaleDB upgrade. +* [Perform a backup][backup] of your database. While TimescaleDB + upgrades are performed in-place, upgrading is an intrusive operation. Always + make sure you have a backup on hand, and that the backup is readable in the + case of disaster. + +[relnotes]: /timescaledb/:currentVersion:/overview/release-notes/ +[upgrade-pg]: /timescaledb/:currentVersion:/how-to-guides/upgrades/upgrade-postgresql/ +[backup]: timescaledb/:currentVersion:/how-to-guides/backup-and-restore/ diff --git a/timescaledb/how-to-guides/page-index/page-index.js b/timescaledb/how-to-guides/page-index/page-index.js index 03bfc901470d..23f13d8e866b 100644 --- a/timescaledb/how-to-guides/page-index/page-index.js +++ b/timescaledb/how-to-guides/page-index/page-index.js @@ -745,44 +745,61 @@ module.exports = [ ], }, { - title: "Update TimescaleDB", - href: "update-timescaledb", + title: "Upgrade TimescaleDB", + href: "upgrades", children: [ { - title: "Update from TimescaleDB 1.x to 2.x", - href: "update-timescaledb-2", - tags: ["upgrade", "1-x", "2-x", "timescaledb"], - keywords: ["upgrade", "1-x", "2-x", "TimescaleDB"], - excerpt: "Upgrade from TimescaleDB 1.x to TimescaleDB 2.x", + title: "About upgrades", + href: "about-upgrades", + tags: ["upgrade", "update", "timescaledb"], + keywords: ["upgrade", "TimescaleDB"], + excerpt: "Learn about upgrading TimescaleDB", }, { - title: "Update using Docker", - href: "updating-docker", - tags: ["upgrade", "docker", "1-x", "2-x", "timescaledb"], - keywords: ["upgrade", "docker", "1-x", "2-x", "TimescaleDB"], + title: "Minor upgrades", + href: "minor-upgrade", + tags: ["upgrade", "update", "timescaledb"], + keywords: ["upgrade", "TimescaleDB"], excerpt: - "Upgrade from TimescaleDB 1.x to TimescaleDB 2.x using Docker", + "Upgrade to a new minor version of TimescaleDB", }, { - title: "Upgrade PostgreSQL", - href: "upgrade-postgresql", - tags: ["upgrade", "postregsql", "timescaledb"], - keywords: ["upgrade", "postgresql", "TimescaleDB"], - excerpt: "Upgrade the version of PostgreSQL used by TimescaleDB", + title: "Major upgrades", + href: "major-upgrade", + tags: ["upgrade", "update", "timescaledb"], + keywords: ["upgrade", "TimescaleDB"], + excerpt: + "Upgrade to a new major version of TimescaleDB", }, { title: "Downgrade TimescaleDB", - href: "downgrade-timescaledb", + href: "downgrade", tags: ["downgrade", "timescaledb"], keywords: ["TimescaleDB", "downgrade"], excerpt: "Downgrade a TimescaleDB version", }, { - title: "Troubleshooting updates", + title: "Upgrade within Docker", + href: "upgrade-docker", + tags: ["upgrade", "update", "docker", "timescaledb"], + keywords: ["upgrade", "docker", "TimescaleDB"], + excerpt: + "Upgrade to a new minor version of TimescaleDB within a Docker container", + }, + { + title: "Upgrade PostgreSQL", + href: "upgrade-pg", + tags: ["upgrade", "update", "postgresql", "timescaledb"], + keywords: ["upgrade", "PostgreSQL", "TimescaleDB"], + excerpt: + "Upgrade to a new version of PostgreSQL", + }, + { + title: "Troubleshooting upgrades", href: "troubleshooting", - tags: ["tshoot", "upgrade", "timescaledb"], + tags: ["tshoot", "upgrade", "update", "timescaledb"], keywords: ["troubleshooting", "upgrade", "TimescaleDB"], - excerpt: "Troubleshoot updating your TimescaleDB installation", + excerpt: "Troubleshoot upgrading your TimescaleDB installation", }, ], }, diff --git a/timescaledb/how-to-guides/update-timescaledb/downgrade-timescaledb.md b/timescaledb/how-to-guides/update-timescaledb/downgrade-timescaledb.md deleted file mode 100644 index 30ca9c9167ae..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/downgrade-timescaledb.md +++ /dev/null @@ -1,34 +0,0 @@ -# Downgrade TimescaleDB versions -If you upgrade your TimescaleDB version and encounter problems, you can -immediately roll back your upgrade. To downgrade to your previous version, -connect to your database and run: -```sql -ALTER EXTENSION timescaledb UPDATE TO ''; -``` - -For example: -```sql -ALTER EXTENSION timescaledb UPDATE TO '2.5.1'; -``` - - -If you're connecting to your database with `psql`, -connect with the `-X` flag. This prevents any commands in `.psqlrc` from loading -another TimescaleDB version. - - -You can verify that the downgrade worked by running `\dx timescaledb` to see the -version number of the extension. - -## Limitations -Downgrading might not be supported for all versions. Where possible, downgrades -between patch versions and between consecutive minor versions are supported. For -example, you can downgrade from TimescaleDB 2.5.2 to 2.5.1, or from 2.5.0 to -2.4.2. However, some versions might not support downgrading. To check whether -you can downgrade from a specific version, see the [release -notes](https://docs.timescale.com/timescaledb/latest/overview/release-notes/). - -Where supported, the downgrade script is tested for a single-step downgrade from -the current version to the previous version. Multi-step downgrades may work but -have not been tested. Downgrading might not work if you make changes to your -database between upgrading and downgrading. \ No newline at end of file diff --git a/timescaledb/how-to-guides/update-timescaledb/index.md b/timescaledb/how-to-guides/update-timescaledb/index.md deleted file mode 100644 index b1de46d66222..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/index.md +++ /dev/null @@ -1,122 +0,0 @@ -# Update TimescaleDB versions - -Update your TimescaleDB version with an in-place update. By updating in-place, -you don't need to dump and restore your data. Automated migration scripts handle -conversion of internal states where needed. - - -Timescale Cloud avoids the manual work involved in updating your TimescaleDB version. -Updates take place automatically during a maintenance window picked by you. -[Learn more](https://docs.timescale.com/cloud/latest/service-operations/maintenance/) -about automatic version updates in Timescale Cloud. - - - -Follow these instructions to update TimescaleDB within the same major release -version. For example, you can update from TimescaleDB 2.1 to 2.2, or from 1.7 to -1.7.4. To update from 1.x to 2.x, see the [section on updating to TimescaleDB -2.x](https://docs.timescale.com/timescaledb/latest/how-to-guides/update-timescaledb/update-timescaledb-2/). - - -## TimescaleDB release compatibility - -TimescaleDB supports the following PostgreSQL releases. If you aren't running a -compatible release, update PostgreSQL before updating TimescaleDB. To learn -more, see the sections on updating PostgreSQL in -[Timescale Cloud][cloud-update-pg], -[Managed Service for TimescaleDB][mst-update-pg], and -[self-hosted TimescaleDB][self-hosted-update-pg]. - -| TimescaleDB release | Supported PostgreSQL releases | -| ------------------- | ----------------------------- | -| 1.7 | 9.6, 10, 11, 12 | -| 2.0 | 11, 12 | -| 2.1-2.3 | 11, 12, 13 | -| 2.4 | 12, 13 | -| 2.5+ | 12, 13, 14 | - - -To make sure your update completes properly, update PostgreSQL and TimescaleDB -separately. Keep PostgreSQL and TimescaleDB versions compatible throughout the -process. If your update spans multiple versions, this could require several steps. - -For example, if you're currently running PostgreSQL 10 and TimescaleDB 1.7.5, -and you want to update to PostgreSQL 13 and TimescaleDB 2.2: - -1. Upgrade PostgreSQL 10 to PostgreSQL 12 -1. Update TimescaleDB 1.7.5 to TimescaleDB 2.2 on PostgreSQL 12 -1. Upgrade PostgreSQL 12 to PostgreSQL 13 with TimescaleDB 2.2 installed - - - -## Update TimescaleDB - -Update TimescaleDB by using PostgreSQL's `ALTER EXTENSION` command. You can run -different TimescaleDB versions on different databases within the same PostgreSQL -instance. You can also update your extensions independently on different -databases. - - -Before updating, check the [release -notes](https://docs.timescale.com/timescaledb/latest/overview/release-notes/) -for the version you want to update to. Specific versions might have different -update requirements that add additional steps. - - - - -### Updating TimescaleDB - -1. [Back up][backup] your database with [`pg_dump`][pg_dump]. -1. [Install][install] the latest version of the TimescaleDB extension. -1. Connect to your database with a PostgreSQL client. This example uses `psql`, - but any client works. If you're using `psql`, connect with the `-X` flag. - This prevents any commands in `.psqlrc` from loading a previous TimescaleDB - version on session startup. - ```bash - psql -X "postgres://:@:/?sslmode=require" - ``` - Do not run any other commands before continuing to the next step. -1. At the `psql` prompt, upgrade TimescaleDB to the latest installed version: - ```sql - ALTER EXTENSION timescaledb UPDATE; - ``` - This upgrades TimescaleDB to the latest installed version, even if you're - several versions behind. To update to a version that's not the latest - installed version, specify the version number, like this: - ```sql - ALTER EXTENSION timescaledb UPDATE TO '2.5.1'; - ``` -1. Verify that the upgrade worked by running `\dx timescaledb` to see the - version number of the extension. - - ```sql - \dx timescaledb - - Name | Version | Schema | Description - ------------+---------+------------+--------------------------------------------------------------------- - timescaledb | x.y.z | public | Enables scalable inserts and complex queries for time-series data - (1 row) - ``` - - - -## Downgrade TimescaleDB - -If you encounter a problem immediately after upgrading, you can roll back your -upgrade. To learn more, see the [section on downgrading TimescaleDB][downgrade]. - -[backup]: /how-to-guides/backup-and-restore/ -[changes-in-2.0]: /overview/release-notes/changes-in-timescaledb-2/ -[cloud-update-pg]: cloud/:currentVersion:/maintenance/#upgrade-to-a-new-postgresql-version -[downgrade]: /how-to-guides/update-timescaledb/downgrade-timescaledb/ -[install]: /install/:currentVersion:/ -[mst-update-pg]: https://kb-managed.timescale.com/en/articles/5368016-perform-a-postgresql-major-version-upgrade -[pg_dump]: https://www.postgresql.org/docs/current/app-pgdump.html -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[self-hosted-update-pg]: /timescaledb/:currentVersion:/how-to-guides/update-timescaledb/upgrade-postgresql/ -[telemetry]: /administration/telemetry/ -[update-docker]: /how-to-guides/update-timescaledb/updating-docker/ -[update-timescaledb]: /how-to-guides/update-timescaledb/update-timescaledb/ -[update-tsdb-2]: /how-to-guides/update-timescaledb/update-timescaledb-2/ -[upgrade-pg]: /how-to-guides/update-timescaledb/upgrade-postgresql/ diff --git a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-1.md b/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-1.md deleted file mode 100644 index bc3ac26c39f6..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-1.md +++ /dev/null @@ -1,155 +0,0 @@ -# Updating TimescaleDB 1.x [](update) - -Use these instructions to update TimescaleDB within the 1.x version. - - -TimescaleDB 2.0 is currently available as a release candidate and we encourage -users to upgrade in testing environments to gain experience and provide feedback on -new and updated features. - -See [Changes in TimescaleDB 2.0][changes-in-2.0] for more information and links to installation -instructions - - -### TimescaleDB release compatibility - -TimescaleDB 1.x is currently supported by the following PostgreSQL releases. - - TimescaleDB Release | Supported PostgreSQL Release - --------------------|------------------------------- - 1.3 - 1.7.4 | 9.6, 10, 11, 12 - -If you need to upgrade PostgreSQL first, please see [our documentation][upgrade-pg]. - -### Update TimescaleDB - -Software upgrades use PostgreSQL's `ALTER EXTENSION` support to update to the -latest version. TimescaleDB supports having different extension -versions on different databases within the same PostgreSQL instance. This -allows you to update extensions independently on different databases. The -upgrade process involves three-steps: - -1. We recommend that you perform a [backup][] of your database via `pg_dump`. -1. [Install][] the latest version of the TimescaleDB extension. -1. Execute the following `psql` command inside any database that you want to - update: - -```sql -ALTER EXTENSION timescaledb UPDATE; -``` - - -When executing `ALTER EXTENSION`, you should connect using `psql` -with the `-X` flag to prevent any `.psqlrc` commands from accidentally -triggering the load of a previous TimescaleDB version on session startup. -It must also be the first command you execute in the session. - - - -This upgrades TimescaleDB to the latest installed version, even if you -are several versions behind. - -After executing the command, the psql `\dx` command should show the latest version: - -```sql -\dx timescaledb - - Name | Version | Schema | Description --------------+---------+------------+--------------------------------------------------------------------- - timescaledb | x.y.z | public | Enables scalable inserts and complex queries for time-series data -(1 row) -``` - -### Example: Migrating docker installations [](update-docker) - -As a more concrete example, the following steps should be taken with a docker -installation to upgrade to the latest TimescaleDB version, while -retaining data across the updates. - -The following instructions assume that your docker instance is named -`timescaledb`. If not, replace this name with the one you use in the subsequent -commands. - -#### Step 1: Pull new image [](update-docker-1) -Install the latest TimescaleDB image: - -```bash -docker pull timescale/timescaledb:latest-pg12 -``` - -If you are using PostgreSQL 11 images, use the tag `latest-pg11`. - - -#### Step 2: Determine mount point used by old container [](update-docker-2) -As you'll want to restart the new docker image pointing to a mount point -that contains the previous version's data, we first need to determine -the current mount point. - -There are two types of mounts. To find which mount type your old container is -using you can run the following command: -```bash -docker inspect timescaledb --format='{{range .Mounts }}{{.Type}}{{end}}' -``` -This command returns either `volume` or `bind`, corresponding -to the two options below. - -1. [Volumes][volumes] -- to get the current volume name use: -```bash -$ docker inspect timescaledb --format='{{range .Mounts }}{{.Name}}{{end}}' -069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c -``` - -2. [Bind-mounts][bind-mounts] -- to get the current mount path use: -```bash -$ docker inspect timescaledb --format='{{range .Mounts }}{{.Source}}{{end}}' -/path/to/data -``` - -#### Step 3: Stop old container [](update-docker-3) -If the container is currently running, stop and remove it in order to connect -the new one. - -```bash -docker stop timescaledb -docker rm timescaledb -``` - -#### Step 4: Start new container [](update-docker-4) -Launch a new container with the updated docker image, but pointing to -the existing mount point. This again differs by mount type. - -1. For volume mounts you can use: -```bash -docker run -v 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb -``` - -2. If using bind-mounts, you need to run: -```bash -docker run -v /path/to/data:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb -``` - - -#### Step 5: Run ALTER EXTENSION [](update-docker-5) -Finally, connect to this instance via `psql` (with the `-X` flag) and execute the `ALTER` command -as above in order to update the extension to the latest version: - -```bash -docker exec -it timescaledb psql -U postgres -X - -# within the PostgreSQL instance -ALTER EXTENSION timescaledb UPDATE; -``` - -You can then run the `\dx` command to make sure you have the -latest version of TimescaleDB installed. - -[changes-in-2.0]: /overview/release-notes/changes-in-timescaledb-2/ -[upgrade-pg]: /how-to-guides/update-timescaledb/upgrade-postgresql/ -[update-tsdb-1]: https://legacy-docs.timescale.com/latest/update-timescaledb/update-tsdb-1 -[update-tsdb-2]: /hot-to-guides/update-timescaledb/update-timescaledb-2/ -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[backup]: /how-to-guides/backup-and-restore/ -[Install]: /install/latest/ -[telemetry]: /administration/telemetry/ -[volumes]: https://docs.docker.com/engine/admin/volumes/volumes/ -[bind-mounts]: https://docs.docker.com/engine/admin/volumes/bind-mounts/ diff --git a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-2.md b/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-2.md deleted file mode 100644 index 2c0da00db53d..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb-2.md +++ /dev/null @@ -1,229 +0,0 @@ -# Updating TimescaleDB to 2.0 [](update) - -Use these instructions to update TimescaleDB 1.x to TimescaleDB 2.0 - - -These instructions are only for upgrading TimescaleDB 1.x to TimescaleDB 2.0 - To upgrade your existing TimescaleDB within the same major version - (for example, from 1.7.2 to 1.7.4, from 2.1 to 2.2), see [Update TimescaleDB](/timescaledb/latest/how-to-guides/update-timescaledb/) - for general update instructions. - - -### TimescaleDB release compatibility [](compatibility) - -TimescaleDB currently supports the following PostgreSQL releases. If you are not -currently running a compatible release, please upgrade before updating TimescaleDB. - - TimescaleDB Release | Supported PostgreSQL Release - --------------------|------------------------------- - 1.7 | 9.6, 10, 11, 12 - 2.0 | 11, 12 - 2.1-2.3 | 11, 12, 13 - 2.4 | 12, 13 - 2.5+ | 12, 13, 14 - -If you need to upgrade PostgreSQL first, -see [our documentation][upgrade-pg]. - - -We always recommend that you update PostgreSQL and TimescaleDB as -separate actions to make sure that each process completes properly. -For example, if you are currently running PostgreSQL 10 and -TimescaleDB 1.7.5, and you want to upgrade to PostgreSQL 13 and -TimescaleDB 2.2, upgrade in this order: - -1. Upgrade PostgreSQL 10 to PostgreSQL 12 -1. Update TimescaleDB 1.7.5 to TimescaleDB 2.2 on PostgreSQL 12 -1. Upgrade PostgreSQL 12 to PostgreSQL 13 with TimescaleDB 2.2 installed - - - -### Notice of breaking changes from TimescaleDB 1.3+ -TimescaleDB 2.0 supports **in-place updates** just like previous releases. During -the update, scripts automatically configure updated features to work as expected -with TimescaleDB 2.0. - -Because this is our first major version release in two years, however, we're providing additional guidance -to help you ensure the update completes successfully and everything is configured as expected (and optimized -for your workload). In particular, settings related to [Continuous Aggregates][caggs], [compression][compression], -and [data retention][retention] have been modified to provide greater configuration transparency and flexibility, -therefore we highly recommend verifying that these settings were migrated correctly. - -**Before completing the upgrade**, we encourage you to read [Changes in TimescaleDB 2.0][changes-in-ts2] for a more -detailed look at the major changes in TimescaleDB 2.0 and how they impact the way your applications and scripts -interact with the API. - -### Prerequisites [](prerequisites) -#### PostgreSQL compatibility -**TimescaleDB 2.0 is not compatible with PostgreSQL 9.6 or 10**. If your current PostgreSQL installation is not -at least version 11, please upgrade PostgreSQL first. Depending on your current PostgreSQL version and installed -TimescaleDB release, you may have to perform multiple upgrades because of compatibility restrictions. - -For example, if you are currently running PostgreSQL 10 and TimescaleDB 1.5, the recommended upgrade path to -PostgreSQL 12 and TimescaleDB 2.0 would be: - -1. Update TimescaleDB 1.5 to TimescaleDB 1.7 on PostgreSQL 10 -1. Upgrade PostgreSQL 10 to PostgreSQL 12 with TimescaleDB 1.7 installed -1. Update TimescaleDB 1.7 to TimescaleDB 2.0 on PostgreSQL with the instructions below - - -Whenever possible, prefer the most recent supported version, PostgreSQL 12. Please see our [Upgrading PostgreSQL](/timescaledb/latest/how-to-guides/update-timescaledb/upgrade-postgresql/) guide for help. - - -#### Fix continuous aggregate errors before upgrading -Before starting the upgrade to TimescaleDB 2.0, **we highly recommend checking the database log for errors -related to failed retention policies that were occurring in TimescaleDB 1.x** and then either remove them or -update them to be compatible with existing continuous aggregates. Any remaining retention policies that are -still incompatible with the `ignore_invalidation_older_than` setting is automatically disabled during -the upgrade and a notice provided. - - -Read more about changes to continuous aggregates and data retension policies [here](/timescaledb/latest/overview/release-notes/changes-in-timescaledb-2#retention-and-caggs). - - - -### Update TimescaleDB [](start-update) - -#### Step 1: Verify TimescaleDB 1.x policy settings (Optional) - -As discussed in the [Changes to TimescaleDB 2.0][changes-in-ts2] document, the APIs and setting names -that configure various policies are changing. The update process below automatically configures -new policies using your current configurations in TimescaleDB 1.x. If you would like to verify -the policy settings after the update is complete, we suggest querying the informational views below -and saving the output so that you can refer to it once the update is complete. - -Execute the following SQL to save current settings for Continuous Aggregates and other policies to CSV using `psql`. If you use an IDE like **pgAdmin** or **DBeaver**, save the output to CSV or another appropriate format to inspect later. - -**Policy Stats** -```SQL -\COPY (SELECT * FROM timescaledb_information.policy_stats) TO policy_stats.csv csv header -``` - -**Continuous Aggregate Stats** -```SQL -\COPY (SELECT * FROM timescaledb_information.continuous_aggregate_stats) TO continuous_aggregate_stats.csv csv header -``` - -**Drop Chunk Policies** -```SQL -\COPY (SELECT * FROM timescaledb_information.drop_chunks_policies) TO drop_chunk_policies.csv csv header -``` -**Reorder Policy Stats** -```SQL -\COPY (SELECT * FROM timescaledb_information.reorder_policies) TO reorder_policies.csv csv header -``` - -#### Step 2: Install and update TimescaleDB extension - -Software upgrades use PostgreSQL's `ALTER EXTENSION` support to update to the -latest version. TimescaleDB supports having different extension -versions on different databases within the same PostgreSQL instance. This -allows you to update extensions independently on different databases. The -upgrade process involves three-steps: - -1. We recommend that you perform a [backup][] of your database via `pg_dump`. -1. [Install][] the latest version of the TimescaleDB extension. -1. Execute the following `psql` command inside any database that you want to - update: - -```sql -ALTER EXTENSION timescaledb UPDATE; -``` - - -When executing `ALTER EXTENSION`, you should connect using `psql` -with the `-X` flag to prevent any `.psqlrc` commands from accidentally -triggering the load of a previous TimescaleDB version on session startup. -It must also be the first command you execute in the session. - - -This upgrades TimescaleDB to the latest installed version, even if you -are several versions behind. - -After executing the command, the psql `\dx` command should show the latest version: - -```sql -\dx timescaledb - - Name | Version | Schema | Description --------------+---------+------------+--------------------------------------------------------------------- - timescaledb | x.y.z | public | Enables scalable inserts and complex queries for time-series data -(1 row) -``` - -#### Step 3: Verify updated policy settings and jobs - -All settings and information previously accessed through separate `stats` informational views have now -been centralized to a common `jobs` view for all types of policies. If you wish to verify that the settings -were moved correctly, query the `timescaledb_information.jobs` view to verify that each policy was correctly -moved and enabled based on your TimescaleDB 1.x setup. - -In the example below, we query for all continuous aggregate policy `jobs`. Compare the names and settings -to the values of the data exported from `timescaledb_information.continuous_aggregates`: - -```SQL -SELECT * FROM timescaledb_information.jobs - WHERE application_name LIKE 'Refresh Continuous%'; - --[ RECORD 1 ]-----+-------------------------------------------------- -job_id | 1001 -application_name | Refresh Continuous Aggregate Policy [1001] -schedule_interval | 01:00:00 -max_runtime | 00:00:00 -max_retries | -1 -retry_period | 01:00:00 -proc_schema | _timescaledb_internal -proc_name | policy_refresh_continuous_aggregate -owner | postgres -scheduled | t -config | {"start_offset": "20 days", "end_offset": "10 -days", "mat_hypertable_id": 2} -next_start | 2020-10-02 12:38:07.014042-04 -hypertable_schema | _timescaledb_internal -hypertable_name | _materialized_hypertable_2 -``` - -Verify the information for each policy type that was exported from TimescaleDB 1.x using the specific -listing of `jobs` in this view. For continuous aggregates, take special note of the `config` information -to verify that all settings were converted correctly given the notes in the -[Updating existing continuous aggregates][changes-in-ts2-caggs] section of our migration document. - -Likewise, you can now verify that all jobs scheduled and running as expected with the new `timescaledb_information.job_stats` -view. Given the continuous aggregate `job` above, querying the new `job_stats` view might return information similar -to the following. - -```SQL -SELECT * FROM timescaledb_information.job_stats - WHERE job_id = 1001; - --[ RECORD 1 ]----------+------------------------------ -hypertable_schema | _timescaledb_internal -hypertable_name | _materialized_hypertable_2 -job_id | 1001 -last_run_started_at | 2020-10-02 09:38:06.871953-04 -last_successful_finish | 2020-10-02 09:38:06.932675-04 -last_run_status | Success -job_status | Scheduled -last_run_duration | 00:00:00.060722 -next_scheduled_run | 2020-10-02 10:38:06.932675-04 -total_runs | 1 -total_successes | 1 -total_failures | 0 -``` - - -[upgrade-pg]: /how-to-guides/update-timescaledb/upgrade-postgresql/ -[update-tsdb-1]: https://legacy-docs.timescale.com/latest/update-timescaledb/update-tsdb-1 -[update-timescaledb]: /how-to-guides/update-timescaledb/update-timescaledb/ -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[backup]: /how-to-guides/backup-and-restore/ -[Install]: /install/latest/ -[telemetry]: /administration/telemetry/ -[volumes]: https://docs.docker.com/engine/admin/volumes/volumes/ -[bind-mounts]: https://docs.docker.com/engine/admin/volumes/bind-mounts/ -[caggs]: /how-to-guides/continuous-aggregates -[compression]: /how-to-guides/compression -[retention]: /how-to-guides/data-retention -[retention-cagg-changes]: /overview/release-notes/changes-in-timescaledb-2#retention-and-caggs -[changes-in-ts2]: /overview/release-notes/changes-in-timescaledb-2 -[changes-in-ts2-caggs]: /overview/release-notes/changes-in-timescaledb-2#updating-continuous-aggregates diff --git a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb.md b/timescaledb/how-to-guides/update-timescaledb/update-timescaledb.md deleted file mode 100644 index 19184ce627ea..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/update-timescaledb.md +++ /dev/null @@ -1,70 +0,0 @@ -# Updating major versions of TimescaleDB [](update) - -Use these instructions to update TimescaleDB within the same major release -version (for example, from TimescaleDB 2.1 to 2.2, or from 1.7 to 1.7.4). If you need to upgrade between -TimescaleDB 1.x and 2.x, see our [separate upgrade document][update-tsdb-2] -for detailed instructions. - -### TimescaleDB release compatibility - -TimescaleDB currently supports the following PostgreSQL releases. If you are not currently running -a compatible release, please upgrade before updating TimescaleDB. - - TimescaleDB Release | Supported PostgreSQL Release - --------------------|------------------------------- - 1.7 | 9.6, 10, 11, 12 - 2.0 | 11, 12 - 2.1-2.3 | 11, 12, 13 - 2.4 | 12, 13 - 2.5+ | 12, 13, 14 - -If you need to upgrade PostgreSQL first, see [our documentation][upgrade-pg]. - -### Update TimescaleDB - -Software upgrades use PostgreSQL's `ALTER EXTENSION` support to update to the -latest version. TimescaleDB supports having different extension -versions on different databases within the same PostgreSQL instance. This -allows you to update extensions independently on different databases. The -upgrade process involves three steps: - -1. Perform a [backup][] of your database via `pg_dump`. -1. [Install][] the latest version of the TimescaleDB extension. -1. Execute the following `psql` command inside any database that you want to - update: - -```sql -ALTER EXTENSION timescaledb UPDATE; -``` - - -When executing `ALTER EXTENSION`, you should connect using `psql` -with the `-X` flag to prevent any `.psqlrc` commands from accidentally -triggering the load of a previous TimescaleDB version on session startup. -It must also be the first command you execute in the session. - - - -This upgrades TimescaleDB to the latest installed version, even if you -are several versions behind. - -After executing the command, the psql `\dx` command should show the latest version: - -```sql -\dx timescaledb - - Name | Version | Schema | Description --------------+---------+------------+--------------------------------------------------------------------- - timescaledb | x.y.z | public | Enables scalable inserts and complex queries for time-series data -(1 row) -``` - - -[changes-in-2.0]: /overview/release-notes/changes-in-timescaledb-2/ -[upgrade-pg]: /how-to-guides/update-timescaledb/upgrade-postgresql/ -[update-tsdb-1]: https://legacy-docs.timescale.com/v1.7/update-timescaledb/update-tsdb-1 -[update-tsdb-2]: /how-to-guides/update-timescaledb/update-timescaledb-2/ -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[backup]: /how-to-guides/backup-and-restore/ -[Install]: /install/latest/ -[telemetry]: /administration/telemetry/ diff --git a/timescaledb/how-to-guides/update-timescaledb/updating-docker.md b/timescaledb/how-to-guides/update-timescaledb/updating-docker.md deleted file mode 100644 index d320a55696f6..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/updating-docker.md +++ /dev/null @@ -1,92 +0,0 @@ -# Updating a TimescaleDB Docker installation - -The following steps should be taken with a docker -installation to upgrade to the latest TimescaleDB version, while -retaining data across the updates. - -The following instructions assume that your docker instance is named -`timescaledb`. If not, replace this name with the one you use in the subsequent -commands. - -#### Step 1: Pull new image [](update-docker-1) -Install the current TimescaleDB 2.0 image: - -```bash -docker pull timescale/timescaledb:2.0.0-pg12 -``` - -If you are using PostgreSQL 11 images, use the tag `2.0.0-pg11`. - - -#### Step 2: Determine mount point used by old container [](update-docker-2) -As you'll want to restart the new docker image pointing to a mount point -that contains the previous version's data, we first need to determine -the current mount point. - -There are two types of mounts. To find which mount type your old container is -using you can run the following command: -```bash -docker inspect timescaledb --format='{{range .Mounts }}{{.Type}}{{end}}' -``` -This command returns either `volume` or `bind`, corresponding -to the two options below. - -1. [Volumes][volumes] -- to get the current volume name use: -```bash -$ docker inspect timescaledb --format='{{range .Mounts }}{{.Name}}{{end}}' -069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c -``` - -2. [Bind-mounts][bind-mounts] -- to get the current mount path use: -```bash -$ docker inspect timescaledb --format='{{range .Mounts }}{{.Source}}{{end}}' -/path/to/data -``` - -#### Step 3: Stop old container [](update-docker-3) -If the container is currently running, stop and remove it in order to connect -the new one. - -```bash -docker stop timescaledb -docker rm timescaledb -``` - -#### Step 4: Start new container [](update-docker-4) -Launch a new container with the updated docker image, but pointing to -the existing mount point. This again differs by mount type. - -1. For volume mounts you can use: -```bash -docker run -v 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb -``` - -2. If using bind-mounts, you need to run: -```bash -docker run -v /path/to/data:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb -``` - - -#### Step 5: Run ALTER EXTENSION [](update-docker-5) -Finally, connect to this instance via `psql` (with the `-X` flag) and execute the `ALTER` command -as above in order to update the extension to the latest version: - -```bash -docker exec -it timescaledb psql -U postgres -X - -# within the PostgreSQL instance -ALTER EXTENSION timescaledb UPDATE; -``` - -You can then run the `\dx` command to make sure you have the -latest version of TimescaleDB installed. - - -[upgrade-pg]: /how-to-guides/update-timescaledb/upgrade-postgresql/ -[update-tsdb-2]: /how-to-guides/update-timescaledb/update-timescaledb-2/ -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[backup]: /how-to-guides/backup-and-restore/ -[Install]: /install/latest/ -[telemetry]: /administration/telemetry/ -[volumes]: https://docs.docker.com/engine/admin/volumes/volumes/ -[bind-mounts]: https://docs.docker.com/engine/admin/volumes/bind-mounts/ diff --git a/timescaledb/how-to-guides/update-timescaledb/upgrade-postgresql.md b/timescaledb/how-to-guides/update-timescaledb/upgrade-postgresql.md deleted file mode 100644 index 2b46467c3dfb..000000000000 --- a/timescaledb/how-to-guides/update-timescaledb/upgrade-postgresql.md +++ /dev/null @@ -1,30 +0,0 @@ -# Upgrade PostgreSQL -Each release of TimescaleDB is compatible with specific versions of PostgreSQL. -Over time support is added for a newer version of PostgreSQL while -simultaneously dropping support for older versions. - -When the supported versions of PostgreSQL changes, you may need to upgrade the version of the **PostgreSQL instance** (for example, from 10 to 12) before you can install the latest release of TimescaleDB. - -To upgrade PostgreSQL, you have two choices, as outlined in the PostgreSQL online documentation. - -### Use `pg_upgrade` - -[`pg_upgrade`][pg_upgrade] is a tool that avoids the need to dump all data and then import it -into a new instance of PostgreSQL after a new version is installed. Instead, `pg_upgrade` allows you to -retain the data files of your current PostgreSQL installation while binding the new PostgreSQL binary -runtime to them. This is currently supported for all releases 8.4 and greater. - - ``` - pg_upgrade -b oldbindir -B newbindir -d olddatadir -D newdatadir" - ``` - -### Use `pg_dump` and `pg_restore` -When `pg_upgrade` is not an option, such as moving data to a new physical instance of PostgreSQL, using the -tried and true method of dumping all data in the database and then restoring into a database in the new instance -is always supported with PostgreSQL and TimescaleDB. - -Please see our documentation on [Backup & Restore][backup] strategies for more information. - - -[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html -[backup]: /how-to-guides/backup-and-restore/ diff --git a/timescaledb/how-to-guides/upgrades/about-upgrades.md b/timescaledb/how-to-guides/upgrades/about-upgrades.md new file mode 100644 index 000000000000..6e39c3dd501e --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/about-upgrades.md @@ -0,0 +1,41 @@ +import PlanUpgrade from 'versionContent/_partials/_plan_upgrade.mdx'; + +# About upgrades +A major upgrade is when you upgrade from one major version of TimescaleDB, to +the next major version. For example, when you upgrade from TimescaleDB 1 +to TimescaleDB 2. + +A minor upgrade is when you upgrade within your current major version of +TimescaleDB. For example, when you upgrade from TimescaleDB 2.5 to +TimescaleDB 2.6. + +If you originally installed TimescaleDB using Docker, you can upgrade from +within the Docker container. For more information, and instructions, see the +[Upgrading with Docker section][upgrade-docker]. + + +Timescale Cloud avoids the manual work involved in updating your TimescaleDB +version. Upgrades take place automatically during a maintenance window picked by +you. +[Learn more](https://docs.timescale.com/cloud/latest/service-operations/maintenance/) +about automatic version upgrades in Timescale Cloud. + + +## Plan your upgrade + + +## Check your version +You can check which version of TimescaleDB you are running, at the psql command +prompt. Use this to check which version you are running before you begin your +upgrade, and again after your upgrade is complete: + +```sql +\dx timescaledb + + Name | Version | Schema | Description +-------------+---------+------------+--------------------------------------------------------------------- + timescaledb | x.y.z | public | Enables scalable inserts and complex queries for time-series data +(1 row) +``` + +[upgrade-docker]: timescaledb/:currentVersion:/how-to-guides/update-timescaledb/upgrade-docker/ diff --git a/timescaledb/how-to-guides/upgrades/downgrade.md b/timescaledb/how-to-guides/upgrades/downgrade.md new file mode 100644 index 000000000000..5a9f30e60ebe --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/downgrade.md @@ -0,0 +1,75 @@ +# Downgrade to a previous version of TimescaleDB +If you upgrade to a new TimescaleDB version and encounter problems, you can roll +back to a previously installed version. This works in the same way as a minor +upgrade. + +Downgrading is not supported for all versions. Generally, downgrades between +patch versions and between consecutive minor versions are supported. For +example, you can downgrade from TimescaleDB 2.5.2 to 2.5.1, or from 2.5.0 to +2.4.2. To check whether you can downgrade from a specific version, see the +[release notes][relnotes]. + +## Plan your downgrade +You can downgrade your on-premise TimescaleDB installation in-place. This means +that you do not need to dump and restore your data. However, it is still +important that you plan for your downgrade ahead of time. + +Before you downgrade: + +* Read [the release notes][relnotes] for the TimescaleDB version you are + downgrading to. +* Check which PostgreSQL version you are currently running. You might need to + [upgrade to the latest PostgreSQL version][upgrade-pg] + before you begin your TimescaleDB downgrade. +* [Perform a backup][backup] of your database. While TimescaleDB + downgrades are performed in-place, downgrading is an intrusive operation. + Always make sure you have a backup on hand, and that the backup is readable in + the case of disaster. + +## Downgrade TimescaleDB to a previous minor version +This downgrade uses the PostgreSQL `ALTER EXTENSION` function to downgrade to +the latest version of the TimescaleDB extension. TimescaleDB supports having +different extension versions on different databases within the same PostgreSQL +instance. This allows you to upgrade and downgrade extensions independently on +different databases. Run the `ALTER EXTENSION` function on each database to +downgrade them individually. + + +The downgrade script is tested and supported for single-step downgrades. That +is, downgrading from the current version, to the previous minor version. +Downgrading might not work if you have made changes to your database between +upgrading and downgrading. + + + + +### Downgrading the TimescaleDB extension + +1. Connect to psql using the `-X` flag. This prevents any `.psqlrc` commands + from accidentally triggering the load of a previous TimescaleDB version on + session startup. +1. At the psql prompt, downgrade the TimescaleDB extension. This must be the + first command you execute in the current session: + + ```sql + ALTER EXTENSION timescaledb UPDATE TO ''; + ``` + + For example: + ```sql + ALTER EXTENSION timescaledb UPDATE TO '2.5.1'; + ``` + +1. Check that you have downgraded to the correct version of the extension with + the `\dx` command. The output should show the downgraded version number. + + ```sql + \dx timescaledb + ``` + + + + +[relnotes]: /timescaledb/:currentVersion:/overview/release-notes/ +[upgrade-pg]: /timescaledb/:currentVersion:/how-to-guides/upgrades/upgrade-postgresql/ +[backup]: /timescaledb/:currentVersion:/how-to-guides/backup-and-restore/ diff --git a/timescaledb/how-to-guides/upgrades/index.md b/timescaledb/how-to-guides/upgrades/index.md new file mode 100644 index 000000000000..3cec95d506fb --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/index.md @@ -0,0 +1,43 @@ +# Upgrade TimescaleDB +You can upgrade your on-premise TimescaleDB installation in-place. + +A major upgrade is when you upgrade from one major version of TimescaleDB, to +the next major version. For example, when you upgrade from TimescaleDB 1, +to TimescaleDB 2. + +A minor upgrade is when you upgrade within your current major version of +TimescaleDB. For example, when you upgrade from TimescaleDB 2.5, to +TimescaleDB 2.6. + +If you originally installed TimescaleDB using Docker, you can upgrade from +within the Docker container. For more information, and instructions, see the +[Upgrading with Docker section][upgrade-docker]. + +You can also downgrade your TimescaleDB installation to a previous version, if +you need to. + +* [Learn about upgrades][about-upgrades] to understand how it works + before you begin your upgrade. +* Upgrade to the next [minor version][upgrade-minor] of TimescaleDB. +* Upgrade to the next [major version][upgrade-major] of TimescaleDB. +* [Downgrade][downgrade] to a previous version of TimescaleDB. +* Upgrade TimescaleDB using [Docker][upgrade-docker]. +* Upgrade the version of [PostgreSQL][upgrade-pg] your TimescaleDB + installation uses. +* [Troubleshoot][upgrade-tshoot] upgrading. + + +Timescale Cloud avoids the manual work involved in updating your TimescaleDB +version. Upgrades take place automatically during a maintenance window picked by +you. +[Learn more](https://docs.timescale.com/cloud/latest/service-operations/maintenance/) +about automatic version upgrades in Timescale Cloud. + + +[about-upgrades]: timescaledb/:currentVersion:/how-to-guides/upgrades/about-upgrades/ +[upgrade-minor]: timescaledb/:currentVersion:/how-to-guides/upgrades/minor-upgrade/ +[upgrade-major]: timescaledb/:currentVersion:/how-to-guides/upgrades/major-upgrade/ +[downgrade]: timescaledb/:currentVersion:/how-to-guides/upgrades/downgrade/ +[upgrade-docker]: timescaledb/:currentVersion:/how-to-guides/upgrades/upgrade-docker/ +[upgrade-pg]: timescaledb/:currentVersion:/how-to-guides/upgrades/upgrade-pg/ +[upgrade-tshoot]: timescaledb/:currentVersion:/how-to-guides/upgrades/troubleshooting/ diff --git a/timescaledb/how-to-guides/upgrades/major-upgrade.md b/timescaledb/how-to-guides/upgrades/major-upgrade.md new file mode 100644 index 000000000000..a645a8c556f9 --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/major-upgrade.md @@ -0,0 +1,180 @@ +import PlanUpgrade from 'versionContent/_partials/_plan_upgrade.mdx'; + +# Major TimescaleDB upgrades +A major upgrade is when you upgrade from one major version of TimescaleDB, to +the next major version. For example, when you upgrade from TimescaleDB 1, +to TimescaleDB 2. + +For upgrading within your current major version, for example upgrading from +TimescaleDB 2.5 to TimescaleDB 2.6, see the +[minor upgrades section][upgrade-minor]. + +## Plan your upgrade + + +Additionally, before you begin this major upgrade, read the +[changes in TimescaleDB 2 section][changes-in-ts2]. +This section provides a more detailed look at the major changes in +TimescaleDB 2. It also includes information about how these major changes +impact the way your applications and scripts interact with the TimescaleDB API. + +## Breaking changes +When you upgrade from TimescaleDB 1, to TimescaleDB 2, scripts +automatically configure updated features to work as expected with the new +version. However, not everything works in exactly the same way as previously. + +Before you begin this major upgrade, check the database log for errors related +to failed retention policies that could have occurred in TimescaleDB 1. You +can either remove the failing policies entirely, or update them to be compatible +with your existing continuous aggregates. + +If incompatible retention policies are present when you perform the upgrade, the +`ignore_invalidation_older_than` setting is automatically turned off, and a +notice is shown. + +For more information about changes to continuous aggregates and data retention +policies, see the [release notes][relnotes-20]. + +## Upgrade TimescaleDB to the next major version +To perform this major upgrade: + +1. Export your TimescaleDB 1 policy settings +1. Upgrade the TimescaleDB extension +1. Verify updated policy settings and jobs + +When you perform the upgrade, new policies are automatically configured based on +your current configuration. This upgrade process allows you to export your +policy settings before performing the upgrade, so that you can verify them after +the upgrade is complete. + +This upgrade uses the PostgreSQL `ALTER EXTENSION` function to upgrade to the +latest version of the TimescaleDB extension. TimescaleDB supports having +different extension versions on different databases within the same PostgreSQL +instance. This allows you to upgrade extensions independently on different +databases. Run the `ALTER EXTENSION` function on each database to upgrade them +individually. + + + +### Exporting TimescaleDB 1 policy settings + +1. At the psql prompt, use this command to save the current settings for your + policy statistics to a `.csv` file: + + ```sql + COPY (SELECT * FROM timescaledb_information.policy_stats) + TO policy_stats.csv csv header + ``` + +1. Use this command to save the current settings for your continuous aggregates + to a `.csv` file: + + ```sql + COPY (SELECT * FROM timescaledb_information.continuous_aggregate_stats) + TO continuous_aggregate_stats.csv csv header + ``` + +1. Use this command to save the current settings for your drop chunk policies to + a `.csv` file: + + ```sql + COPY (SELECT * FROM timescaledb_information.drop_chunks_policies) + TO drop_chunk_policies.csv csv header + ``` + +1. Use this command to save the current settings for your reorder policies + to a `.csv` file: + + ```sql + COPY (SELECT * FROM timescaledb_information.reorder_policies) + TO reorder_policies.csv csv header + ``` + + + + + +### Upgrading the TimescaleDB extension + +1. Connect to psql using the `-X` flag. This prevents any `.psqlrc` commands + from accidentally triggering the load of a previous TimescaleDB version on + session startup. +1. At the psql prompt, upgrade the TimescaleDB extension. This must be the first + command you execute in the current session: + + ```sql + ALTER EXTENSION timescaledb UPDATE; + ``` + +1. Check that you have upgraded to the latest version of the extension with the + `\dx` command. The output should show the upgraded version number. + + ```sql + \dx timescaledb + ``` + + + + + +### Verifying updated policy settings and jobs + +1. Use this query to verify the continuous aggregate policy jobs: + + ```sql + SELECT * FROM timescaledb_information.jobs + WHERE application_name LIKE 'Refresh Continuous%'; + + -[ RECORD 1 ]-----+-------------------------------------------------- + job_id | 1001 + application_name | Refresh Continuous Aggregate Policy [1001] + schedule_interval | 01:00:00 + max_runtime | 00:00:00 + max_retries | -1 + retry_period | 01:00:00 + proc_schema | _timescaledb_internal + proc_name | policy_refresh_continuous_aggregate + owner | postgres + scheduled | t + config | {"start_offset": "20 days", "end_offset": "10 + days", "mat_hypertable_id": 2} + next_start | 2020-10-02 12:38:07.014042-04 + hypertable_schema | _timescaledb_internal + hypertable_name | _materialized_hypertable_2 + ``` + +1. Verify the information for each policy type that you exported before you + upgraded. For continuous aggregates, take note of the `config` information to + verify that all settings were converted correctly. +1. Verify that all jobs are scheduled and running as expected using the new + `timescaledb_information.job_stats` view: + +```sql +SELECT * FROM timescaledb_information.job_stats + WHERE job_id = 1001; +``` + +The output looks like this: + +```sql +-[ RECORD 1 ]----------+------------------------------ +hypertable_schema | _timescaledb_internal +hypertable_name | _materialized_hypertable_2 +job_id | 1001 +last_run_started_at | 2020-10-02 09:38:06.871953-04 +last_successful_finish | 2020-10-02 09:38:06.932675-04 +last_run_status | Success +job_status | Scheduled +last_run_duration | 00:00:00.060722 +next_scheduled_run | 2020-10-02 10:38:06.932675-04 +total_runs | 1 +total_successes | 1 +total_failures | 0 +``` + + + + +[upgrade-minor]: timescaledb/:currentVersion:/how-to-guides/upgrades/minor-upgrade/ +[changes-in-ts2]: /timescaledb/:currentVersion:/overview/release-notes/changes-in-timescaledb-2 +[relnotes-20]: /timescaledb/:currentVersion:/overview/release-notes/changes-in-timescaledb-2#retention-and-caggs diff --git a/timescaledb/how-to-guides/upgrades/minor-upgrade.md b/timescaledb/how-to-guides/upgrades/minor-upgrade.md new file mode 100644 index 000000000000..7a5b2eb70e4e --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/minor-upgrade.md @@ -0,0 +1,46 @@ +import PlanUpgrade from 'versionContent/_partials/_plan_upgrade.mdx'; + +# Minor TimescaleDB upgrades +A minor upgrade is when you upgrade within your current major version of +TimescaleDB. For example, when you upgrade from TimescaleDB 2.5, to +TimescaleDB 2.6. + +For upgrading to a new major version, for example upgrading from +TimescaleDB 1 to TimescaleDB 2, see the +[major upgrades section][upgrade-major]. + +## Plan your upgrade + + +## Upgrade TimescaleDB to the next minor version +This upgrade uses the PostgreSQL `ALTER EXTENSION` function to upgrade to the +latest version of the TimescaleDB extension. TimescaleDB supports having +different extension versions on different databases within the same PostgreSQL +instance. This allows you to upgrade extensions independently on different +databases. Run the `ALTER EXTENSION` function on each database to upgrade them +individually. + + + +### Upgrading the TimescaleDB extension + +1. Connect to psql using the `-X` flag. This prevents any `.psqlrc` commands + from accidentally triggering the load of a previous TimescaleDB version on + session startup. +1. At the psql prompt, upgrade the TimescaleDB extension. This must be the first + command you execute in the current session: + + ```sql + ALTER EXTENSION timescaledb UPDATE; + ``` + +1. Check that you have upgraded to the latest version of the extension with the + `\dx` command. The output should show the upgraded version number. + + ```sql + \dx timescaledb + ``` + + + +[upgrade-major]: timescaledb/:currentVersion:/how-to-guides/upgrades/major-upgrade/ diff --git a/timescaledb/how-to-guides/update-timescaledb/troubleshooting.md b/timescaledb/how-to-guides/upgrades/troubleshooting.md similarity index 89% rename from timescaledb/how-to-guides/update-timescaledb/troubleshooting.md rename to timescaledb/how-to-guides/upgrades/troubleshooting.md index 844a80655fe4..8fd46690b091 100644 --- a/timescaledb/how-to-guides/update-timescaledb/troubleshooting.md +++ b/timescaledb/how-to-guides/upgrades/troubleshooting.md @@ -12,8 +12,9 @@ with updating your TimescaleDB installation. * Copy this comment at the top of every troubleshooting page --> -## Updating fails with an error saying `no update path` -In some cases, when you use the `ALTER EXTENSION timescaledb UPDATE` command to update, it might fail with an error like this: +## Upgrading fails with an error saying `no update path` +In some cases, when you use the `ALTER EXTENSION timescaledb UPDATE` command to +upgrade, it might fail with an error like this: ```sql ERROR: extension "timescaledb" has no update path from version "2.5.2" to version "2.6.1" @@ -22,5 +23,5 @@ ERROR: extension "timescaledb" has no update path from version "2.5.2" to versio This occurs if the list of available extensions does not include the version you are trying to upgrade to, and it can occur if the package was not installed correctly in the first place. To correct the problem, install the upgrade -package, restart PostgreSQL, verify the version, and then attempt the update +package, restart PostgreSQL, verify the version, and then attempt the upgrade again. diff --git a/timescaledb/how-to-guides/upgrades/upgrade-docker.md b/timescaledb/how-to-guides/upgrades/upgrade-docker.md new file mode 100644 index 000000000000..cf2962d9aca5 --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/upgrade-docker.md @@ -0,0 +1,99 @@ +# Upgrades within a Docker container +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. + + +In this section, the examples use a Docker instance called `timescaledb`. If you +have given your Docker instance a different name, replace it when you issue the +commands. + + +## Determine the mount point type +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. + + + +### Determining the mount point type +1. Work out what type of mount your Docker container uses by running this + command, which returns either `volume` or `bind`: + + ```bash + docker inspect timescaledb --format='{{range .Mounts }}{{.Type}}{{end}}' + ``` + +1. Get the current name or mount path with this command, and record it to use + when you perform the upgrade. Make sure you copy the correct command, based + on your mount point type. + + For volume mounts: + + ```bash + docker inspect timescaledb --format='{{range .Mounts }}{{.Name}}{{end}}' + 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c + ``` + + For bind mounts: + + ```bash + docker inspect timescaledb --format='{{range .Mounts }}{{.Source}}{{end}}' + /path/to/data + ``` + + + +## Upgrade TimescaleDB within Docker +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: + + ```bash + docker pull timescale/timescaledb-ha:pg14-latest + ``` + +1. Stop the old container, and remove it: + + ```bash + docker stop timescaledb + docker rm timescaledb + ``` + +1. 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: + + ```bash + docker run -v 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb + ``` + + For bind mounts: + + ```bash + docker run -v /path/to/data:/var/lib/postgresql/data -d --name timescaledb -p 5432:5432 timescale/timescaledb + ``` + +1. Connect to the upgraded instance using `psql` with the `-X` flag: + + ```bash + docker exec -it timescaledb psql -U postgres -X + ``` + +1. At the psql prompt, use the `ALTER` command to upgrade the extension: + + ```sql + ALTER EXTENSION timescaledb UPDATE; + ``` + + diff --git a/timescaledb/how-to-guides/upgrades/upgrade-pg.md b/timescaledb/how-to-guides/upgrades/upgrade-pg.md new file mode 100644 index 000000000000..407528c964f4 --- /dev/null +++ b/timescaledb/how-to-guides/upgrades/upgrade-pg.md @@ -0,0 +1,73 @@ +# Upgrade PostgreSQL +Because TimescaleDB is a PostgreSQL extension, you need to ensure you keep your +underlying PotsgreSQL installation up to date. When you upgrade your TimescaleDB +extension to a new version, always take the time to check if you need to also +upgrade your PostgreSQL version. If you are running an older version of +PostgreSQL, you need to upgrade it first, before you upgrade your TimescaleDB +extension. + +TimescaleDB supports these PostgreSQL releases. If you are not running a +compatible PostgreSQL version, make sure you upgrade PostgreSQL before you +upgrade TimescaleDB: + +||PostgreSQL 9.6|PostgreSQL 10|PostgreSQL 11|PostgreSQL 12|PostgreSQL 13|PostgreSQL 14| +|-|-|-|-|-|-|-| +|TimescaleDB 1.7|✅|✅|✅|✅|❌|❌| +|TimescaleDB 2.0|❌|❌|✅|✅|❌|❌| +|TimescaleDB 2.1|❌|❌|✅|✅|✅|❌| +|TimescaleDB 2.2|❌|❌|✅|✅|✅|❌| +|TimescaleDB 2.3|❌|❌|✅|✅|✅|❌| +|TimescaleDB 2.4|❌|❌|❌|✅|✅|❌| +|TimescaleDB 2.5 and higher|❌|❌|❌|✅|✅|✅| + +You need to upgrade PostgreSQL and TimescaleDB in two separate steps. This is so +that you can make sure each upgrade completes properly. For example, if you are +running PostgreSQL 10 and TimescaleDB 1.7.5, and you want to upgrade +to PostgreSQL 13 and TimescaleDB 2.2, upgrade in this order: + +1. Upgrade PostgreSQL 10 to PostgreSQL 12 +1. Upgrade TimescaleDB 1.7.5 to TimescaleDB 2.2 on PostgreSQL 12 +1. Upgrade PostgreSQL 12 to PostgreSQL 13 with TimescaleDB 2.2 + installed + +## Plan your upgrade +You can upgrade your PostgreSQL installation in-place. This means +that you do not need to dump and restore your data. However, it is still +important that you plan for your upgrade ahead of time. + +Before you upgrade: + +* Read [the release notes][pg-relnotes] for the PostgreSQL version you are + upgrading to. +* [Perform a backup][backup] of your database. While PostgreSQL and + TimescaleDB upgrades are performed in-place, upgrading is an intrusive + operation. Always make sure you have a backup on hand, and that the backup is + readable in the case of disaster. + +## Upgrade PostgreSQL +You can use the [`pg_upgrade`][pg_upgrade] tool to upgrade PostgreSQL in-place. +This means that you do not need to dump and restore your data. Instead, +`pg_upgrade` allows you to retain the data files of your current PostgreSQL +installation while binding the new PostgreSQL binary runtime to them. This is +supported for PostgreSQL 8.4 and higher. + + + +### Upgrading PostgreSQL + +1. Before you begin, determine the location of the PostgreSQL binary and your + data directory on your local system. +1. At the psql prompt, perform the upgrade: + ```sql + pg_upgrade -b -B -d -D + ``` + + + +If you are moving data to a new physical instance of PostgreSQL, you can use the +`pg_dump` and `pg_restore` tools to dump your data from the old database, and +then restore it into the new, upgraded, database. For more information, see the [backup and restore section][backup]. + +[pg_upgrade]: https://www.postgresql.org/docs/current/static/pgupgrade.html +[backup]: /timescaledb/:currentVersion:/how-to-guides/backup-and-restore/ +[pg-relnotes]: https://www.postgresql.org/docs/release/