Replace Connection#execute_returning_count with command.execute

Using `update` and `delete` was previously quite annoying to write. This
makes the API feel much more fluid, and reads better if you're not
actually using the count. Since `insert` is coming in this release as
well, this will make things more useable.

Author: sgrif

CHANGELOG.md

@@ -6,6 +6,13 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
 
 ## Unreleased
 
+### Added
+
+* Added an `execute` method to `QueryFragment`, which is intended to replace
+  `Connection#execute_returning_count`. The old method still exists for use
+  under the hood, but has been hidden from docs and is not considered public
+  API.
+
 ### Changed
 
 * Added a hidden `__Nonexhaustive` variant to `result::Error`. This is not

README.md

@@ -164,8 +164,7 @@ fn change_users_name(connection: &Connection, target: i32, new_name: &str) -> Qu
 
 As with [`insert`][insert], we can return any type which implements
 [`Queriable`][queriable] for the right types. If you do not want to use the
-returned record(s), you should call
-[`execute_returning_count`][execute_returning_count] instead of
+returned record(s), you should call [`execute`][execute] instead of
 [`query_one`][query_one] or [`query_all`][query_all].
 
 You can also use a struct to represent the changes, if it implements
@@ -217,8 +216,7 @@ fn delete_user(connection: &Connection, user: User) -> QueryResult<()> {
     use diesel::query_builder::delete;
     use users::dsl::*;
 
-    let command = delete(users.filter(id.eq(user.id)));
-    let deleted_rows = try!(connection.execute_returning_count(&command));
+    delete(users.filter(id.eq(user.id))).execute(&connection).unwrap();
     debug_assert!(deleted_rows == 1);
     Ok(())
 }
@@ -237,7 +235,7 @@ you can go about getting the data structures set up.
 [insertable]: http://sgrif.github.io/diesel/diesel/trait.Insertable.html
 [insert]: http://sgrif.github.io/diesel/diesel/struct.Connection.html#method.insert
 [insert_returning_count]: http://sgrif.github.io/diesel/diesel/struct.Connection.html#method.insert_returning_count
-[execute_returning_count]: http://sgrif.github.io/diesel/diesel/struct.Connection.html#method.execute_returning_count
+[execute]: http://sgrif.github.io/diesel/diesel/trait.ExecuteDsl.html#method.execute
 [query_one]: http://sgrif.github.io/diesel/diesel/struct.Connection.html#method.query_one
 [query_all]: http://sgrif.github.io/diesel/diesel/struct.Connection.html#method.query_all
 [update]: http://sgrif.github.io/diesel/diesel/query_builder/fn.update.html

diesel/src/connection/mod.rs

@@ -255,10 +255,7 @@ impl Connection {
         self.exec_sql_params(&sql, &params, &Some(param_types)).map(|r| r.rows_affected())
     }
 
