Introduce a #[declare_sql_function] attribute macro

CHANGELOG.md

@@ -16,13 +16,24 @@ Increasing the minimal supported Rust version will always be coupled at least wi
 * Fixed `#[derive(Identifiable)]` ignoring attribute `#[diesel(serialize_as)]` on primary keys
 * Added embedded struct support for `AsChangeset` via `#[diesel(embed)]`
 * Support for libsqlite3-sys 0.30.0
-* Add support for built-in PostgreSQL range operators and functions
+* Added support for built-in PostgreSQL range operators and functions
+* Added support for various built-in PostgreSQL array functions
 * Support for postgres multirange type
 * Added `diesel::r2d2::TestCustomizer`, which allows users to customize their `diesel::r2d2::Pool`s
 in a way that makes the pools suitable for use in parallel tests.
 * Added `Json` and `Jsonb` support for the SQLite backend.
+* Added a `#[diesel::declare_sql_function]` attribute macro to easily define support for 
+  multiple sql functions at once via an `extern "SQL"` block
+
+### Fixed 
+
 * Fixed diesel thinking `a.eq_any(b)` was non-nullable even if `a` and `b` were nullable.
 
+### Deprecated
+
+* The `diesel::define_sql_function!` is now deprecated in favour of the `#[diesel::declare_sql_function]` 
+  attribute macro.
+
 ## [2.2.2] 2024-07-19
 
 ### Fixed

diesel/src/connection/statement_cache/strategy.rs

@@ -148,7 +148,6 @@ mod testing_utils {
 mod tests_pg {
     use crate::connection::CacheSize;
     use crate::dsl::sql;
-    use crate::expression::functions::define_sql_function;
     use crate::insertable::Insertable;
     use crate::pg::Pg;
     use crate::sql_types::{Integer, VarChar};
@@ -158,6 +157,11 @@ mod tests_pg {
 
     use super::testing_utils::{count_cache_calls, RecordCacheEvents};
 
+    #[crate::declare_sql_function]
+    extern "SQL" {
+        fn lower(x: VarChar) -> VarChar;
+    }
+
     table! {
         users {
             id -> Integer,
@@ -209,8 +213,6 @@ mod tests_pg {
         assert_eq!(2, count_cache_calls(connection));
     }
 
-    define_sql_function!(fn lower(x: VarChar) -> VarChar);
-
     #[test]
     fn queries_with_identical_types_and_binds_but_different_sql_are_cached_separately() {
         let connection = &mut connection();

diesel/src/expression/count.rs

@@ -1,6 +1,6 @@
 use std::marker::PhantomData;
 
-use super::functions::define_sql_function;
+use super::functions::declare_sql_function;
 use super::{is_aggregate, AsExpression};
 use super::{Expression, ValidGrouping};
 use crate::backend::Backend;
@@ -9,7 +9,8 @@ use crate::result::QueryResult;
 use crate::sql_types::{BigInt, DieselNumericOps, SingleValue, SqlType};
 use crate::{AppearsOnTable, SelectableExpression};
 
-define_sql_function! {
+#[declare_sql_function]
+extern "SQL" {
     /// Creates a SQL `COUNT` expression
     ///
     /// As with most bare functions, this is not exported by default. You can import

diesel/src/expression/functions/aggregate_folding.rs

@@ -1,7 +1,8 @@
-use crate::expression::functions::define_sql_function;
+use crate::expression::functions::declare_sql_function;
 use crate::sql_types::Foldable;
 
-define_sql_function! {
+#[declare_sql_function]
+extern "SQL" {
     /// Represents a SQL `SUM` function. This function can only take types which are
     /// Foldable.
     ///
@@ -19,9 +20,7 @@ define_sql_function! {
     /// ```
     #[aggregate]
     fn sum<ST: Foldable>(expr: ST) -> ST::Sum;
-}
 
-define_sql_function! {
     /// Represents a SQL `AVG` function. This function can only take types which are
     /// Foldable.
     ///

diesel/src/expression/functions/aggregate_ordering.rs

@@ -1,7 +1,8 @@
 use self::private::SqlOrdAggregate;
-use crate::expression::functions::define_sql_function;
+use crate::expression::functions::declare_sql_function;
 
-define_sql_function! {
+#[declare_sql_function]
+extern "SQL" {
     /// Represents a SQL `MAX` function. This function can only take types which are
     /// ordered.
     ///
@@ -18,9 +19,7 @@ define_sql_function! {
     /// # }
     #[aggregate]
     fn max<ST: SqlOrdAggregate>(expr: ST) -> ST::Ret;
-}
 
-define_sql_function! {
     /// Represents a SQL `MIN` function. This function can only take types which are
     /// ordered.
     ///

diesel/src/expression/functions/date_and_time.rs

@@ -1,6 +1,6 @@
 use crate::backend::Backend;
 use crate::expression::coerce::Coerce;
-use crate::expression::functions::define_sql_function;
+use crate::expression::functions::declare_sql_function;
 use crate::expression::{AsExpression, Expression, ValidGrouping};
 use crate::query_builder::*;
 use crate::result::QueryResult;
@@ -27,7 +27,9 @@ impl_selectable_expression!(now);
 
 operator_allowed!(now, Add, add);
 operator_allowed!(now, Sub, sub);
-define_sql_function! {
+
+#[declare_sql_function]
+extern "SQL" {
     /// Represents the SQL `DATE` function. The argument should be a Timestamp
     /// expression, and the return value will be an expression of type Date.
     ///

diesel/src/expression/functions/mod.rs

@@ -1,5 +1,9 @@
 //! Helper macros to define custom sql functions
 
+#[doc(inline)]
+pub use diesel_derives::declare_sql_function;
+
+#[cfg(all(feature = "with-deprecated", not(feature = "without-deprecated")))]
 #[doc(inline)]
 pub use diesel_derives::define_sql_function;
 

diesel/src/lib.rs

@@ -725,6 +725,8 @@ pub mod prelude {
     pub use crate::expression::IntoSql as _;
 
     #[doc(inline)]
+    pub use crate::expression::functions::declare_sql_function;
+    #[cfg(all(feature = "with-deprecated", not(feature = "without-deprecated")))]
     pub use crate::expression::functions::define_sql_function;
     #[cfg(all(feature = "with-deprecated", not(feature = "without-deprecated")))]
     pub use crate::expression::functions::sql_function;