feat!: support for rolling back migrations by ElijahAhianyo · Pull Request #583 · cot-rs/cot

ElijahAhianyo · 2026-06-02T03:02:46Z

Related issue or discussion

fixes #547

Description

This allows rolling back migrations to the specified migration file.

Assuming the project has the following migration files in its migration dir:

├── migrations
 │   └── m_0001_initial.rs
 |   └── m_0002_second.rs

./target/debug/foo migration rollback m_0001_initial

The above command will roll back(unapply) the m_0002_second file, leaving m_0001_initial applied.
Alternatively, the migration file number can be used for convenience:

./target/debug/foo migration rollback 0001

Migrations are currently tied to a crate(the crate name is used), which means rolling back a migration in a project that imports apps from external crates will implicitly (and only) rollback migrations in the current project/crate. This might change when support for workspaces is added

As a bonus, this PR also adds CLI Group tasks as a means to group nested related subcommands under a parent subcommand:

Eg.

     use async_trait::async_trait;
     use clap::{ArgMatches, Command};
     use cot::cli::{Cli, CliTask, CliTaskGroup};
     use cot::project::WithConfig;
     use cot::{Bootstrapper, Project};
    
     struct Frobnicate;
    
     #[async_trait(?Send)]
     impl CliTask for Frobnicate {
         fn subcommand(&self) -> Command {
             Command::new("frobnicate")
                  .about("Test frobnicate command")

         }
    
         async fn execute(
             &mut self,
             _matches: &ArgMatches,
             _bootstrapper: Bootstrapper<WithConfig>,
         ) -> cot::Result<()> {
             println!("Frobnicating...");
    
             Ok(())
         }
     }
    
     struct MyProject;
     impl Project for MyProject {
         fn register_tasks(&self, cli: &mut Cli) {
             let mut group_command = CliTaskGroup::new("foo").about("Foo related commands");
             group_command.add_task(Frobnicate);
             cli.add_task(group_command);
        }
   }

Type of change

github-actions · 2026-06-02T03:07:14Z

Bencher Report

Project	cot
Branch	elijah/migrations-rollback
Testbed	github-ubuntu-latest

🚨 1 Alert

Benchmark	Measure Units	View	Benchmark Result (Result Δ%)	Upper Boundary (Limit %)
empty_router/empty_router	Latency milliseconds (ms)	📈 plot 🚷 threshold 🚨 alert (🔔)	13.74 ms (+89.52%) Baseline: 7.25 ms	12.55 ms (109.52%)

Click to view all benchmark results

