Merge remote-tracking branch 'upstream/master' into faillible_queryable_stillgeneric

Author: Ten0

diesel/src/expression/operators.rs

@@ -421,6 +421,7 @@ macro_rules! diesel_prefix_operator {
 }
 
 infix_operator!(And, " AND ");
+infix_operator!(Or, " OR ");
 infix_operator!(Escape, " ESCAPE ");
 infix_operator!(Eq, " = ");
 infix_operator!(Gt, " > ");
@@ -457,10 +458,7 @@ use crate::expression::{TypedExpressionType, ValidGrouping};
 use crate::insertable::{ColumnInsertValue, Insertable};
 use crate::query_builder::{QueryFragment, QueryId, ValuesClause};
 use crate::query_source::Column;
-use crate::sql_types::{
-    is_nullable, AllAreNullable, Bool, DieselNumericOps, MaybeNullableType, SqlType,
-};
-use crate::Expression;
+use crate::sql_types::{DieselNumericOps, SqlType};
 
 impl<T, U> Insertable<T::Table> for Eq<T, U>
 where
@@ -529,58 +527,3 @@ where
         Ok(())
     }
 }
-
-// or is different
-// it only evaluates to null if both sides are null
-#[derive(
-    Debug,
-    Clone,
-    Copy,
-    crate::query_builder::QueryId,
-    crate::sql_types::DieselNumericOps,
-    crate::expression::ValidGrouping,
-)]
-#[doc(hidden)]
-pub struct Or<T, U> {
-    pub(crate) left: T,
-    pub(crate) right: U,
-}
-
-impl<T, U> Or<T, U> {
-    pub fn new(left: T, right: U) -> Self {
-        Or { left, right }
-    }
-}
-
-impl_selectable_expression!(Or<T, U>);
-
-impl<T, U> Expression for Or<T, U>
-where
-    T: Expression,
-    U: Expression,
-    T::SqlType: SqlType,
-    U::SqlType: SqlType,
-    is_nullable::IsSqlTypeNullable<T::SqlType>:
-        AllAreNullable<is_nullable::IsSqlTypeNullable<U::SqlType>>,
-    is_nullable::AreAllNullable<T::SqlType, U::SqlType>: MaybeNullableType<Bool>,
-{
-    type SqlType =
-        is_nullable::MaybeNullable<is_nullable::AreAllNullable<T::SqlType, U::SqlType>, Bool>;
-}
-
-impl<T, U, DB> crate::query_builder::QueryFragment<DB> for Or<T, U>
-where
-    DB: crate::backend::Backend,
-    T: crate::query_builder::QueryFragment<DB>,
-    U: crate::query_builder::QueryFragment<DB>,
-{
-    fn walk_ast(
-        &self,
-        mut out: crate::query_builder::AstPass<DB>,
-    ) -> crate::result::QueryResult<()> {
-        self.left.walk_ast(out.reborrow())?;
-        out.push_sql(" OR ");
-        self.right.walk_ast(out.reborrow())?;
-        Ok(())
-    }
-}

diesel/src/expression/sql_literal.rs

@@ -73,7 +73,7 @@ where
     ///
     /// ```rust
     /// # include!("../doctest_setup.rs");
-    ///
+    /// #
     /// # table! {
     /// #    users {
     /// #        id -> Integer,
@@ -125,7 +125,7 @@ where
     ///
     /// ```rust
     /// # include!("../doctest_setup.rs");
-    ///
+    /// #
     /// # table! {
     /// #    users {
     /// #        id -> Integer,
@@ -199,7 +199,7 @@ impl<ST, T, GB> ValidGrouping<GB> for SqlLiteral<ST, T> {
     type IsAggregate = is_aggregate::Never;
 }
 
-/// Use literal SQL in the query builder
+/// Use literal SQL in the query builder.
 ///
 /// Available for when you truly cannot represent something using the expression
 /// DSL. You will need to provide the SQL type of the expression, in addition to
