Documentation

Manually upgrade from InfluxDB 1.x to 2.0

To manually upgrade from InfluxDB 1.x to InfluxDB 2.0:

  1. Install InfluxDB 2.0
  2. Migrate custom configuration settings
  3. Create DBRP mappings
  4. Create authorizations
  5. Migrate time series data
  6. Migrate continuous queries

Install InfluxDB 2.0

Download, install, and set up InfluxDB 2.0.

Required 2.x credentials

All InfluxDB 2.0 influx CLI examples below assume the required host, organization, and authentication token credentials are provided by your influx CLI configuration.

Migrate custom configuration settings

If you’re using custom configuration settings in your InfluxDB 1.x instance, do the following:

  1. Compare 1.x and 2.0 configuration settings:

    View configuration option parity

  2. Apply your 1.x custom settings to the comparable InfluxDB 2.0 settings using influxd flags, environment variables, or a 2.0 configuration file. For more information about configuring InfluxDB 2.0, see Configuration options.

  3. Restart influxd.

Create DBRP mappings

InfluxDB database and retention policy (DBRP) mappings associate database and retention policy combinations with InfluxDB 2.0 buckets. These mappings allow InfluxDB 1.x clients to successfully query and write to InfluxDB 2.0 buckets while using the 1.x DBRP convention.

For more information about DBRP mapping, see Database and retention policy mapping.

To map a DBRP combination to an InfluxDB 2.0 bucket:

  1. Create a bucket
    Create an InfluxDB 2.0 bucket. We recommend creating a bucket for each unique 1.x database and retention policy combination using the following naming convention:

    # Naming convention
    db-name/rp-name
    
    # Example
    telegraf/autogen
    
  2. Create a DBRP mapping
    Use the influx v1 dbrp create command command to create a DBRP mapping. Provide the following:

    • database name
    • retention policy name (not retention period)
    • bucket ID
    • (optional) --default flag if you want the retention policy to be the default retention policy for the specified database
    influx v1 dbrp create \
      --db example-db \
      --rp example-rp \
      --bucket-id 00xX00o0X001 \
      --default
    
    # Create telegraf/autogen DBRP mapping with autogen
    # as the default RP for the telegraf DB
    
    influx v1 dbrp create \
      --db telegraf \
      --rp autogen \
      --bucket-id 00xX00o0X001 \
      --default
    
    # Create telegraf/downsampled-daily DBRP mapping that
    # writes to a different bucket
    
    influx v1 dbrp create \
      --db telegraf \
      --rp downsampled-daily \
      --bucket-id 00xX00o0X002
    
  3. Confirm the DBRP mapping was created
    Use the influx v1 dbrp list to list existing DBRP mappings.

    influx v1 dbrp list
    

For information about managing DBRP mappings, see the influx v1 dbrp command documentation.

Create authorizations

InfluxDB 2.0 requires authentication and provides two authentication methods:

Token authentication

Use InfluxDB 2.0 token authentication to authenticate requests to InfluxDB 2.0.

  • Your 1.x instance does not have authentication enabled.

Use tokens with basic authentication

To use tokens with InfluxDB clients that require an InfluxDB username and password, provide an arbitrary user name and pass the token as the password.

1.x-compatible authorizations

InfluxDB 2.0 provides a 1.x compatibility API that lets you authenticate using a username and password as in InfluxDB 1.x. If authentication is enabled in your InfluxDB 1.x instance, create a 1.x-compatible authorization with the same username and password as your InfluxDB 1.x instance to allow external clients to connect to your InfluxDB 2.0 instance without any change.

  • Your 1.x instance has authentication enabled.
  • You’re using InfluxDB 1.x clients or client libraries configured with InfluxDB usernames and passwords.

1.x compatibility authorizations are separate from credentials used to log into the InfluxDB 2.0 user interface (UI).

Create a 1.x-compatible authorization

Use the InfluxDB 2.0 influx v1 auth create command to create a 1.x-compatible authorization that grants read/write permissions to specific 2.0 buckets. Provide the following:

  • list of bucket IDs to grant read or write permissions to
  • new v1 auth username
  • new v1 auth password (when prompted)
influx v1 auth create \
  --read-bucket 00xX00o0X001 \
  --write-bucket 00xX00o0X001 \
  --username example-user
influx v1 auth create \
  --read-bucket 00xX00o0X001 \
  --read-bucket 00xX00o0X002 \
  --write-bucket 00xX00o0X001 \
  --write-bucket 00xX00o0X002 \
  --username example-user

For information about managing 1.x compatible authorizations, see the influx v1 auth command documentation.

Migrate time series data

To migrate time series data from your InfluxDB 1.x instance to InfluxDB 2.0:

  1. Use the InfluxDB 1.x influx_inspect export command to export time series data as line protocol. Include the -lponly flag to exclude comments and the data definition language (DDL) from the output file.

    We recommend exporting each DBRP combination separately to easily write data to a corresponding InfluxDB 2.0 bucket.

    # Syntax
    influx_inspect export \
      -database <database-name> \
      -retention <retention-policy-name> \
      -out <output-file-path> \
      -lponly
    
    # Example
    influx_inspect export \
      -database example-db \
      -retention example-rp \
      -out /path/to/example-db_example-rp.lp \
      -lponly
    
  2. Use the InfluxDB 2.0 influx write command to write the exported line protocol to InfluxDB 2.0.

    # Syntax
    influx write \
      --bucket <bucket-name> \
      --file <path-to-line-protocol-file>
    
    # Example
    influx write \
      --bucket example-db/example-rp \
      --file /path/to/example-db_example-rp.lp
    

Repeat this process for each bucket.

Migrate continuous queries

For information about migrating InfluxDB 1.x continuous queries to InfluxDB 2.0 tasks, see Migrate continuous queries to tasks.


Cloud or OSS?

InfluxDB OSS 2.0 now generally available!

InfluxDB OSS 2.0 is now generally available and ready for production use. See the InfluxDB OSS 2.0 release notes.

For information about upgrading to InfluxDB OSS 2.0, see: