influxdata / influxdata/influxdb

Improve DX for parameter `host` of the `backup` command

Open
#24,542 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
31.7k
Forks
3.7k
Avg merge
13h 37m
Merged PRs (30d)
8

Description

## Describe Development Experience Issue:

Here is the documentation I'm referring to: https://docs.influxdata.com/influxdb/v2/reference/cli/influx/backup/
I find the parameter name `host` to be a bit unintuitive. "host" in my experience when used in parameters is usually an abbreviation for hostname, which would mean one would be expected to enter a value like `localhost` or maybe `localhost:8086`, but the parameter expects the protocol to be included as well, as is clearly shown by the example and the mentioning of "HTTP address". This is further exacerbated by showing an unintuitive error message when you forget to put `http://` in front of the host value.

Also, the terms "host", "address" and "URL" don't seem to be used consistently in the docs, see for example: https://docs.influxdata.com/influxdb/v2/reference/urls/ where it says: "Default host: `localhost`" (which contradicts the `host` parameter for `backup`). Later on it says "Customize your InfluxDB OSS URL" mentioning `http-bind-address` which only includes hostname and port but no protocol? And the page's name is "InfluxDB OSS URLs"

### Steps to reproduce:

1. Run `influx backup --host myinfluxdb:8086`

### Desired result:

Backup runs through successfully or shows a descriptive error.

I could imagine one or multiple of the following possible solutions:
- When no protocol is added, show an error that the protocol is missing
- When no protocol is added, implicitly add `http://` and if it fails, show a warning that `http://` was automatically prepended to the host
- When a port is missing, show an error that the port is missing.
- When a port is missing, implicitly add `:8086` at the end and if it fails, show a warning that `:8086` was appended and that the port might be different.
- Rename `host` parameter to `address` (maybe with a deprecation notice and a temporary alias to `host` for compatibility, which is removed in a future major version)

### Actual result:

The following error is shown:
```
Error: API compatibility check failed: Get "myinfluxdb:///health": unsupported protocol scheme "myinfluxdb"
```

## Hardware Environment:

The following sections are not relevant for this issue, but are provided anyways.

- Package: Cloud VM
- CPU: 4
- Memory: 24 GB
- Block Device: unknown

## Operating System:

`Linux 5.15.0-1049-oracle #55-Ubuntu SMP Mon Nov 20 19:53:49 UTC 2023 aarch64 aarch64 aarch64 GNU/Linux`

## Code Editing Tool:

None, execute command using SSH in bash

## Build Environment:

[ ] I'm using sccache

Bash

Contributor guide

Open the contributing guide

Research direction

Start with the `influx backup` command and the backup documentation at https://docs.influxdata.com/influxdb/v2/reference/cli/influx/backup/, then compare its `host` handling with the URL terminology at https://docs.influxdata.com/influxdb/v2/reference/urls/. The issue offers several possible resolutions, so completion would require choosing and implementing a consistent parameter or error behavior, with `influx backup --host myinfluxdb:8086` producing a successful or descriptive result.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.