Add more migration sources

This PR adds more migration sources to diesel_migrations with the goal
to make it easier to write different kinds of migrations in multi-crate
deployments.

It adds a CombinedMigrations source that is essentially just a list of
sources. The resulting list of migrations is just all migrations from
all sources. That is useful for multi-crate projects as then each
sub-project can have their own set of migrations (by using files or
embedded migrations etc) and then combine them into a final list using
this migration source.

As a second variant a RustMigrationSource is added. The goal there is to
make it much easier to register rust based migrations by having some
sort of typed interface for this. This migration source needs to know
the connection type, not only the backend. This information is then used
to internally receive the right connection type from the migration
connection for the user. The user has the ability to provide different
kinds of rust structs/functions all "migration. This includes closures,
functions, a migration builder (that in turn accepts clousures but
allows more fine grained configuration) or even custom types (via the
provided trait).

Author: weiznich

diesel/src/connection/instrumentation.rs

@@ -1,7 +1,7 @@
 use downcast_rs::Downcast;
 use std::fmt::{Debug, Display};
 use std::num::NonZeroU32;
-use std::ops::{Deref, DerefMut};
+use std::ops::DerefMut;
 
 static GLOBAL_INSTRUMENTATION: std::sync::RwLock<fn() -> Option<Box<dyn Instrumentation>>> =
     std::sync::RwLock::new(|| None);
@@ -321,6 +321,12 @@ where
 #[diesel_derives::__diesel_public_if(
     feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
 )]
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 /// An optional dyn instrumentation.
 ///
 /// For ease of use, this type implements [`Deref`] and [`DerefMut`] to `&dyn Instrumentation`,
@@ -335,14 +341,26 @@ pub(crate) struct DynInstrumentation {
     inner: Option<Box<dyn Instrumentation>>,
 }
 
