Automatically run migrations on service startup

crates/cli/src/commands/server.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use std::{sync::Arc, time::Duration};
+use std::{collections::BTreeSet, sync::Arc, time::Duration};
 
 use anyhow::Context;
 use clap::Parser;
@@ -29,6 +29,7 @@
     distributions::{Alphanumeric, DistString},
     thread_rng,
 };
+use sqlx::migrate::Migrate;
 use tokio::signal::unix::SignalKind;
 use tracing::{info, info_span, warn, Instrument};
 
@@ -42,8 +43,13 @@
 
 #[derive(Parser, Debug, Default)]
 pub(super) struct Options {
-    /// Automatically apply pending migrations
+    /// Do not apply pending migrations on start
     #[arg(long)]
+    no_migrate: bool,
+
+    /// DEPRECATED: default is to apply pending migrations, use `--no-migrate`
+    /// to disable
+    #[arg(long, hide = true)]
     migrate: bool,
 
     /// Do not start the task worker
@@ -57,11 +63,25 @@
         let span = info_span!("cli.run.init").entered();
         let config: AppConfig = root.load_config()?;
 
+        if self.migrate {
+            warn!("The `--migrate` flag is deprecated and will be removed in a future release. Please use `--no-migrate` to disable automatic migrations on startup.");
+        }
+
         // Connect to the database
         info!("Connecting to the database");
         let pool = database_pool_from_config(&config.database).await?;
 
-        if self.migrate {
+        if self.no_migrate {
+            // Check that we applied all the migrations
+            let mut conn = pool.acquire().await?;
+            let applied = conn.list_applied_migrations().await?;
+            let applied: BTreeSet<_> = applied.into_iter().map(|m| m.version).collect();
+            let has_missing_migrations = MIGRATOR.iter().any(|m| !applied.contains(&m.version));
+            if has_missing_migrations {
+                // Refuse to start if there are pending migrations
+                return Err(anyhow::anyhow!("The server is running with `--no-migrate` but there are pending. Please run them first with `mas-cli database migrate`, or omit the `--no-migrate` flag to apply them automatically on startup."));
+            }
+        } else {
             info!("Running pending migrations");
             MIGRATOR
                 .run(&pool)

docs/setup/database.md

@@ -51,24 +51,18 @@ database:
 ## Database migrations
 
 The service manages the database schema with embedded migrations.
-Those migrations need to be run before the service can be started, and every time the service is upgraded.
+Those migrations are run automatically when the service starts, but it is also possible to run them manually.
 This is done using the [`database migrate`](../usage/cli/database.md#database-migrate) command:
 
 ```sh
 mas-cli database migrate
 ```
 
-It is also possible to run any pending migrations on service start, by setting the `--migrate` option to the [`server`](../usage/cli/server.md#server) command:
-
-```sh
-mas-cli server --migrate
-```
-
 ## Next steps
 
 Once the database is up, the remaining steps are to:
 
  - [Set up the connection to the homeserver (recommended)](./homeserver.md)
  - [Setup email sending (optional)](../usage/configuration.md#email)
  - [Configure a reverse proxy (optional)](./reverse-proxy.md)
- - [Run the service](./running.md)
+ - [Run the service](./running.md)

docs/usage/cli/server.md

@@ -8,5 +8,3 @@ INFO mas_cli::server: Starting task scheduler
 INFO mas_core::templates: Loading builtin templates
 INFO mas_cli::server: Listening on http://0.0.0.0:8080
 ```
-
-A `--migrate` flag can be set to automatically run pending database migrations on startup.