Implement a new raw SQL API geared towards complete queries

`sql` has always been a bit clunky to use if you wanted to write a whole
query with it. You have to specify the SQL type of the query, which also
means you have to list every column out explicitly to ensure they're in
the expected order.

This adds a replacement API that more geared towards writing complete
queries. There are two notable differences. The first is that the SQL
type of each field is specified during deserialization, not when the
query is constructed. The types are never checked anyway (other than to
make sure the deserialization is valid), so it makes sense to defer this
to a place where we can derive it.

The second difference is that columns are deserialized by name, not by
index. This has all of the gotchas that are associated with doing that
with other libraries (name conflicts between tables, etc)

I had originally planned on having `NamedRow::get` optionally also take
a table name. However, PG gives you the OID not the name, so we'd need
to do another query to get the table name. SQLite only gives you the
table/column name if compiled with a flag to enable it, which the system
sqlite3 on mac does not.

For those two reasons, I've opted to use the column name alone. This
means that the derived `QueryableByName` is unlikely to be usable with
joins, but that's a price we'll have to pay for now.

I'd like to expand the number of cases that our derive impl can handle
(e.g. allow providing a sql type in addition to a column name), but this
is a good bare minimum place to start.

Fixes diesel-rs#650.

Author: sgrif

CHANGELOG.md

@@ -42,6 +42,11 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
 * `allow_tables_to_appear_in_same_query!` can now take more than 2 tables, and is the same
   as invoking it separately for every combination of those tables.
 
+* Added `sql_query`, a new API for dropping to raw SQL that is more pleasant to
+  use than `sql` for complete queries. The main difference from `sql` is that
+  you do not need to state the return type, and data is loaded from the query by
+  name rather than by index.
+
 ### Changed
 
 * The signatures of `QueryId`, `Column`, and `FromSqlRow` have all changed to
@@ -74,6 +79,11 @@ for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/
 * Deprecated `enable_multi_table_joins` in favor of
   `allow_tables_to_appear_in_same_query!`
 
+* Deprecated `SqlLiteral#bind`. `sql` is intended for use with small fragments
+  of SQL, not complete queries. Writing bind parameters in raw SQL when you are
+  not writing the whole query is error-prone. Use `sql_query` if you need raw
+  SQL with bind parameters.
+
 ### Removed
 
 * `IntoInsertStatement` and `BatchInsertStatement` have been removed. It's

diesel/Cargo.toml

@@ -33,7 +33,7 @@ bitflags = { version = "0.9", optional = true }
 
 [dev-dependencies]
 cfg-if = "0.1.0"
-diesel_codegen = "0.13.0"
+diesel_codegen = "0.16.0"
 dotenv = ">=0.8, <0.11"
 quickcheck = "0.3.1"
 tempdir = "^0.3.4"

diesel/src/connection/mod.rs

@@ -3,7 +3,7 @@ mod transaction_manager;
 
 use backend::Backend;
 use query_builder::{AsQuery, QueryFragment, QueryId};
-use query_source::Queryable;
+use query_source::{Queryable, QueryableByName};
 use result::*;
 use types::HasSqlType;
 