Benchmark	Latency	Benchmark Result milliseconds (ms) (Result Δ%)	Upper Boundary milliseconds (ms) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold 🚨 view alert (🔔)	13.74 ms (+89.52%) Baseline: 7.25 ms	12.55 ms (109.52%)
json_api/json_api	📈 view plot 🚷 view threshold	1.12 ms (+3.36%) Baseline: 1.08 ms	1.37 ms (81.70%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	1.05 ms (+4.19%) Baseline: 1.01 ms	1.24 ms (84.33%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	1.01 ms (+4.62%) Baseline: 0.97 ms	1.21 ms (84.08%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	16.87 ms (-2.87%) Baseline: 17.37 ms	21.69 ms (77.80%)

🐰 View full continuous benchmarking report in Bencher

codecov · 2026-06-09T20:39:50Z

Codecov Report

❌ Patch coverage is 88.43188% with 45 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot/src/db/migrations.rs	85.22%	21 Missing and 22 partials ⚠️
cot/src/cli.rs	97.70%	2 Missing ⚠️

Flag	Coverage Δ
rust	`90.22% <88.43%> (-0.03%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot/src/db/migrations/sorter.rs	`93.59% <100.00%> (+0.12%)`	⬆️
cot/src/utils/graph.rs	`98.76% <100.00%> (+0.04%)`	⬆️
cot/src/cli.rs	`87.33% <97.70%> (+4.07%)`	⬆️
cot/src/db/migrations.rs	`84.20% <85.22%> (+0.72%)`	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

m4tx

Looks like a solid start, but we need more work on this before it can be merged.

m4tx · 2026-06-23T20:23:39Z

+        // name.
+        // TODO: cli command should take an explicit crate name as arg when workspaces
+        // are supported.
+        let crate_name = bootstrapper.project().cli_metadata().name;


I think we can still potentially want to rollback other libraries' migrations, so I guess we should still support other crates here. For instance, in the admin example we have on the repo, we should still support rolling back cot's m_0001_initial that creates cot__database_user. This is perhaps not terribly useful on its own, but if someone uses libraries that define some more complex migrations, that's more useful. And I believe should be fairly simple to implement, too.

Also, another problem with this in the current form is that we can have multiple migrations called m_0001_initial and it's inclear which one will be chosen.

m4tx · 2026-06-23T20:38:43Z

+    }
+}
+
+struct MigrationRollback;


I believe a few features would make it much more useful:

A subcommand that would list all available migrations

A dry run mode to see which migrations would actually be rolled back

Actual log lines being displayed. cot-cli just eprintlns the info when executing migration make, which I think we could replicate here.

For a subcommand to list all available migrations, I believe we already have that in cot-cli via cot migration list and I dont think we should duplicate that in cot crate. Perhaps this is where #587 can come in handy

m4tx · 2026-06-23T20:44:14Z

+    /// database or if there is an error while generating the migration
+    /// graph or if there is an error while unapplying a migration.
+    pub async fn rollback(&self, database: &Database, file: &str, app_name: &str) -> Result<()> {
+        info!("Rolling back migrations");


Please add a TODO to add transactions here. And I should finally finish the work on #468...

Sadly, the lack of transactions means that we can potentially leave the database in an invalid state if one of the rollback fails. I'm wondering if the transactions would fix this issue, or are there any database engines that we support that don't support transactions on schema-changing operations? (SQLite could be one, but I'm not sure about the status in 2026)

seqre

Apart from @m4tx comments, please add snapshot tests for the new commands

- add an app flag which defaults to the current running app

m4tx · 2026-07-22T13:43:11Z

+
+use anstyle::{AnsiColor, Color, Effects, Style};
+
+#[doc(hidden)] // Not part of Cot's public API; used by the CLI.


I'm wondering if it would make sense to take all the #[doc(hidden)] stuff and just move it into another crate. This shouldn't happen in this PR anyway, but this is just something that maybe we should do at some point.

m4tx · 2026-07-22T13:51:14Z

        const OPERATIONS: &'static [Operation] = &[];
    }

+    struct RollbackApp1Initial;


I think all of the changes in the test module here should go into the tests/ directory. They are clearly integration tests (they involve multiple components: the migration engine, operations themselves, multiple database backends, applying the migrations, then rolling them back). This could even go into a completely separate file, considering how big the change here is and how much it tests. This should make the change much cleaner, and as an added bonus, the snapshot test output won't be too far away from the tests themselves.

m4tx · 2026-07-22T13:52:34Z

 chrono = { workspace = true, features = ["alloc", "serde", "clock"] }
 chrono-tz.workspace = true
-clap.workspace = true
+clap = {workspace = true, features = ["string"] }


nit:

Suggested change

clap = {workspace = true, features = ["string"] }

clap = { workspace = true, features = ["string"] }

feat!: Add support for rolling back migrations

edcd182

github-actions Bot added A-deps Area: Dependencies C-lib Crate: cot (main library crate) labels Jun 2, 2026

ElijahAhianyo and others added 11 commits June 4, 2026 23:00

add unit tests

d069460

chore(pre-commit.ci): auto fixes from pre-commit hooks

965f482

clippy fix

851faff

chore(pre-commit.ci): auto fixes from pre-commit hooks

921ef7b

Merge branch 'master' into elijah/migrations-rollback

4b90c80

fix doc tests

45ed531

update lock

92564de

Merge branch 'master' into elijah/migrations-rollback

6b4176d

remove unwanted test

787f31a

fix linting

d5445b9

shorten test name so mysql runs

d16c593

add some more comments and docs

aa5472c

ElijahAhianyo marked this pull request as ready for review June 9, 2026 20:46

ElijahAhianyo requested review from m4tx and seqre June 9, 2026 20:58

refactor function name

eeb4a62

m4tx requested changes Jun 23, 2026

View reviewed changes

ElijahAhianyo added 3 commits June 25, 2026 22:00

address low-hanging fruits in PR comments

4978351

Merge branch 'master' into elijah/migrations-rollback

65e48e7

remove unused dep

99da125

seqre requested changes Jun 26, 2026

View reviewed changes

ElijahAhianyo added 4 commits June 29, 2026 18:23

- add dry run

b34f193

- add an app flag which defaults to the current running app

Merge branch 'master' into elijah/migrations-rollback

fd959a5

Snapshot test for migration rollback dry run

982e83e

move snapshot testing into tests module

197bd5d

ElijahAhianyo added 2 commits July 17, 2026 21:25

Merge branch 'master' into elijah/migrations-rollback

5e8c26b

add logs to rollback cli and some refactor

ac361ea

github-actions Bot added the C-cli Crate: cot-cli (issues and Pull Requests related to Cot CLI) label Jul 17, 2026

ElijahAhianyo added 3 commits July 21, 2026 13:20

move snapshot tests back

1220134

add snapshot to rollback command

a5e11cd

Merge branch 'master' into elijah/migrations-rollback

2d94f86

ElijahAhianyo requested review from m4tx and seqre July 21, 2026 15:21

m4tx requested changes Jul 22, 2026

View reviewed changes

m4tx changed the title ~~feat!: Add support for rolling back migrations~~ feat!: support for rolling back migrations Jul 22, 2026


		use anstyle::{AnsiColor, Color, Effects, Style};

		#[doc(hidden)] // Not part of Cot's public API; used by the CLI.

	clap = {workspace = true, features = ["string"] }
	clap = { workspace = true, features = ["string"] }

Uh oh!

Uh oh!

Conversation

ElijahAhianyo commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issue or discussion

Description

Type of change

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚨 1 Alert

Uh oh!

codecov Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

m4tx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

seqre left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ElijahAhianyo commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading

codecov Bot commented Jun 9, 2026 •

edited

Loading