Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0 (stable)

To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.0rc0 or later, manually upgrade all resources and data to the latest version by completing the following steps:

  1. Disable existing integrations
  2. Stop existing InfluxDB beta instance
  3. (Optional) Rename existing InfluxDB binaries
  4. Move existing data and start the latest InfluxDB
  5. Start old InfluxDB beta instance
  6. Create configuration profiles for the InfluxDB CLI
  7. Copy all resources from old instance to the new one
  8. Set up integrations to point to new instance
  9. Load historical data into new instance

Depending on how you have things set up and how important the data stored in InfluxDB is, you can determine which steps apply to you. For example, if there’s nothing in your existing InfluxDB beta instance you need to keep, skip the sections about migrating resources and data to the new instance.

Why is this manual process required?

To ensure that existing InfluxQL integrations work with the latest release, we had to make breaking changes to the underlying storage engine for InfluxDB 2.0.

If you have questions while upgrading, open an issue or join the Community Slack workspace to get immediate help.

1. Disable existing integrations

To begin, shut off all integrations that are reading from, writing to, or monitoring your InfluxDB instance. This includes Telegraf, client libraries, and any custom applications.

2. Stop existing InfluxDB beta instance

Next, shut down your existing InfluxDB beta instance. You can manually stop the individual process using Control+c (or by finding the process ID with ps aux | grep -i influxd and using sudo kill -9 <PID>). If you’ve set influxd to run as a system process, follow the same steps you would use to disable any system process.

3. (Optional) Rename existing InfluxDB binaries

To easily identify your existing InfluxDB binaries, rename them influx_old and influxd_old. This is helpful if you’ve installed the binaries in your $PATH. We use the names influxd_old for this guide, but you can use whatever you like.

4. Move existing data and start the latest InfluxDB

If you haven’t already, download the InfluxDB OSS 2.0rc. Download and follow the install instructions for influxd and influx. Be careful not to overwrite the existing binaries.

To move data between the two instances, first configure both the old and new instances of InfluxDB to run at the same time. If you download the latest InfluxDB beta and try to start it with existing data, most likely it won’t start and the following error message will appear:

  1. Incompatible InfluxDB 2.0 version found.
  2. Move all files outside of engine_path before influxd will start.

To avoid this error, run the following command to move your existing data to a another location (anywhere you like):

  1. mv ~/.influxdbv2 ~/.influxdbv2_old

Start the latest InfluxDB version by running:

  1. influxd

If you were using specific command line flags for InfluxDB beta, you can use those same command line flags.

Because the data folder has been moved, everything will be empty. You can visit http://localhost:8086 in your browser and see a setup page, but don’t go through the setup process yet.

5. Start old InfluxDB beta instance

You can now start your old InfluxDB instance and point it to your old data directory:

  1. ./influxd_old \
  2.     --bolt-path ~/.influxdbv2_old/influxd.bolt \
  3.     --engine-path ~/.influxdbv2_old/engine

