launchbadge
Document down migrations
sqlx migrate revert --help states Revert the latest migration with a down file but its not clear what a "down file" is.
It would be helpful to either document the usage of down migrations (in README and in CLI?) or to implement #356 or both.
#356 should be closed, sqlx migrate add already has a -r flag to create a set of up / down migrations.
sqlx migrate -r add create_main_table
error: unexpected argument '-r' found
@mammothcoding
sqlx migrate -r add create_main_tableerror: unexpected argument '-r' found
Usage: sqlx migrate add [OPTIONS] <DESCRIPTION>
sqlx migrate add -r create_users_table creates two files: 20241231141112_create_users_table.up.sql and 20241231141112_create_users_table.down.sql.
sqlx migrate run executes "up" files and sqlx migrate revert executes "down" ones.
@mammothcoding
sqlx migrate -r add create_main_tableerror: unexpected argument '-r' foundUsage: sqlx migrate add [OPTIONS]
sqlx migrate add -r create_users_tablecreates two files:20241231141112_create_users_table.up.sqland20241231141112_create_users_table.down.sql.
sqlx migrate runexecutes "up" files andsqlx migrate revertexecutes "down" ones.
Don't work :(
sqlx migrate add -r create_main_table
Creating migrations/20250101152639_create_main_table.sql
sqlx = "0.8.2"
sqlx-cli = "0.8.2"
This is poorly documented, but the -r flag only has effect when making the first migration. Subsequent migrations will automatically use the same mode.
Would it be worth adding a warning there when the migration type doesn't match up? i.e. when the user requests reversible migrations, but the first migration wasn't created as reversible?
Looking at https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md, arguably it is documented. I have the feeling the documentation could be a bit more clear at some points, but it is there.
A bigger problem IMO would be that the documentation is not accessible. It isn't where people would search for it, which means they don't find it.
(I for example wouldn't naturally look for a readme, of a subproject of the crate that I installed via cargo add)
(Granted it is linked from the main readme, but still ...)
I think the best solution might be to unify all the docs in docs.rs and unify them in a few "stub-modules". (The actual text could still be written in markdown documents which can be included using #[doc = include_str!("<file-path>")])
The ideal would of cause be to have a small tutorial that goes over the most important concepts and gives a short intro to how it is recommended to use the crate.
My reflex was to --help from the CLI (as did OP apparently). As shown below, the information is actually present, in an introduction text. However, I am used to jump the the relevant option (here -r), so I missed the text entirely. In my case, a simple comment in the description of -r that references the introduction text would be enough.
~% sqlx migrate add --help
Create a new migration with the given description.
A version number will be automatically assigned to the migration.
For convenience, this command will attempt to detect if sequential versioning is in use, and if so, continue the sequence.
Sequential versioning is inferred if:
* The version numbers of the last two migrations differ by exactly 1, or:
* only one migration exists and its version number is either 0 or 1.
Otherwise timestamp versioning is assumed.
This behavior can overridden by `--sequential` or `--timestamp`, respectively.
Usage: sqlx migrate add [OPTIONS] <DESCRIPTION>
Arguments:
<DESCRIPTION>
Options:
--source <SOURCE>
Path to folder containing migrations
[default: migrations]
-r
If true, creates a pair of up and down migration files with same version else creates a single sql file
-t, --timestamp
If set, use timestamp versioning for the new migration. Conflicts with `--sequential`
-s, --sequential
If set, use sequential versioning for the new migration. Conflicts with `--timestamp`
-h, --help
Print help (see a summary with '-h')
Looking at https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md, arguably it is documented. I have the feeling the documentation could be a bit more clear at some points, but it is there.
A bigger problem IMO would be that the documentation is not accessible. It isn't where people would search for it, which means they don't find it. (I for example wouldn't naturally look for a readme, of a subproject of the crate that I installed via
cargo add)(Granted it is linked from the main readme, but still ...)
I think the best solution might be to unify all the docs in docs.rs and unify them in a few "stub-modules". (The actual text could still be written in markdown documents which can be included using
#[doc = include_str!("<file-path>")])The ideal would of cause be to have a small tutorial that goes over the most important concepts and gives a short intro to how it is recommended to use the crate.
It's definitely confusing, the command line -h documentation should definitely mention it only does something for the first migration if that is the intended behavior.
It just says:
-r If true, creates a pair of up and down migration files with same version else creates a single sql file
Either way I think this command should override the behavior of the first migration file. As you can make .up .down files manually and it works perfectly fine even if the the first file is not .up
Can I work on this? I think I have a fix for it? BTW i am new to open source contributions so I would appreciate if someone can guide me if possible after I write my solution.
Can I work on this? I think I have a fix for it? BTW i am new to open source contributions so I would appreciate if someone can guide me if possible after I write my solution.
As in document the feature? Sure feel free