InfluxDB

New in version 2.1.8 To backup InfluxDB with borgmatic, use the influxdb_databases: hook. For instance:

influxdb_databases:
    - name: mybucket
      password: mytoken

This hook requires the influx command-line tool from InfluxDB 2.x, as borgmatic dumps and restores with influx backup and influx restore. Because those commands produce a directory of files rather than a single file, this hook writes each dump to temporary disk space instead of streaming it directly to Borg.

See below for the full set of configuration options available, including hostname, organization, TLS settings, etc.

InfluxDB versions

This hook supports InfluxDB 2.x only. InfluxDB 3 has no means of producing a local database dump, so there's nothing for borgmatic to include in a backup:

• InfluxDB 3 Core has no backup or restore commands at all. Backing it up means copying its object store by hand in a particular order.
• InfluxDB 3 Enterprise added backup and restore in 3.11, but a backup goes to the server's own object store rather than to a path of your choosing, and the command returns as soon as the backup starts instead of when it finishes.

The 2.x influx command-line tool can't bridge the gap either, because its backup and restore commands use the /api/v2/backup and /api/v2/restore endpoints, which InfluxDB 3 doesn't implement.

Supporting InfluxDB 3 therefore calls for a separate hook that works differently, which may come in a future version of borgmatic.

Buckets

The name option is the name of the InfluxDB bucket to dump. To dump every bucket in an instance instead, set it to all:

influxdb_databases:
    - name: all
      password: mytoken

If you'd rather select a bucket by ID than by name, set the bucket_id option. It takes precedence over the bucket named by name (but name is still used to identify the dump within the backup, so it remains required):

influxdb_databases:
    - name: mybucket
      bucket_id: 06fc0dfd1a97b4c1
      password: mytoken

Organizations work the same way: organization_id takes precedence over organization_name when both are given.

Authentication

The password option is an InfluxDB API token. It's named password rather than token so that borgmatic's own password handling applies to it (which means you can keep it out of your configuration file with the {credential ...} syntax):

influxdb_databases:
    - name: mybucket
      password: "{credential file /credentials/influxdb_token.txt}"

borgmatic gives the token to the influx command-line tool via the INFLUX_TOKEN environment variable rather than a command-line flag, so it doesn't show up in the process list for other users on the same machine to see.

Alternatively, omit password entirely and let the influx command-line tool supply the token from its own configuration, selected with the active_configuration option and optionally located with configurations_path:

influxdb_databases:
    - name: mybucket
      active_configuration: myconfig

Restoring

By default, borgmatic restores each bucket back to the bucket and organization it was dumped from. Use restore_bucket and restore_organization to restore somewhere else instead, and full_replace to replace all data on the server rather than merging into it.

You can also override the connection settings at restore time without editing your configuration:

borgmatic restore --data-source mybucket --hostname influx.example.org --port 8086 --password othertoken

Full configuration

Here's an example configuration with all of the available options for this feature in the most recent version of borgmatic. If you're using an older version, some of these options may not work, and you should instead generate a sample configuration file specific to your borgmatic version.

influxdb_databases:
    # Bucket name to dump (required if using this hook). Or
    # "all" to dump all buckets on the host. Ignored for
    # dumping purposes if "bucket_id" is given, but still
    # used to identify the dump in the backup.
    - name: mybucket

      # The ID of the bucket to backup. Takes precedence over
      # the bucket named by the "name" option.
      bucket_id: 3c9bb0c293be4658

      # Label to identify the database dump in the backup.
      label: my_backup_label

      # The InfluxDB executable to use, from InfluxDB 2.x.
      # InfluxDB 3 is not supported. Defaults to "influx".
      influx_command: /usr/local/bin/influx

      # InfluxDB API token used to authenticate requests. This
      # option is named "password" rather than "token" (which
      # would better suit InfluxDB terminology) so that
      # borgmatic's native password handling applies. Omit it
      # when the token comes from the influx CLI configuration
      # selected by "active_configuration". Supports the
      # "{credential ...}" syntax.
      password: trustsome1

      # Selects if using HTTP (false) or HTTPS (true).
      # Defaults to true.
      tls: false

      # InfluxDB hostname/IP to connect to.
      # Defaults to localhost.
      hostname: localhost

      # Port to connect to. Defaults to 8086.
      port: 8086

      # The ID of the organization.
      organization_id: ccf6258c1e195e27

      # The name of the organization. Ignored if
      # "organization_id" is also provided.
      organization_name: my-org

      # Path to the influx CLI configurations.
      configurations_path: /root/.influxdbv2/configs

      # Config name to use for command.
      active_configuration: default

      # New name to use for the restored bucket.
      restore_bucket: mybucket-restored

      # New name to use for the restored organization.
      restore_organization: my-org-restored

      # Verify the TLS certificate chain and host name of the
      # InfluxDB host. Defaults to true.
      verify_tls: false

      # Fully restore and replace all data on server.
      # Defaults to false.
      full_replace: true

      # Compression to use for local backup files, either
      # "none" or "gzip". Defaults to "gzip".
      compression: none

Related documentation

• How to backup your databases