Improve SyncConnectionWrapper documentation and tests

Author: momobel

Cargo.toml

@@ -49,7 +49,7 @@ path = "tests/lib.rs"
 harness = true
 
 [package.metadata.docs.rs]
-features = ["postgres", "mysql", "deadpool", "bb8", "mobc", "async-connection-wrapper", "r2d2"]
+features = ["postgres", "mysql", "sqlite", "deadpool", "bb8", "mobc", "async-connection-wrapper", "sync-connection-wrapper", "r2d2"]
 no-default-features = true
 rustc-args = ["--cfg", "doc_cfg"]
 rustdoc-args = ["--cfg", "doc_cfg"]

examples/sync-wrapper/src/main.rs

@@ -28,6 +28,7 @@ type InnerConnection = SqliteConnection;
 type InnerDB = Sqlite;
 
 async fn establish(db_url: &str) -> ConnectionResult<SyncConnectionWrapper<InnerConnection>> {
+    // It is necessary to specify the specific inner connection type because of inference issues
     SyncConnectionWrapper::<SqliteConnection>::establish(db_url).await
 }
 

src/doctest_setup.rs

@@ -160,6 +160,81 @@ cfg_if::cfg_if! {
             create_tables(&mut connection).await;
 
 
+            connection
+        }
+    }  else if #[cfg(feature = "sqlite")] {
+        use diesel_async::sync_connection_wrapper::SyncConnectionWrapper;
+        use diesel::sqlite::SqliteConnection;
+        #[allow(dead_code)]
+        type DB = diesel::sqlite::Sqlite;
+        #[allow(dead_code)]
+        type DbConnection = SyncConnectionWrapper<SqliteConnection>;
+
+        fn database_url() -> String {
+            database_url_from_env("SQLITE_DATABASE_URL")
+        }
+
+        async fn connection_no_data() -> SyncConnectionWrapper<SqliteConnection> {
+            use diesel_async::AsyncConnection;
+            let connection_url = database_url();
+            SyncConnectionWrapper::<SqliteConnection>::establish(&connection_url).await.unwrap()
+        }
+
+        async fn create_tables(connection: &mut SyncConnectionWrapper<SqliteConnection>) {
+            use diesel_async::RunQueryDsl;
+            use diesel_async::AsyncConnection;
+            diesel::sql_query("CREATE TEMPORARY TABLE IF NOT EXISTS users (
+                id INTEGER PRIMARY KEY,
+                name TEXT NOT NULL
+            )").execute(connection).await.unwrap();
+
+
+            diesel::sql_query("CREATE TEMPORARY TABLE IF NOT EXISTS animals (
+                id INTEGER PRIMARY KEY,
+                species TEXT NOT NULL,
+                legs INTEGER NOT NULL,
+                name TEXT
+            )").execute(connection).await.unwrap();
+
+            diesel::sql_query("CREATE TEMPORARY TABLE IF NOT EXISTS posts (
+                id INTEGER PRIMARY KEY,
+                user_id INTEGER NOT NULL,
+                title TEXT NOT NULL
+            )").execute(connection).await.unwrap();
+
+            diesel::sql_query("CREATE TEMPORARY TABLE IF NOT EXISTS comments (
+                id INTEGER PRIMARY KEY,
+                post_id INTEGER NOT NULL,
+                body TEXT NOT NULL
+            )").execute(connection).await.unwrap();
+            diesel::sql_query("CREATE TEMPORARY TABLE IF NOT EXISTS brands (
+                id INTEGER PRIMARY KEY,
+                color VARCHAR(255) NOT NULL DEFAULT 'Green',
+                accent VARCHAR(255) DEFAULT 'Blue'
+            )").execute(connection).await.unwrap();
+
+            connection.begin_test_transaction().await.unwrap();
+            diesel::sql_query("INSERT INTO users (name) VALUES ('Sean'), ('Tess')").execute(connection).await.unwrap();
+            diesel::sql_query("INSERT INTO posts (user_id, title) VALUES
+                (1, 'My first post'),
+                (1, 'About Rust'),
+                (2, 'My first post too')").execute(connection).await.unwrap();
+            diesel::sql_query("INSERT INTO comments (post_id, body) VALUES
+                (1, 'Great post'),
+                (2, 'Yay! I am learning Rust'),
+                (3, 'I enjoyed your post')").execute(connection).await.unwrap();
+            diesel::sql_query("INSERT INTO animals (species, legs, name) VALUES
+                               ('dog', 4, 'Jack'),
+                               ('spider', 8, null)").execute(connection).await.unwrap();
+
+        }
+
+        #[allow(dead_code)]
+        async fn establish_connection() -> SyncConnectionWrapper<SqliteConnection> {
+            let mut connection = connection_no_data().await;
+            create_tables(&mut connection).await;
+
+
             connection
         }
     } else {

src/lib.rs

@@ -14,11 +14,12 @@
 //!
 //! These traits closely mirror their diesel counter parts while providing async functionality.
 //!
-//! In addition to these core traits 2 fully async connection implementations are provided
+//! In addition to these core traits 3 fully async connection implementations are provided
 //! by diesel-async:
 //!
 //! * [`AsyncMysqlConnection`] (enabled by the `mysql` feature)
 //! * [`AsyncPgConnection`] (enabled by the `postgres` feature)
+//! * [`SyncConnectionWrapper`] (enabled by the `sync-connection-wrapper` feature)
 //!
 //! Ordinary usage of `diesel-async` assumes that you just replace the corresponding sync trait
 //! method calls and connections with their async counterparts.

src/run_query_dsl/mod.rs

@@ -208,10 +208,12 @@ pub trait RunQueryDsl<Conn>: Sized {
     ///     .await?;
     /// assert_eq!(1, inserted_rows);
     ///
+    /// # #[cfg(not(feature = "sqlite"))]
     /// let inserted_rows = insert_into(users)
     ///     .values(&vec![name.eq("Jim"), name.eq("James")])
     ///     .execute(connection)
     ///     .await?;
+    /// # #[cfg(not(feature = "sqlite"))]
     /// assert_eq!(2, inserted_rows);
     /// #     Ok(())
     /// # }
@@ -604,10 +606,12 @@ pub trait RunQueryDsl<Conn>: Sized {
     /// # async fn run_test() -> QueryResult<()> {
     /// #     use schema::users::dsl::*;
     /// #     let connection = &mut establish_connection().await;
-    /// diesel::insert_into(users)
-    ///     .values(&vec![name.eq("Sean"), name.eq("Pascal")])
-    ///     .execute(connection)
-    ///     .await?;
+    /// for n in &["Sean", "Pascal"] {
+    ///     diesel::insert_into(users)
+    ///         .values(name.eq(n))
+    ///         .execute(connection)
+    ///         .await?;
+    /// }
     ///
     /// let first_name = users.order(id)
     ///     .select(name)
@@ -678,13 +682,15 @@ impl<T, Conn> RunQueryDsl<Conn> for T {}
 /// #     use self::animals::dsl::*;
 /// #     let connection = &mut establish_connection().await;
 /// let form = AnimalForm { id: 2, name: "Super scary" };
+/// # #[cfg(not(feature = "sqlite"))]
 /// let changed_animal = form.save_changes(connection).await?;
 /// let expected_animal = Animal {
 ///     id: 2,
 ///     species: String::from("spider"),
 ///     legs: 8,
 ///     name: Some(String::from("Super scary")),
 /// };
+/// # #[cfg(not(feature = "sqlite"))]
 /// assert_eq!(expected_animal, changed_animal);
 /// #     Ok(())
 /// # }

src/sync_connection_wrapper.rs

@@ -37,6 +37,38 @@ fn from_tokio_join_error(join_error: JoinError) -> diesel::result::Error {
 /// * it's a [`diesel::connection::LoadConnection`]
 /// * its [`diesel::connection::Connection::Backend`] has a [`diesel::query_builder::BindCollector`] implementing [`diesel::query_builder::MoveableBindCollector`]
 /// * its [`diesel::connection::LoadConnection::Row`] implements [`diesel::row::IntoOwnedRow`]
+///
+/// Internally this wrapper type will use `spawn_blocking` on tokio
+/// to execute the request on the inner connection. This implies a
+/// dependency on tokio and that the runtime is running.
+///
+/// Note that only SQLite is supported at the moment.
+///
+/// # Examples
+///
+/// ```rust
+/// # include!("doctest_setup.rs");
+/// use diesel_async::RunQueryDsl;
+/// use schema::users;
+///
+/// async fn some_async_fn() {
+/// # let database_url = database_url();
+///          use diesel_async::AsyncConnection;
+///          use diesel::sqlite::SqliteConnection;
+///          let mut conn =
+///          SyncConnectionWrapper::<SqliteConnection>::establish(&database_url).await.unwrap();
+/// # create_tables(&mut conn).await;
+///
+///          let all_users = users::table.load::<(i32, String)>(&mut conn).await.unwrap();
+/// #         assert_eq!(all_users.len(), 2);
+/// }
+///
+/// # #[cfg(feature = "sqlite")]
+/// # #[tokio::main]
+/// # async fn main() {
+/// #    some_async_fn().await;
+/// # }
+/// ```
 pub struct SyncConnectionWrapper<C> {
     inner: Arc<Mutex<C>>,
 }