@@ -209,6 +209,8 @@ impl<ST, T, GB> ValidGrouping<GB> for SqlLiteral<ST, T> {
 /// your query. If you want to write the entire query using raw SQL, use
 /// [`sql_query`](../fn.sql_query.html) instead.
 ///
+/// Query parameters can be bound into the literal SQL using [`SqlLiteral::bind()`].
+///
 /// # Safety
 ///
 /// The compiler will be unable to verify the correctness of the annotated type.
@@ -220,10 +222,11 @@ impl<ST, T, GB> ValidGrouping<GB> for SqlLiteral<ST, T> {
 /// ```rust
 /// # include!("../doctest_setup.rs");
 /// # fn main() {
-/// #     run_test().unwrap();
+/// #     run_test_1().unwrap();
+/// #     run_test_2().unwrap();
 /// # }
 /// #
-/// # fn run_test() -> QueryResult<()> {
+/// # fn run_test_1() -> QueryResult<()> {
 /// #     use schema::users::dsl::*;
 /// #     use diesel::sql_types::Bool;
 /// use diesel::dsl::sql;
@@ -233,7 +236,30 @@ impl<ST, T, GB> ValidGrouping<GB> for SqlLiteral<ST, T> {
 /// assert_eq!(expected, user);
 /// #     Ok(())
 /// # }
+/// #
+/// # fn run_test_2() -> QueryResult<()> {
+/// #     use crate::schema::users::dsl::*;
+/// #     use diesel::dsl::sql;
+/// #     use diesel::sql_types::{Bool, Integer, Text};
+/// #     let connection = establish_connection();
+/// #     diesel::insert_into(users)
+/// #         .values(name.eq("Ryan"))
+/// #         .execute(&connection).unwrap();
+/// let query = users
+///     .select(name)
+///     .filter(
+///         sql::<Bool>("id > ")
+///         .bind::<Integer,_>(1)
+///         .sql(" AND name <> ")
+///         .bind::<Text, _>("Ryan")
+///     )
+///     .get_results(&connection);
+/// let expected = vec!["Tess".to_string()];
+/// assert_eq!(Ok(expected), query);
+/// #     Ok(())
+/// # }
 /// ```
+/// [`SqlLiteral::bind()`]: ../expression/struct.SqlLiteral.html#method.bind
 pub fn sql<ST>(sql: &str) -> SqlLiteral<ST>
 where
     ST: TypedExpressionType,
@@ -245,7 +271,7 @@ where
 #[must_use = "Queries are only executed when calling `load`, `get_result`, or similar."]
 /// Returned by the [`SqlLiteral::bind()`] method when binding a value to a fragment of SQL.
 ///
-/// [`bind()`]: ./struct.SqlLiteral.html#method.bind
+/// [`SqlLiteral::bind()`]: ./struct.SqlLiteral.html#method.bind
 pub struct UncheckedBind<Query, Value> {
     query: Query,
     value: Value,
@@ -259,7 +285,7 @@ where
         UncheckedBind { query, value }
     }
 
-    /// Use literal SQL in the query builder
+    /// Use literal SQL in the query builder.
     ///
     /// 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
@@ -275,7 +301,7 @@ where
     ///
     /// ```rust
     /// # include!("../doctest_setup.rs");
-    ///
+    /// #
     /// # table! {
     /// #    users {
     /// #        id -> Integer,

diesel/src/query_builder/functions.rs

@@ -512,7 +512,13 @@ pub fn replace_into<T>(target: T) -> IncompleteInsertStatement<T, Replace> {
 /// supported by the query builder. Unlike most queries in Diesel, `sql_query`
 /// will deserialize its data by name, not by index. That means that you cannot
 /// deserialize into a tuple, and structs which you deserialize from this
-/// function will need to have `#[derive(QueryableByName)]`
+/// function will need to have `#[derive(QueryableByName)]`.
+///
+/// This function is intended for use when you want to write the entire query
+/// using raw SQL. If you only need a small bit of raw SQL in your query, use
+/// [`sql`](./dsl/fn.sql.html) instead.
+///
+/// Query parameters can be bound into the raw query using [`SqlQuery::bind()`].
 ///
 /// # Safety
 ///
@@ -521,7 +527,7 @@ pub fn replace_into<T>(target: T) -> IncompleteInsertStatement<T, Replace> {
 /// that the given type is correct. If your query returns a column of an
 /// unexpected type, the result may have the wrong value, or return an error.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # include!("../doctest_setup.rs");
@@ -536,7 +542,13 @@ pub fn replace_into<T>(target: T) -> IncompleteInsertStatement<T, Replace> {
 /// # }
 /// #
 /// # fn main() {
+/// #     run_test_1().unwrap();
+/// #     run_test_2().unwrap();
+/// # }
+/// #
+/// # fn run_test_1() -> QueryResult<()> {
 /// #     use diesel::sql_query;
+/// #     use diesel::sql_types::{Integer, Text};
 /// #
 /// #     let connection = establish_connection();
 /// let users = sql_query("SELECT * FROM users ORDER BY id")
@@ -546,8 +558,34 @@ pub fn replace_into<T>(target: T) -> IncompleteInsertStatement<T, Replace> {
 ///     User { id: 2, name: "Tess".into() },
 /// ];
 /// assert_eq!(Ok(expected_users), users);
+/// #     Ok(())
+/// # }
+///
+/// # fn run_test_2() -> QueryResult<()> {
+/// #     use diesel::sql_query;
+/// #     use diesel::sql_types::{Integer, Text};
+/// #
+/// #     let connection = establish_connection();
+/// #     diesel::insert_into(users::table)
+/// #         .values(users::name.eq("Jim"))
+/// #         .execute(&connection).unwrap();
+/// #     #[cfg(feature = "postgres")]
+/// #     let users = sql_query("SELECT * FROM users WHERE id > $1 AND name != $2");
+/// #     #[cfg(not(feature = "postgres"))]
+/// let users = sql_query("SELECT * FROM users WHERE id > ? AND name <> ?")
+/// # ;
+/// let users = users
+///     .bind::<Integer, _>(1)
+///     .bind::<Text, _>("Tess")
+///     .get_results(&connection);
+/// let expected_users = vec![
+///     User { id: 3, name: "Jim".into() },
+/// ];
+/// assert_eq!(Ok(expected_users), users);
+/// #     Ok(())
 /// # }
 /// ```
+/// [`SqlQuery::bind()`]: query_builder/struct.SqlQuery.html#method.bind
 pub fn sql_query<T: Into<String>>(query: T) -> SqlQuery<()> {
     SqlQuery::new((), query.into())
 }

diesel/src/query_builder/sql_query.rs

@@ -124,6 +124,9 @@ impl<Inner, Conn> RunQueryDsl<Conn> for SqlQuery<Inner> {}
 
 #[derive(Debug, Clone, Copy)]
 #[must_use = "Queries are only executed when calling `load`, `get_result` or similar."]
+/// Returned by the [`SqlQuery::bind()`] method when binding a value to a fragment of SQL.
+///
+/// [`SqlQuery::bind()`]: ./struct.SqlQuery.html#method.bind
 pub struct UncheckedBind<Query, Value, ST> {
     query: Query,
     value: Value,
@@ -147,6 +150,65 @@ impl<Query, Value, ST> UncheckedBind<Query, Value, ST> {
         BoxedSqlQuery::new(self)
     }
 
+    /// Construct a full SQL query using raw SQL.
+    ///
+    /// This function exists for cases where a query needs to be written that is not
+    /// supported by the query builder. Unlike most queries in Diesel, `sql_query`
+    /// will deserialize its data by name, not by index. That means that you cannot
+    /// deserialize into a tuple, and structs which you deserialize from this
+    /// function will need to have `#[derive(QueryableByName)]`.
+    ///
+    /// This function is intended for use when you want to write the entire query
+    /// using raw SQL. If you only need a small bit of raw SQL in your query, use
+    /// [`sql`](./dsl/fn.sql.html) instead.
+    ///
+    /// Query parameters can be bound into the raw query using [`SqlQuery::bind()`].
+    ///
+    /// # Safety
+    ///
+    /// The implementation of `QueryableByName` will assume that columns with a
+    /// given name will have a certain type. The compiler will be unable to verify
+    /// that the given type is correct. If your query returns a column of an
+    /// unexpected type, the result may have the wrong value, or return an error.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # include!("../doctest_setup.rs");
+    /// #
+    /// # use schema::users;
+    /// #
+    /// # #[derive(QueryableByName, Debug, PartialEq)]
+    /// # #[table_name="users"]
+    /// # struct User {
+    /// #     id: i32,
+    /// #     name: String,
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     use diesel::sql_query;
+    /// #     use diesel::sql_types::{Integer, Text};
+    /// #
+    /// #     let connection = establish_connection();
+    /// #     diesel::insert_into(users::table)
+    /// #         .values(users::name.eq("Jim"))
+    /// #         .execute(&connection).unwrap();
+    /// # #[cfg(feature = "postgres")]
+    /// # let users = sql_query("SELECT * FROM users WHERE id > $1 AND name != $2");
+    /// # #[cfg(not(feature = "postgres"))]
+    /// let users = sql_query("SELECT * FROM users WHERE id > ? AND name <> ?")
+    /// # ;
+    /// # let users = users
+    ///     .bind::<Integer, _>(1)
+    ///     .bind::<Text, _>("Tess")
+    ///     .get_results(&connection);
+    /// let expected_users = vec![
+    ///     User { id: 3, name: "Jim".into() },
+    /// ];
+    /// assert_eq!(Ok(expected_users), users);
+    /// # }
+    /// ```
+    /// [`SqlQuery::bind()`]: query_builder/struct.SqlQuery.html#method.bind
     pub fn sql<T: Into<String>>(self, sql: T) -> SqlQuery<Self> {
         SqlQuery::new(self, sql.into())
     }