[sqlx-cli] --source flag is difficult to discover and confusing to use

[DanielJoyce]

No way to override migrations directory for CLI.

[abonander]

It does, but it's a command line flag:

$ sqlx mig --help
sqlx-migrate 
Group of commands for creating and running migrations

USAGE:
    sqlx migrate [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help
            Prints help information

    -V, --version
            Prints version information


OPTIONS:
        --source <source>
            Path to folder containing migrations [default: migrations]

...

I'd be open to maybe adding a way to specify this via a config file, but the --source flag should work at least. If not that's a bug.

[abonander]

Hmm, the --source flag doesn't show up in the help message for the subcommands, so I can see how it might be easy to miss:

$ sqlx migrate add --help
sqlx-migrate-add 
Create a new migration with the given description, and the current time as the version

USAGE:
    sqlx migrate add [FLAGS] <description>

ARGS:
    <description>    

FLAGS:
    -h, --help       Prints help information
    -r               If true, creates a pair of up and down migration files with same version else
                     creates a single sql file
    -V, --version    Prints version information

I wonder if that's a Clap bug or if we structured the subcommands wrong.

[abonander]

Okay, so Clap treats --source as an option to the migrate command and not the subcommand, so you need to pass it before the subcommand, which is confusing:

$ sqlx migrate run --source foo
error: Found argument '--source' which wasn't expected, or isn't valid in this context

	If you tried to supply `--source` as a value rather than a flag, use `-- --source`

USAGE:
    sqlx migrate run [OPTIONS] --database-url <DATABASE_URL>

For more information try --help

Versus:

$ sqlx migrate --source foo run
error: while resolving migrations: No such file or directory (os error 2)

(This is the error I'd expect as the foo directory doesn't exist.)

So the solution here would be to copy source here: https://github.com/launchbadge/sqlx/blob/master/sqlx-cli/src/opt.rs#L106-L107

To every variant of MigrateCommand below. However, to not break existing usage we should still keep source where it's at now as well, maybe mark it as deprecated if we can, and have --source on the subcommand override the value if it is not the default.

[azzamsa]

Hmm, the --source flag doesn't show up in the help message for the subcommands, so I can see how it might be easy to miss:

Yes. That's why I create the issue #1666. Should we explain about this in the Readme?