Double-check that InfluxDB is working by going to your previous InfluxDB beta location (probably http://localhost:9999) and logging in. Everything should still be there.

If you run into a problem about a missing migration, manually edit your bolt file to remove it. Use BoltBrowser to open and edit your old influxd.bolt file and manually remove the migration.

Caution: Backup your old influxd.bolt file before doing this, as manually editing this file could cause you to lose all your data.

Highlight the record under the migrationsv1 path and press D.

Now, the new instance and old instance of InfluxDB are running simultaneously.

6. Create configuration profiles for the InfluxDB CLI

Next, set up your InfluxDB CLI to connect to your old and new instances.

a. Configure old profile

If you’ve used the CLI before, copy your existing configs file to your new data directory:

  1. cp ~/.influxdbv2_old/configs ~/.influxdbv2/configs

We recommend renaming the old configuration file to something like influx_old.

  1. [influx_old]
  2.   url = "http://localhost:9999"
  3.   token = "<YOUR TOKEN>"
  4.   org = "influxdata"
  5.   active = true

If you’ve never used the CLI before, create a new configuration profile to connect to your old instance using the influx config command.

  1. influx config create \
  2.     --config-name influx_old \
  3.     --host-url http://localhost:9999 \
  4.     --org influxdata \
  5.     --token <OLD_TOKEN>

Now when you run influx config ls, you will see a profile for your old instance.

  1. $ influx config ls
  2. Active  Name        URL                    Org
  3. *       influx_old  http://localhost:9999  InfluxData

b. Configure new profile

Next set up your new instance, which will automatically create a configuration profile for you.

The influx setup command will create a config profile named default automatically, make sure you don’t already have a profile with that name before the command.

Run the influx setup command and answer the prompts.

To avoid a file conflict, don’t use the same name as a bucket in your existing instance. Otherwise, there will be a collision when you try to copy your resources over. We will delete this dummy bucket after everything is moved over.

  1. $ influx setup
  2. Welcome to InfluxDB 2.0!
  3. Please type your primary username: admin
  5. Please type your password:
  7. Please type your password again:
  9. Please type your primary organization name: InfluxData
  11. Please type your primary bucket name: dummy_bucket
  13. Please type your retention period in hours.
  14. Or press ENTER for infinite.:
  16. You have entered:
  17.   Username:          admin
  18.   Organization:      InfluxData
  19.   Bucket:            dummy_bucket
  20.   Retention Period:  infinite
  21. Confirm? (y/n): y
  23. Config default has been stored in /Users/rsavage/.influxdbv2/configs.
  24. User    Organization    Bucket
  25. admin    InfluxData    dummy_bucket

You now have two config profiles: one named default that points to your new instance, and one named influx_old that points to your old instance.

  1. $ influx config ls
  2. Active  Name        URL                    Org
  3.         default     http://localhost:8086  InfluxData
  4. *       influx_old  http://localhost:9999  InfluxData

You can now send commands to each of them as needed using the -c, --active-config option in the CLI.

7. Copy all resources from old instance to the new one

We will use config profiles here to export all resources from the old instance and applying them to your new instance. (The only things that will not be copied over are scraper configurations. You will need to manually reconfigure those.)

Copy all your existing InfluxDB resources, such as dashboards, tasks, and alerts, to your new instance by running the following command:

  1. influx export all -c influx_old | influx apply -c default

(To learn more about this command, see influx export and influx apply.)

This displays a list of the resources being created in your new instance. Assuming everything succeeded, you can delete the bucket created during the setup.

  1. $ influx export all -c influx_old | influx apply -c default
  2. LABELS    +add | -remove | unchanged
  3. +-----+------------------------+----+---------------+---------+-------------+
  4. | +/- |     METADATA NAME      | ID | RESOURCE NAME |  COLOR  | DESCRIPTION |
  5. +-----+------------------------+----+---------------+---------+-------------+
  6. | +   | tasty-northcutt-c9c001 |    | something     | #326BBA |             |
  7. +-----+------------------------+----+---------------+---------+-------------+
  8. |                                                      TOTAL  |      1      |
  9. +-----+------------------------+----+---------------+---------+-------------+
  10. ​
  11. BUCKETS    +add | -remove | unchanged
  12. +-----+------------------------+----+---------------+------------------+-------------+
  13. | +/- |     METADATA NAME      | ID | RESOURCE NAME | RETENTION PERIOD | DESCRIPTION |
  14. +-----+------------------------+----+---------------+------------------+-------------+
  15. | +   | fasting-taussig-c9c007 |    | apps          | 0s               |             |
  16. +-----+------------------------+----+---------------+------------------+-------------+
  17. +-----+------------------------+----+---------------+------------------+-------------+
  18. | +   | great-davinci-c9c005   |    | new_telegraf  | 0s               |             |
  19. +-----+------------------------+----+---------------+------------------+-------------+
  20. +-----+------------------------+----+---------------+------------------+-------------+
  21. | +   | stubborn-hugle-c9c003  |    | telegraf      | 719h59m59s       |             |
  22. +-----+------------------------+----+---------------+------------------+-------------+
  23. |                                                          TOTAL       |      3      |
  24. +-----+------------------------+----+---------------+------------------+-------------+

Now, you have all the resources from your old instance stored in your new instance. Sign in to your new instance (by default http://localhost:8086) and take a look. You will see dashboards, but your old data has not yet been migrated.

8. Set up integrations to point to new instance

Re-enable any integrations you disabled in step 2. You will need re-enable Telegraf, client libraries, custom applications, or third-party data sinks using new tokens and credentials.

9. Load historical data into new instance

Use the CLI to export and then re-import your data using the command below. (For the range, pick a time before your bucket’s retention period, or something a really long time ago if you have an unlimited retention period.)

  1. influx query -c influx_old \
  2.   'from(bucket: "my-bucket") |> range(start: -3y)' --raw > my-bucket.csv

Then write to the new bucket:

  1. influx write -c default --format csv -b my-bucket -f my-bucket.csv

Repeat that process for each bucket.

Verify InfluxDB resources, data, and integrations

Verify that the latest version of InfluxDB is running with all your resources, data, and integrations configured. Double-check that everything is there and it is working as expected. Once you’re set up with the latest InfluxDB, you can safely turn off your old instance and archive the previous data directory.