-impl Deref for DynInstrumentation {
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
+impl core::ops::Deref for DynInstrumentation {
     type Target = dyn Instrumentation;
 
     fn deref(&self) -> &Self::Target {
         self.inner.as_deref().unwrap_or(&self.no_instrumentation)
     }
 }
 
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 impl DerefMut for DynInstrumentation {
     fn deref_mut(&mut self) -> &mut Self::Target {
         self.inner
@@ -351,6 +369,12 @@ impl DerefMut for DynInstrumentation {
     }
 }
 
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 impl DynInstrumentation {
     /// Create a instance of the default instrumentation provider
     #[diesel_derives::__diesel_public_if(
@@ -406,6 +430,12 @@ impl DynInstrumentation {
     }
 }
 
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 impl<I: Instrumentation> From<I> for DynInstrumentation {
     fn from(instrumentation: I) -> Self {
         Self {
@@ -414,14 +444,31 @@ impl<I: Instrumentation> From<I> for DynInstrumentation {
         }
     }
 }
-
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 struct NoInstrumentation;
 
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 impl Instrumentation for NoInstrumentation {
     fn on_connection_event(&mut self, _: InstrumentationEvent<'_>) {}
 }
 
 /// Unwrap unnecessary boxing levels
+#[cfg(any(
+    feature = "postgres",
+    feature = "sqlite",
+    feature = "mysql",
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+))]
 fn unpack_instrumentation(
     mut instrumentation: Box<dyn Instrumentation>,
 ) -> Box<dyn Instrumentation> {

diesel/src/query_source/mod.rs

@@ -142,13 +142,15 @@ pub trait AppearsInFromClause<QS> {
 ///
 /// (Notably, a bunch of [`AppearsInFromClause`] for the tables and their aliases.)
 ///
-/// This trait is implemented by the [`allow_tables_to_appear_in_same_query!`] macro.
+/// This trait is implemented by the
+/// [`allow_tables_to_appear_in_same_query!`](crate::allow_tables_to_appear_in_same_query)
+/// macro.
 ///
 /// Troubleshooting
 /// ---------------
 /// If you encounter an error mentioning this trait, it could mean that either:
 /// - You are attempting to use tables that don't belong to the same database together
-///   (no call to [`allow_tables_to_appear_in_same_query!`] was made)
+///   (no call to [`allow_tables_to_appear_in_same_query!`](crate::allow_tables_to_appear_in_same_query) was made)
 /// - You are attempting to use two aliases to the same table in the same query, but they
 ///   were declared through different calls to [`alias!`](crate::alias)
 #[diagnostic::on_unimplemented(

diesel_migrations/src/combined_migrations.rs

@@ -0,0 +1,77 @@
+use std::sync::Arc;
+
+use diesel::backend::Backend;
+use diesel::migration::{Migration, MigrationSource};
+
+/// A diesel migration source that combines several other sources
+///
+/// This source will act like all migrations came from a single source.
+/// It orders all the migrations by version
+///
+/// # Example
+/// ```
+/// # include!("../../diesel/src/doctest_setup.rs");
+/// # fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+/// use diesel::prelude::*;
+/// use diesel_migrations::EmbeddedMigrations;
+/// use diesel_migrations::CombinedMigrationSource;
+/// use crate::diesel_migrations::MigrationHarness;
+/// use migrations_macros::embed_migrations;
+///
+/// pub const PG_MIGRATIONS: EmbeddedMigrations = embed_migrations!("../migrations/postgres");
+/// pub const SQLITE_MIGRATIONS: EmbeddedMigrations = embed_migrations!("../migrations/sqlite");
+///
+/// # #[cfg(feature = "postgres")]
+/// # let connection_url = database_url_from_env("PG_DATABASE_URL");
+/// # #[cfg(feature = "sqlite")]
+/// # let connection_url = database_url_from_env("SQLITE_DATABASE_URL");
+/// # #[cfg(feature = "mysql")]
+/// # let connection_url = database_url_from_env("MYSQL_DATABASE_URL");
+/// # #[cfg(feature = "postgres")]
+/// # type SqliteConnection = PgConnection;
+/// # #[cfg(feature = "mysql")]
+/// # type SqliteConnection = MysqlConnection;
+/// #
+/// // Create a new empty combined source
+/// let mut combined_sources = CombinedMigrationSource::default();
+///
+/// // It's not particular meaningful to combine PostgreSQL and SQLite like this,
+/// // but that reasonable demonstrates the API
+/// combined_sources.add_source(PG_MIGRATIONS);
+/// combined_sources.add_source(SQLITE_MIGRATIONS);
+///
+/// // run the migrations
+/// let mut connection = SqliteConnection::establish(&connection_url)?;
+/// let res = connection.run_pending_migrations(combined_sources);
+/// # assert!(res.is_err(), "This is supposed to fail as you cannot run postgres migrations using sqlite");
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Default, Clone)]
+pub struct CombinedMigrationSource<DB> {
+    migrations: Vec<Arc<dyn MigrationSource<DB> + Send + Sync>>,
+}
+
+impl<DB> CombinedMigrationSource<DB>
+where
+    DB: Backend,
+{
+    /// Register another source with the given migration source
+    pub fn add_source(&mut self, source: impl MigrationSource<DB> + Send + Sync + 'static) {
+        self.migrations.push(Arc::new(source))
+    }
+}
+
+impl<DB> MigrationSource<DB> for CombinedMigrationSource<DB>
+where
+    DB: Backend,
+{
+    fn migrations(&self) -> diesel::migration::Result<Vec<Box<dyn Migration<DB>>>> {
+        let mut migrations = Vec::new();
+        for source in &self.migrations {
+            migrations.extend(source.migrations()?);
+        }
+        migrations.sort_by(|m1, m2| m1.name().version().cmp(&m2.name().version()));
+        Ok(migrations)
+    }
+}

diesel_migrations/src/lib.rs

@@ -32,15 +32,23 @@
 //! Migrations can either be run with the CLI or embedded into the compiled application
 //! and executed with code, for example right after establishing a database connection.
 //! For more information, consult the [`embed_migrations!`] macro.
+//!
+//! You can also define migrations in your rust code by using the [`RustMigrationSource`].
+//! The [`CombinedMigrationSource`] allows you to combine migrations from different sources
+//! to execute them together
 
+mod combined_migrations;
 mod embedded_migrations;
 mod errors;
 mod file_based_migrations;
 mod migration_harness;
+mod rust_migrations;
 
-pub use crate::embedded_migrations::EmbeddedMigrations;
-pub use crate::file_based_migrations::FileBasedMigrations;
-pub use crate::migration_harness::{HarnessWithOutput, MigrationHarness};
+pub use self::embedded_migrations::EmbeddedMigrations;
+pub use self::file_based_migrations::FileBasedMigrations;
+pub use self::migration_harness::{HarnessWithOutput, MigrationHarness};
+pub use self::rust_migrations::{RustMigration, RustMigrationSource, TypedMigration};
+pub use combined_migrations::CombinedMigrationSource;
 pub use migrations_macros::embed_migrations;
 
 #[doc(hidden)]

diesel_migrations/src/migration_harness.rs

@@ -118,7 +118,6 @@ pub trait MigrationHarness<DB: Backend> {
             .into_iter()
             .map(|m| (m.name().version().as_owned(), m))
             .collect::<HashMap<_, _>>();
-
         for applied_version in applied_versions {
             migrations.remove(&applied_version);
         }