@@ -145,6 +145,12 @@ pub trait Connection: SimpleConnection + Sized + Send {
         Self::Backend: HasSqlType<T::SqlType>,
         U: Queryable<T::SqlType, Self::Backend>;
 
+    #[doc(hidden)]
+    fn query_by_name<T, U>(&self, source: &T) -> QueryResult<Vec<U>>
+    where
+        T: QueryFragment<Self::Backend> + QueryId,
+        U: QueryableByName<Self::Backend>;
+
     #[doc(hidden)]
     fn execute_returning_count<T>(&self, source: &T) -> QueryResult<usize>
     where

diesel/src/expression/sql_literal.rs

@@ -4,6 +4,7 @@ use backend::Backend;
 use expression::*;
 use query_builder::*;
 use result::QueryResult;
+#[cfg(feature = "with-deprecated")]
 use super::unchecked_bind::UncheckedBind;
 use types::HasSqlType;
 
@@ -99,6 +100,8 @@ impl<ST> SqlLiteral<ST> {
     /// assert_eq!(Ok(expected), query.load(&connection));
     /// # }
     /// ```
+    #[deprecated(since = "0.99.0", note = "use `sql_query` if you need bind parameters")]
+    #[cfg(feature = "with-deprecated")]
     pub fn bind<BindST, T>(self, bind_value: T) -> UncheckedBind<Self, T, BindST> {
         UncheckedBind::new(self, bind_value)
     }
@@ -137,11 +140,9 @@ impl<ST> NonAggregate for SqlLiteral<ST> {}
 /// DSL. You will need to provide the SQL type of the expression, in addition to
 /// the SQL.
 ///
-/// # Bound parameters
-///
-/// If you need to pass arguments to your query, you should use [`.bind()`].
-///
-/// [`.bind()`]: ../sql_literal/struct.SqlLiteral.html#method.bind
+/// This function is intended for use when you need a small bit of raw SQL in
+/// your query. If you want to write the entire query using raw SQL, use
+/// [`sql_query`](../fn.sql_query.html) instead.
 ///
 /// # Safety
 ///

diesel/src/expression/unchecked_bind.rs

@@ -1,3 +1,5 @@
+#![cfg(feature = "with-deprecated")]
+
 use std::marker::PhantomData;
 
 use backend::Backend;

diesel/src/lib.rs

@@ -173,7 +173,7 @@ pub use prelude::*;
 #[doc(inline)]
 pub use query_builder::debug_query;
 #[doc(inline)]
-pub use query_builder::functions::{delete, insert_into, replace_into, select, update};
+pub use query_builder::functions::{delete, insert_into, replace_into, select, sql_query, update};
 #[cfg(feature = "with-deprecated")]
 #[doc(inline)]
 #[allow(deprecated)]

diesel/src/mysql/connection/bind.rs

@@ -34,6 +34,16 @@ impl Binds {
         Binds { data: data }
     }
 
+    pub fn from_result_metadata(fields: &[ffi::MYSQL_FIELD]) -> Self {
+        let data = fields
+            .iter()
+            .map(|field| field.type_)
+            .map(BindData::for_output)
+            .collect();
+
+        Binds { data }
+    }
+
     pub fn with_mysql_binds<F, T>(&mut self, f: F) -> T
     where
         F: FnOnce(*mut ffi::MYSQL_BIND) -> T,

diesel/src/mysql/connection/mod.rs

@@ -6,7 +6,7 @@ mod url;
 use connection::*;
 use query_builder::*;
 use query_builder::bind_collector::RawBytesBindCollector;
-use query_source::Queryable;
+use query_source::{Queryable, QueryableByName};
 use result::*;
 use self::raw::RawConnection;
 use self::stmt::Statement;
@@ -80,6 +80,19 @@ impl Connection for MysqlConnection {
         })
     }
 
+    #[doc(hidden)]
+    fn query_by_name<T, U>(&self, source: &T) -> QueryResult<Vec<U>>
+    where
+        T: QueryFragment<Self::Backend> + QueryId,
+        U: QueryableByName<Self::Backend>,
+    {
+        use result::Error::DeserializationError;
+
+        let mut stmt = try!(self.prepare_query(source));
+        let results = unsafe { stmt.named_results()? };
+        results.map(|row| U::build(&row).map_err(DeserializationError))
+    }
+
     #[doc(hidden)]
     fn execute_returning_count<T>(&self, source: &T) -> QueryResult<usize>
     where

diesel/src/mysql/connection/stmt/iterator.rs

@@ -1,6 +1,8 @@
-use super::{ffi, libc, Binds, Statement};
+use std::collections::HashMap;
+
+use super::{ffi, libc, Binds, Statement, StatementMetadata};
 use result::QueryResult;
-use row::Row;
+use row::*;
 use mysql::{Mysql, MysqlType};
 
 pub struct StatementIterator<'a> {
