Some suggestions for command-line use

[LarryBrasfield]

After quite a few bad starts, I finally got litestream working from the command line without having to do anything requiring root privilege. Thankfully, in part due to help from error messages, I was able to get to a good start. I thought to share these observations:

1. I had to do a web search to learn of the option, -config <filename> . The docs were utterly silent on this, other than hinting that such an option might exist by referring to "the default configuration" file. All options need to be mentioned somewhere, and should appear in an index or the like.
2. It took a good while to experimentally discover that the command, "litestream -config ~/.litestream somecommand" was never going to work. The command line parser should allow globally applicable options to appear early, before the subcommand. In general, positional dependence should be avoided for options.
3. While using (or trying to use) sftp transport from the command line, (because I despaired of getting litestream to know of my config file as a non-privileged user), I had to change the destination account password multiple times. The litestream command-line parser needs a quoting mechanism, or options to pass in parameters that can be quoted at the invoking shell level. Passwords with spaces, question marks, exclamation marks, and likely many more, cannot be passed in the do-it-all command-line format now documented.
4. It is utterly unclear what PATH means in the command-line invocation summaries. I finally deduced that it means a directory on the replication destination. Tens of minutes would have been saved if that had been made clear in the doc(s).
5. The doc on the restore subcommand is unclear about whether the about-to-be-restored DB name can be something new (because the original is still there) or must be the original name so that litestream can know which DB to get from the server. It would help if there was a description of the mapping between DB names at the "client" side and their replication names elsewhere.

FWIW, I'm using litestream as part of a liteweight work-product preservation scheme for Fossil repositories that are taking dozens of work-in-progress checkins per day. I want something that can be private to a user who has access to multiple machines but dislikes using root privilege for getting data movement that does not, in and of itself, require such privilege. (This is about that config file.)

Just in case this seems whiny: I appreciate litestream as a tool, and I hope my feedback can help improve it.

-Larry Brasfield

[LarryBrasfield]

Another few observations and suggestions:

6. For some reason, it is not enough to redirect stdin, stdout and stderr to keep litestream from littering a terminal screen when it put into the background. In fact, when those outputs are redirected to a file, it remains empty.

7. It would be nice to know how to stop litestream (when running in background) in such a way to have it exit gracefully rather than leaving shm and wal files behind.

[benbjohnson]

Thanks for all the feedback, @LarryBrasfield. It's always good to get some new perspective.

I had to do a web search to learn of the option, -config . The docs were utterly silent on this...

Which docs were you looking at? It appears in litestream replicate -h as well as the website docs for litestream replicate. Are you suggesting to add it to the Getting Started page?

The command line parser should allow globally applicable options to appear early, before the subcommand. In general, positional dependence should be avoided for options.

Yeah, I agree that the command line parser should be more flexible. I'm a bit torn on it as that requires importing a third party parser library and I generally dislike most of the CLI parser libraries for Go.

The litestream command-line parser needs a quoting mechanism, or options to pass in parameters that can be quoted at the invoking shell level. Passwords with spaces, question marks, exclamation marks, and likely many more, cannot be passed in the do-it-all command-line format now documented.

Can you pass in using single quotes? I'm not sure what you mean by a quoting mechanism as it seems like escaping should be done at the shell level.

It is utterly unclear what PATH means in the command-line invocation summaries

That's a fair point. I can update the docs to clarify that it's the database path.

The doc on the restore subcommand is unclear about whether the about-to-be-restored DB name can be something new (because the original is still there) or must be the original name so that litestream can know which DB to get from the server. It would help if there was a description of the mapping between DB names at the "client" side and their replication names elsewhere.

Sure, I can clarify that in the docs.

For some reason, it is not enough to redirect stdin, stdout and stderr to keep litestream from littering a terminal screen when it put into the background. In fact, when those outputs are redirected to a file, it remains empty.

That seems surprising. Litestream uses Go's log package which defaults to use stderr. What's the command you're using to redirect stderr?

_ It would be nice to know how to stop litestream (when running in background) in such a way to have it exit gracefully rather than leaving shm and wal files behind._

I believe SQLite leaves the -shm and -wal files in place on exit by default when in WAL mode, correct? I just tried running sqlite3 on a local database, creating a table, and exiting and it's left those two files.

[chmaynard]

I generally dislike most of the CLI parser libraries for Go.

Take a look at https://github.com/docopt/docopt.go