Revert "added missing docs"

This reverts commit 3d80f57.

Author: seqre

cot/src/db/migrations.rs

@@ -4,7 +4,9 @@ mod sorter;
 
 use std::fmt;
 use std::fmt::{Debug, Formatter};
+use std::future::Future;
 
+pub use cot_macros::migration_op;
 use sea_query::{ColumnDef, StringLen};
 use thiserror::Error;
 use tracing::{Level, info};
@@ -20,9 +22,13 @@ pub enum MigrationEngineError {
     /// An error occurred while determining the correct order of migrations.
     #[error("error while determining the correct order of migrations")]
     MigrationSortError(#[from] MigrationSorterError),
+    /// A custom error occurred during a migration.
+    #[error("error running migration: {0}")]
+    Custom(String),
 }
 
-/// A migration engine that can run migrations.
+/// A migration engine responsible for managing and applying database
+/// migrations.
 ///
 /// # Examples
 ///
@@ -133,7 +139,7 @@ impl MigrationEngine {
     ///
     /// # Errors
     ///
-    /// Throws an error if any of the migrations fail to apply, or if there is
+    /// Returns an error if any of the migrations fail to apply, or if there is
     /// an error while interacting with the database, or if there is an
     /// error while marking a migration as applied.
     ///
@@ -424,11 +430,37 @@ impl Operation {
         RemoveModelBuilder::new()
     }
 
+    // TODO: docs
+    pub const fn alter_field() -> AlterFieldBuilder {
+        AlterFieldBuilder::new()
+    }
+
+    /// Returns a builder for a custom operation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use cot::db::Result;
+    /// use cot::db::migrations::{MigrationContext, Operation, migration_op};
+    ///
+    /// #[migration_op]
+    /// async fn forwards(ctx: MigrationContext<'_>) -> Result<()> {
+    ///     // do something
+    ///     Ok(())
+    /// }
+    ///
+    /// const OPERATION: Operation = Operation::custom(forwards).build();
+    /// ```
+    #[must_use]
+    pub const fn custom(forwards: CustomOperationFn) -> CustomBuilder {
+        CustomBuilder::new(forwards)
+    }
+
     /// Runs the operation forwards.
     ///
     /// # Errors
     ///
-    /// Throws an error if the operation fails to apply.
+    /// Returns an error if the operation fails to apply.
     ///
     /// # Examples
     ///
@@ -512,6 +544,13 @@ impl Operation {
                 let query = sea_query::Table::drop().table(*table_name).to_owned();
                 database.execute_schema(query).await?;
             }
+            OperationInner::Custom {
+                forwards,
+                backwards: _,
+            } => {
+                let context = MigrationContext::new(database);
+                forwards(context).await?;
+            }
         }
         Ok(())
     }
@@ -521,7 +560,7 @@ impl Operation {
     ///
     /// # Errors
     ///
-    /// Throws an error if the operation fails to apply.
+    /// Returns an error if the operation fails to apply.
     ///
     /// # Examples
     ///
@@ -601,11 +640,50 @@ impl Operation {
                 }
                 database.execute_schema(query).await?;
             }
+            OperationInner::Custom {
+                forwards: _,
+                backwards,
+            } => {
+                if let Some(backwards) = backwards {
+                    let context = MigrationContext::new(database);
+                    backwards(context).await?;
+                } else {
+                    return Err(crate::db::DatabaseError::MigrationError(
+                        MigrationEngineError::Custom("Backwards migration not implemented".into()),
+                    ));
+                }
+            }
         }
         Ok(())
     }
 }
 
+/// A context for a custom migration operation.
+///
+/// This structure provides access to the database and other information that
+/// might be needed during a migration.
+#[derive(Debug)]
+#[non_exhaustive]
+pub struct MigrationContext<'a> {
+    /// The database connection to run the migration against.
+    pub db: &'a Database,
+}
+
+impl<'a> MigrationContext<'a> {
+    fn new(db: &'a Database) -> Self {
+        Self { db }
+    }
+}
+
+/// A type alias for a custom migration operation function.
+///
+/// Typically, you should use the [`migration_op`] attribute macro to define
+/// functions of this type.
+pub type CustomOperationFn =
+    for<'a> fn(
+        MigrationContext<'a>,
+    ) -> std::pin::Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>;
+
 #[derive(Debug, Copy, Clone)]
 enum OperationInner {
     /// Create a new model with the given fields.
@@ -634,6 +712,10 @@ enum OperationInner {
         old_field: Field,
         new_field: Field,
     },
+    Custom {
+        forwards: CustomOperationFn,
+        backwards: Option<CustomOperationFn>,
+    },
 }
 
 /// A field in a model.
@@ -687,6 +769,12 @@ impl Field {
 
     /// Marks the field as a foreign key to the given model and field.
     ///
+    /// # Panics
+    ///
+    /// This function will panic if `on_delete` or `on_update` is set to
+    /// [`SetNone`](ForeignKeyOnDeletePolicy::SetNone) and the field is not
+    /// nullable.
+    ///
     /// # Cot CLI Usage
     ///
     /// Typically, you shouldn't need to use this directly. Instead, in most
@@ -1558,13 +1646,61 @@ impl RemoveModelBuilder {
     }
 }
 