@@ -13,10 +15,7 @@ impl<'a> StatementIterator<'a> {
     pub fn new(stmt: &'a mut Statement, types: Vec<MysqlType>) -> QueryResult<Self> {
         let mut output_binds = Binds::from_output_types(types);
 
-        unsafe {
-            output_binds.with_mysql_binds(|bind_ptr| stmt.bind_result(bind_ptr))?;
-            stmt.execute()?;
-        }
+        execute_statement(stmt, &mut output_binds)?;
 
         Ok(StatementIterator {
             stmt: stmt,
@@ -36,25 +35,14 @@ impl<'a> StatementIterator<'a> {
     }
 
     fn next(&mut self) -> Option<QueryResult<MysqlRow>> {
-        let next_row_result = unsafe { ffi::mysql_stmt_fetch(self.stmt.stmt) };
-        match next_row_result as libc::c_uint {
-            ffi::MYSQL_NO_DATA => return None,
-            ffi::MYSQL_DATA_TRUNCATED => {
-                let res = self.output_binds.populate_dynamic_buffers(self.stmt);
-                if let Err(e) = res {
-                    return Some(Err(e));
-                }
-            }
-            0 => self.output_binds.update_buffer_lengths(),
-            _error => if let Err(e) = self.stmt.did_an_error_occur() {
-                return Some(Err(e));
-            },
+        match populate_row_buffers(self.stmt, &mut self.output_binds) {
+            Ok(Some(())) => Some(Ok(MysqlRow {
+                col_idx: 0,
+                binds: &mut self.output_binds,
+            })),
+            Ok(None) => None,
+            Err(e) => Some(Err(e)),
         }
-
-        Some(Ok(MysqlRow {
-            col_idx: 0,
-            binds: &mut self.output_binds,
-        }))
     }
 }
 
@@ -74,3 +62,83 @@ impl<'a> Row<Mysql> for MysqlRow<'a> {
         (0..count).all(|i| self.binds.field_data(self.col_idx + i).is_none())
     }
 }
+
+pub struct NamedStatementIterator<'a> {
+    stmt: &'a mut Statement,
+    output_binds: Binds,
+    metadata: StatementMetadata,
+}
+
+#[cfg_attr(feature = "clippy", allow(should_implement_trait))] // don't need `Iterator` here
+impl<'a> NamedStatementIterator<'a> {
+    pub fn new(stmt: &'a mut Statement) -> QueryResult<Self> {
+        let metadata = stmt.metadata()?;
+        let mut output_binds = Binds::from_result_metadata(metadata.fields());
+
+        execute_statement(stmt, &mut output_binds)?;
+
+        Ok(NamedStatementIterator {
+            stmt,
+            output_binds,
+            metadata,
+        })
+    }
+
+    pub fn map<F, T>(mut self, mut f: F) -> QueryResult<Vec<T>>
+    where
+        F: FnMut(NamedMysqlRow) -> QueryResult<T>,
+    {
+        let mut results = Vec::new();
+        while let Some(row) = self.next() {
+            results.push(f(row?)?);
+        }
+        Ok(results)
+    }
+
+    fn next(&mut self) -> Option<QueryResult<NamedMysqlRow>> {
+        match populate_row_buffers(self.stmt, &mut self.output_binds) {
+            Ok(Some(())) => Some(Ok(NamedMysqlRow {
+                binds: &self.output_binds,
+                column_indices: self.metadata.column_indices(),
+            })),
+            Ok(None) => None,
+            Err(e) => Some(Err(e)),
+        }
+    }
+}
+
+pub struct NamedMysqlRow<'a> {
+    binds: &'a Binds,
+    column_indices: &'a HashMap<&'a str, usize>,
+}
+
+impl<'a> NamedRow<Mysql> for NamedMysqlRow<'a> {
+    fn index_of(&self, column_name: &str) -> Option<usize> {
+        self.column_indices.get(column_name).cloned()
+    }
+
+    fn get_raw_value(&self, idx: usize) -> Option<&[u8]> {
+        self.binds.field_data(idx)
+    }
+}
+
+fn execute_statement(stmt: &mut Statement, binds: &mut Binds) -> QueryResult<()> {
+    unsafe {
+        binds.with_mysql_binds(|bind_ptr| stmt.bind_result(bind_ptr))?;
+        stmt.execute()?;
+    }
+    Ok(())
+}
+
+fn populate_row_buffers(stmt: &Statement, binds: &mut Binds) -> QueryResult<Option<()>> {
+    let next_row_result = unsafe { ffi::mysql_stmt_fetch(stmt.stmt) };
+    match next_row_result as libc::c_uint {
+        ffi::MYSQL_NO_DATA => Ok(None),
+        ffi::MYSQL_DATA_TRUNCATED => binds.populate_dynamic_buffers(stmt).map(Some),
+        0 => {
+            binds.update_buffer_lengths();
+            Ok(Some(()))
+        }
+        _error => stmt.did_an_error_occur().map(Some),
+    }
+}

diesel/src/mysql/connection/stmt/metadata.rs

@@ -0,0 +1,51 @@
+use std::collections::HashMap;
+use std::ffi::CStr;
+use std::slice;
+
+use super::ffi;
+
+pub struct StatementMetadata {
+    result: &'static mut ffi::MYSQL_RES,
+    column_indices: HashMap<&'static str, usize>,
+}
+
+impl StatementMetadata {
+    pub fn new(result: &'static mut ffi::MYSQL_RES) -> Self {
+        let mut res = StatementMetadata {
+            column_indices: HashMap::new(),
+            result,
+        };
+        res.populate_column_indices();
+        res
+    }
+
+    pub fn fields(&self) -> &[ffi::MYSQL_FIELD] {
+        unsafe {
+            let ptr = self.result as *const _ as *mut _;
+            let num_fields = ffi::mysql_num_fields(ptr);
+            let field_ptr = ffi::mysql_fetch_fields(ptr);
+            slice::from_raw_parts(field_ptr, num_fields as usize)
+        }
+    }
+
+    pub fn column_indices(&self) -> &HashMap<&str, usize> {
+        &self.column_indices
+    }
+
+    fn populate_column_indices(&mut self) {
+        self.column_indices = self.fields()
+            .iter()
+            .enumerate()
+            .map(|(i, field)| {
+                let c_name = unsafe { CStr::from_ptr(field.name) };
+                (c_name.to_str().unwrap_or_default(), i)
+            })
+            .collect()
+    }
+}
+
+impl Drop for StatementMetadata {
+    fn drop(&mut self) {
+        unsafe { ffi::mysql_free_result(self.result) };
+    }
+}