Manually upgrade from InfluxDB 1.x to 2.1

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

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

Install InfluxDB 2.1

Download, install, and set up InfluxDB 2.1.

Required 2.x credentials

All InfluxDB 2.1 influx CLI examples below assume the required host, organization, and API 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.1 configuration settings:

    View configuration option parity

    1.x configuration option2.1 configuration option
    [data]
    direngine-path
    wal-direngine-path
    wal-fsync-delaystorage-wal-fsync-delay
    index-version
    trace-logging-enabled
    query-log-enabled
    strict-error-handling
    validate-keysstorage-validate-keys
    cache-max-memory-sizestorage-cache-max-memory-size
    cache-snapshot-memory-sizestorage-cache-snapshot-memory-size
    cache-snapshot-write-cold-durationstorage-cache-snapshot-write-cold-duration
    compact-full-write-cold-durationstorage-compact-full-write-cold-duration
    max-concurrent-compactionsstorage-max-concurrent-compactions
    compact-throughput
    compact-throughput-burststorage-compact-throughput-burst
    tsm-use-madv-willneedstorage-tsm-use-madv-willneed
    max-series-per-database
    max-values-per-tag
    max-index-log-file-sizestorage-max-index-log-file-size
    series-id-set-cache-sizestorage-series-id-set-cache-size
    [retention]
    check-intervalstorage-retention-check-interval
    [shard-precreation]
    check-intervalstorage-shard-precreator-check-interval
    advance-periodstorage-shard-precreator-advance-period
    [http]
    flux-enabled
    flux-log-enabled
    bind-addresshttp-bind-address
    auth-enabled
    realm
    log-enabled
    suppress-write-log
    access-log-path
    access-log-status-filters
    write-tracing
    pprof-enabledpprof-disabled
    pprof-auth-enabled
    debug-pprof-enabled
    ping-auth-enabled
    https-enabled
    https-certificatetls-cert
    https-private-keytls-key
    shared-secret
    max-row-limit
    max-connection-limit
    unix-socket-enabled
    bind-socket
    max-body-size
    max-concurrent-write-limit
    max-enqueued-write-limit
    enqueued-write-timeouthttp-write-timeout
    [logging]
    format
    levellog-level
    suppress-logo
    [tls]
    cipherstls-strict-ciphers
    min-versiontls-min-version
    max-version

    1.x configuration groups not in 2.1

    The following 1.x configuration groups do not apply to InfluxDB 2.1:

    • meta
    • coordinator
    • monitor
    • subscriber
    • graphite
    • collectd
    • opentsdb
    • udp
    • continuous_queries

  2. Apply your 1.x custom settings to the comparable InfluxDB 2.1 settings using influxd flags, environment variables, or a 2.1 configuration file. For more information about configuring InfluxDB 2.1, 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.1 buckets. These mappings allow InfluxDB 1.x clients to successfully query and write to InfluxDB 2.1 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.1 bucket:

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

    1. # Naming convention
    2. db-name/rp-name
    4. # Example
    5. telegraf/autogen

  2. Create a DBRP mapping
    Use the influx v1 dbrp create 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

    DB with one RP DB with multiple RPs

    1. influx v1 dbrp create \
    2.   --db example-db \
    3.   --rp example-rp \
    4.   --bucket-id 00xX00o0X001 \
    5.   --default
    1. # Create telegraf/autogen DBRP mapping with autogen
    2. # as the default RP for the telegraf DB
    4. influx v1 dbrp create \
    5.   --db telegraf \
    6.   --rp autogen \
    7.   --bucket-id 00xX00o0X001 \
    8.   --default
    10. # Create telegraf/downsampled-daily DBRP mapping that
    11. # writes to a different bucket
    13. influx v1 dbrp create \
    14.   --db telegraf \
    15.   --rp downsampled-daily \
    16.   --bucket-id 00xX00o0X002

  3. Confirm the DBRP mapping was created
    Use the influx v1 dbrp list to list existing DBRP mappings.

    1. influx v1 dbrp list

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

Create authorizations

InfluxDB 2.1 requires authentication and provides two authentication methods:

Token authentication

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

Recommended if:
  • 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.1 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.1 instance without any change.

Recommended if:
  • 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.1 user interface (UI).

Create a 1.x-compatible authorization

Use the InfluxDB 2.1 influx v1 auth create command to create a 1.x-compatible authorization that grants read/write permissions to specific 2.1 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)

Single bucket Mutiple buckets

  1. influx v1 auth create \
  2.   --read-bucket 00xX00o0X001 \
  3.   --write-bucket 00xX00o0X001 \
  4.   --username example-user
  1. influx v1 auth create \
  2.   --read-bucket 00xX00o0X001 \
  3.   --read-bucket 00xX00o0X002 \
  4.   --write-bucket 00xX00o0X001 \
  5.   --write-bucket 00xX00o0X002 \
  6.   --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.1:

  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.1 bucket.

    1. # Syntax
    2. influx_inspect export \
    3.   -database <database-name> \
    4.   -retention <retention-policy-name> \
    5.   -out <output-file-path> \
    6.   -lponly
    8. # Example
    9. influx_inspect export \
    10.   -database example-db \
    11.   -retention example-rp \
    12.   -out /path/to/example-db_example-rp.lp \
    13.   -lponly

  2. Use the InfluxDB 2.1 influx write command to write the exported line protocol to InfluxDB 2.1.

    1. # Syntax
    2. influx write \
    3.   --bucket <bucket-name> \
    4.   --file <path-to-line-protocol-file>
    6. # Example
    7. influx write \
    8.   --bucket example-db/example-rp \
    9.   --file /path/to/example-db_example-rp.lp

  3. Repeat steps 1-2 for each bucket.

Migrate continuous queries

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