-/// Returns a builder for an operation that alters a field in a model.
-pub const fn alter_field() -> AlterFieldBuilder {
-    AlterFieldBuilder::new()
+/// A builder for a custom operation.
+///
+/// # Examples
+///
+/// ```
+/// use cot::db::Result;
+/// use cot::db::migrations::{MigrationContext, Operation, migration_op};
+///
+/// #[migration_op]
+/// async fn forwards(ctx: MigrationContext<'_>) -> Result<()> {
+///     // do something
+///     Ok(())
+/// }
+///
+/// #[migration_op]
+/// async fn backwards(ctx: MigrationContext<'_>) -> Result<()> {
+///     // undo something
+///     Ok(())
+/// }
+///
+/// const OPERATION: Operation = Operation::custom(forwards).backwards(backwards).build();
+/// ```
+#[derive(Debug, Copy, Clone)]
+pub struct CustomBuilder {
+    forwards: CustomOperationFn,
+    backwards: Option<CustomOperationFn>,
+}
+
+impl CustomBuilder {
+    #[must_use]
+    const fn new(forwards: CustomOperationFn) -> Self {
+        Self {
+            forwards,
+            backwards: None,
+        }
+    }
+
+    /// Sets the backwards operation.
+    #[must_use]
+    pub const fn backwards(mut self, backwards: CustomOperationFn) -> Self {
+        self.backwards = Some(backwards);
+        self
+    }
+
+    /// Builds the operation.
+    #[must_use]
+    pub const fn build(self) -> Operation {
+        Operation::new(OperationInner::Custom {
+            forwards: self.forwards,
+            backwards: self.backwards,
+        })
+    }
 }
 
-/// A builder for altering a field in a model.
-#[must_use]
+// TODO: docs
 #[derive(Debug, Copy, Clone)]
 pub struct AlterFieldBuilder {
     table_name: Option<Identifier>,
@@ -1600,7 +1736,6 @@ impl AlterFieldBuilder {
     }
 
     /// Builds the operation.
-    #[must_use]
     pub const fn build(self) -> Operation {
         Operation::new(OperationInner::AlterField {
             table_name: unwrap_builder_option!(self, table_name),
@@ -2088,6 +2223,86 @@ mod tests {
         }
     }
 
+    #[cot::test]
+    #[cfg_attr(
+        miri,
+        ignore = "unsupported operation: can't call foreign function `sqlite3_open_v2`"
+    )]
+    async fn operation_custom() {
+        // test only on SQLite because we are using raw SQL
+        let test_db = TestDatabase::new_sqlite().await.unwrap();
+
+        #[migration_op]
+        async fn forwards(ctx: MigrationContext<'_>) -> Result<()> {
+            ctx.db
+                .raw("CREATE TABLE custom_test (id INTEGER PRIMARY KEY)")
+                .await?;
+            Ok(())
+        }
+
+        let operation = Operation::custom(forwards).build();
+        operation.forwards(&test_db.database()).await.unwrap();
+
+        let result = test_db.database().raw("SELECT * FROM custom_test").await;
+        assert!(result.is_ok());
+    }
+
+    #[cot::test]
+    #[cfg_attr(
+        miri,
+        ignore = "unsupported operation: can't call foreign function `sqlite3_open_v2`"
+    )]
+    async fn operation_custom_backwards() {
+        // test only on SQLite because we are using raw SQL
+        let test_db = TestDatabase::new_sqlite().await.unwrap();
+
+        #[migration_op]
+        async fn forwards(_ctx: MigrationContext<'_>) -> Result<()> {
+            panic!("this should not be called");
+        }
+
+        #[migration_op]
+        async fn backwards(ctx: MigrationContext<'_>) -> Result<()> {
+            ctx.db.raw("DROP TABLE custom_test_back").await?;
+            Ok(())
+        }
+
+        test_db
+            .database()
+            .raw("CREATE TABLE custom_test_back (id INTEGER PRIMARY KEY)")
+            .await
+            .unwrap();
+
+        let operation = Operation::custom(forwards).backwards(backwards).build();
+        operation.backwards(&test_db.database()).await.unwrap();
+
+        let result = test_db
+            .database()
+            .raw("SELECT * FROM custom_test_back")
+            .await;
+        assert!(result.is_err());
+    }
+
+    #[cot::test]
+    #[cfg_attr(
+        miri,
+        ignore = "unsupported operation: can't call foreign function `sqlite3_open_v2`"
+    )]
+    async fn operation_custom_backwards_not_implemented() {
+        // test only on SQLite because we are using raw SQL
+        let test_db = TestDatabase::new_sqlite().await.unwrap();
+
+        #[migration_op]
+        async fn forwards(_ctx: MigrationContext<'_>) -> Result<()> {
+            Ok(())
+        }
+
+        let operation = Operation::custom(forwards).build();
+        let result = operation.backwards(&test_db.database()).await;
+
+        assert!(result.is_err());
+    }
+
     #[test]
     fn field_new() {
         let field = Field::new(Identifier::new("id"), ColumnType::Integer)