-    /// Executes the given command, returning the number of rows affected. Used
-    /// in conjunction with
-    /// [`update`](../query_builder/fn.update.html) and
-    /// [`delete`](../query_builder/fn.delete.html)
+    #[doc(hidden)]
     pub fn execute_returning_count<T>(&self, source: &T) -> QueryResult<usize> where
         T: QueryFragment,
     {

diesel/src/query_builder/functions.rs

@@ -62,8 +62,7 @@ pub fn update<T: UpdateTarget>(source: T) -> IncompleteUpdateStatement<T> {
 /// #     let connection = establish_connection();
 /// #     let get_count = || users.count().first::<i64>(&connection).unwrap();
 /// let old_count = get_count();
-/// let command = delete(users.filter(id.eq(1)));
-/// connection.execute_returning_count(&command).unwrap();
+/// delete(users.filter(id.eq(1))).execute(&connection).unwrap();
 /// assert_eq!(old_count - 1, get_count());
 /// # }
 /// ```
@@ -86,7 +85,7 @@ pub fn update<T: UpdateTarget>(source: T) -> IncompleteUpdateStatement<T> {
 /// #     use diesel::query_builder::delete;
 /// #     let connection = establish_connection();
 /// #     let get_count = || users.count().first::<i64>(&connection).unwrap();
-/// connection.execute_returning_count(&delete(users)).unwrap();
+/// delete(users).execute(&connection).unwrap();
 /// assert_eq!(0, get_count());
 /// # }
 /// ```

diesel/src/query_dsl/load_dsl.rs

@@ -1,5 +1,5 @@
 use connection::{Connection, Cursor};
-use query_builder::{Query, AsQuery};
+use query_builder::{Query, QueryFragment, AsQuery};
 use query_source::Queriable;
 use result::QueryResult;
 use super::LimitDsl;
@@ -26,3 +26,16 @@ pub trait LoadDsl: AsQuery + LimitDsl + Sized {
 
 impl<T: AsQuery + LimitDsl> LoadDsl for T {
 }
+
+pub trait ExecuteDsl: QueryFragment + Sized {
+    /// Executes the given command, returning the number of rows affected. Used
+    /// in conjunction with
+    /// [`update`](../query_builder/fn.update.html) and
+    /// [`delete`](../query_builder/fn.delete.html)
+    fn execute(&self, conn: &Connection) -> QueryResult<usize> {
+        conn.execute_returning_count(self)
+    }
+}
+
+impl<T: QueryFragment> ExecuteDsl for T {
+}

diesel/src/query_dsl/mod.rs

@@ -14,7 +14,7 @@ pub use self::belonging_to_dsl::BelongingToDsl;
 pub use self::count_dsl::CountDsl;
 pub use self::filter_dsl::FilterDsl;
 pub use self::limit_dsl::LimitDsl;
-pub use self::load_dsl::LoadDsl;
+pub use self::load_dsl::{LoadDsl, ExecuteDsl};
 pub use self::offset_dsl::OffsetDsl;
 pub use self::order_dsl::OrderDsl;
 pub use self::select_dsl::{SelectDsl, SelectSqlDsl};

diesel_tests/tests/insert.rs

@@ -130,10 +130,9 @@ fn delete() {
     use diesel::query_builder::delete;
     let connection = connection_with_sean_and_tess_in_users_table();
 
-    let command = delete(users.filter(name.eq("Sean")));
-    let deleted_rows = connection.execute_returning_count(&command).unwrap();
+    let deleted_rows = delete(users.filter(name.eq("Sean"))).execute(&connection);
 
-    assert_eq!(1, deleted_rows);
+    assert_eq!(Ok(1), deleted_rows);
 
     let num_users = users.count().first(&connection);
 

diesel_tests/tests/update.rs

@@ -12,8 +12,7 @@ fn test_updating_single_column() {
     let data: Vec<String> = users.select(name).load(&connection).unwrap().collect();
     assert_eq!(expected_data, data);
 
-    let command = update(users).set(name.eq("Jim"));
-    connection.execute_returning_count(&command).unwrap();
+    update(users).set(name.eq("Jim")).execute(&connection).unwrap();
 
     let expected_data = vec!["Jim".to_string(); 2];
     let data: Vec<String> = users.select(name).load(&connection).unwrap().collect();
@@ -26,8 +25,8 @@ fn test_updating_single_column_of_single_row() {
 
     let connection = connection_with_sean_and_tess_in_users_table();
 
-    let command = update(users.filter(id.eq(1))).set(name.eq("Jim"));
-    connection.execute_returning_count(&command).unwrap();
+    update(users.filter(id.eq(1))).set(name.eq("Jim"))
+        .execute(&connection).unwrap();
 
     let expected_data = vec!["Tess".to_string(), "Jim".to_string()];
     let data: Vec<String> = users.select(name).load(&connection).unwrap().collect();
@@ -40,17 +39,17 @@ fn test_updating_nullable_column() {
 
     let connection = connection_with_sean_and_tess_in_users_table();
 
-    let command = update(users.filter(id.eq(1))).set(hair_color.eq(Some("black")));
-    connection.execute_returning_count(&command).unwrap();
+    update(users.filter(id.eq(1))).set(hair_color.eq(Some("black")))
+        .execute(&connection).unwrap();
 
     let data: Option<String> = users.select(hair_color)
         .filter(id.eq(1))
         .first(&connection)
         .unwrap();
     assert_eq!(Some("black".to_string()), data);
 
-    let command = update(users.filter(id.eq(1))).set(hair_color.eq(None::<String>));
-    connection.execute_returning_count(&command).unwrap();
+    update(users.filter(id.eq(1))).set(hair_color.eq(None::<String>))
+        .execute(&connection).unwrap();
 
     let data: QueryResult<Option<String>> = users.select(hair_color)
         .filter(id.eq(1))
@@ -64,11 +63,10 @@ fn test_updating_multiple_columns() {
 
     let connection = connection_with_sean_and_tess_in_users_table();
 
-    let command = update(users.filter(id.eq(1))).set((
+    update(users.filter(id.eq(1))).set((
         name.eq("Jim"),
         hair_color.eq(Some("black")),
-    ));
-    connection.execute_returning_count(&command).unwrap();
+    )).execute(&connection).unwrap();
 
     let expected_user = User::with_hair_color(1, "Jim", "black");
     let user = connection.find(users, 1);