Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0

To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.x, first follow these steps to upgrade your InfluxDB beta instance, data, and resources to InfluxDB 2.0.

Depending on how you have set up your InfluxDB beta instance and the importance of your existing resources and data, you can determine which steps apply to you–for example, if you don’t want to migrate your data and resources, then you can skip those sections.

  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

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 and install InfluxDB 2.0 for your system, but don’t run the setup process yet. 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 appears:

  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 path has changed for InfluxDB v2, 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 visiting your InfluxDB beta instance URL (probably http://localhost:9999) and logging in. Your data and resources should still be there.

If you see a “missing migration” error, manually edit your bolt file to remove the migration–for example:

  1. Recommended: Backup your old influxd.bolt file–manually editing this file could cause you to lose all your data.
  2. Use BoltBrowser to open and edit your old influxd.bolt file
  3. To remove the migration, 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

Recommended: rename 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>

To list configurations, enter the following command:

  1. influx config ls

The output lists the configuration profile for your old instance:

  1. Active  Name        URL                    Org
  2. *       influx_old  http://localhost:9999  InfluxData

b. Configure new profile

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

The influx setup command automatically creates a config profile named default. Make sure you don’t already have a profile with that name before you run the command.

Run the influx setup command and answer the prompts.

Don’t use the same bucket name as a bucket in your existing instance. Otherwise, a name collision and file conflict occurs when you try to copy your resources. You’ll delete this dummy bucket later, after you migrate your resources.

  1. influx setup

The command prompts you to configure credentials:

  1. Welcome to InfluxDB 2.0!
  2. Please type your primary username: admin
  4. Please type your password:
  6. Please type your password again:
  8. Please type your primary organization name: InfluxData
  10. Please type your primary bucket name: dummy_bucket
  12. Please type your retention period in hours.
  13. Or press ENTER for infinite.:
  15. You have entered:
  16.   Username:          admin
  17.   Organization:      InfluxData
  18.   Bucket:            dummy_bucket
  19.   Retention Period:  infinite
  20. Confirm? (y/n): y
  22. Config default has been stored in /Users/rsavage/.influxdbv2/configs.
  23. User    Organization    Bucket
  24. 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

Use config profiles to export all resources from the old instance and apply 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.)

The output is a list of the resources created in your new instance. If successful, you can delete the bucket created during the setup.

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

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 you haven’t yet migrated your old data.

8. Set up integrations to point to new instance

Re-enable any integrations you disabled in step 2. You will need to 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.

Upgrade to the latest InfluxDB v2 version

Follow steps to upgrade from InfluxDB 2.0 to the latest InfluxDB 2.x version.