Merge pull request diesel-rs#3195 from weiznich/make_more_things_private

Put the `backend::sql_dialect` module behind the

Author: weiznich

diesel/src/backend.rs

@@ -142,7 +142,10 @@ pub type BindCollector<'a, DB> = <DB as HasBindCollector<'a>>::BindCollector;
 /// a custom `QueryFragment<YourBackend, YourSpecialSyntaxType>` implementation
 /// to specialize on generic `QueryFragment<DB, DB::AssociatedType>` implementations.
 ///
-/// See the [`sql_dialect`] module for options provided by diesel out of the box.
+#[cfg_attr(
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+    doc = "See the [`sql_dialect`] module for options provided by diesel out of the box."
+)]
 pub trait SqlDialect: self::private::TrustedBackend {
     /// Configures how this backends supports `RETURNING` clauses
     ///
@@ -157,21 +160,30 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementation for `ReturningClause`"
     )]
     ///
-    /// See [`sql_dialect::returning_clause`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::returning_clause`] for provided default implementations"
+    )]
     type ReturningClause;
     /// Configures how this backend supports `ON CONFLICT` clauses
     ///
     /// This allows backends to opt in `ON CONFLICT` clause support
     ///
-    /// See [`sql_dialect::on_conflict_clause`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::on_conflict_clause`] for provided default implementations"
+    )]
     type OnConflictClause;
     /// Configures how this backend handles the bare `DEFAULT` keyword for
     /// inserting the default value in a `INSERT INTO` `VALUES` clause
     ///
     /// This allows backends to opt in support for `DEFAULT` value expressions
     /// for insert statements
     ///
-    /// See [`sql_dialect::default_keyword_for_insert`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::default_keyword_for_insert`] for provided default implementations"
+    )]
     type InsertWithDefaultKeyword;
     /// Configures how this backend handles Batch insert statements
     ///
@@ -185,7 +197,10 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementation for `BatchInsert`"
     )]
     ///
-    /// See [`sql_dialect::batch_insert_support`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::batch_insert_support`] for provided default implementations"
+    )]
     type BatchInsertSupport;
     /// Configures how this backend handles the `DEFAULT VALUES` clause for
     /// insert statements.
@@ -200,7 +215,10 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementation for `DefaultValues`"
     )]
     ///
-    /// See [`sql_dialect::default_value_clause`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::default_value_clause`] for provided default implementations"
+    )]
     type DefaultValueClauseForInsert;
     /// Configures how this backend handles empty `FROM` clauses for select statements.
     ///
@@ -214,7 +232,10 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementation for `NoFromClause`"
     )]
     ///
-    /// See [`sql_dialect::from_clause_syntax`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::from_clause_syntax`] for provided default implementations"
+    )]
     type EmptyFromClauseSyntax;
     /// Configures how this backend handles `EXISTS()` expressions.
     ///
@@ -228,7 +249,10 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementation for `Exists`"
     )]
     ///
-    /// See [`sql_dialect::exists_syntax`] for provided default implementations
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::exists_syntax`] for provided default implementations"
+    )]
     type ExistsSyntax;
 
     /// Configures how this backend handles `IN()` and `NOT IN()` expressions.
@@ -245,18 +269,43 @@ pub trait SqlDialect: self::private::TrustedBackend {
         doc = "implementations for `In`, `NotIn` and `Many`"
     )]
     ///
-    /// See `[sql_dialect::array_comparison`] for provided default implementations
-    type ArrayComparision;
+    #[cfg_attr(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes",
+        doc = "See [`sql_dialect::array_comparison`] for provided default implementations"
+    )]
+    type ArrayComparison;
 }
 
 /// This module contains all options provided by diesel to configure the [`SqlDialect`] trait.
-pub mod sql_dialect {
+// This module is only public behind the unstable feature flag, as we may want to change SqlDialect
+// implementations of existing backends because of:
+// * The backend gained support for previously unsupported SQL operations
+// * The backend fixed/introduced a bug that requires special handling
+// * We got some edge case wrong with sharing the implementation between backends
+//
+// By not exposing these types publically we are able to change the exact definitions later on
+// as users cannot write trait bounds that ensure that a specific type is used in place of
+// an existing associated type.
+#[diesel_derives::__diesel_public_if(
+    feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+)]
+pub(crate) mod sql_dialect {
+    #![cfg_attr(
+        not(feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"),
+        // Otherwise there are false positives
+        // because the lint seems to believe that these pub statements
+        // are not required, but they are required through the various backend impls
+        allow(unreachable_pub)
+    )]
     #[cfg(doc)]
     use super::SqlDialect;
 
     /// This module contains all diesel provided reusable options to
     /// configure [`SqlDialect::OnConflictClause`]
-    pub mod on_conflict_clause {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod on_conflict_clause {
         /// A marker trait indicating if a `ON CONFLICT` clause is supported or not
         ///
         /// If you use a custom type to specify specialized support for `ON CONFLICT` clauses
@@ -271,7 +320,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::ReturningClause`]
-    pub mod returning_clause {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod returning_clause {
         /// A marker trait indicating if a `RETURNING` clause is supported or not
         ///
         /// If you use custom type to specify specialized support for `RETURNING` clauses
@@ -292,7 +344,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::InsertWithDefaultKeyword`]
-    pub mod default_keyword_for_insert {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod default_keyword_for_insert {
         /// A marker trait indicating if a `DEFAULT` like expression
         /// is supported as part of `INSERT INTO` clauses to indicate
         /// that a default value should be inserted at a specific position
@@ -318,7 +373,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::BatchInsertSupport`]
-    pub mod batch_insert_support {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod batch_insert_support {
         /// A marker trait indicating if batch insert statements
         /// are supported for this backend or not
         pub trait SupportsBatchInsert {}
@@ -341,7 +399,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::DefaultValueClauseForInsert`]
-    pub mod default_value_clause {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod default_value_clause {
 
         /// Indicates that this backend uses the
         /// `DEFAULT VALUES` syntax to specify
@@ -353,7 +414,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::EmptyFromClauseSyntax`]
-    pub mod from_clause_syntax {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod from_clause_syntax {
 
         /// Indicates that this backend skips
         /// the `FROM` clause in `SELECT` statements
@@ -364,7 +428,10 @@ pub mod sql_dialect {
 
     /// This module contains all reusable options to configure
     /// [`SqlDialect::ExistsSyntax`]
-    pub mod exists_syntax {
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod exists_syntax {
 
         /// Indicates that this backend
         /// treats `EXIST()` as function
@@ -374,8 +441,11 @@ pub mod sql_dialect {
     }
 
     /// This module contains all reusable options to configure
-    /// [`SqlDialect::ArrayComparision`]
-    pub mod array_comparision {
+    /// [`SqlDialect::ArrayComparison`]
+    #[diesel_derives::__diesel_public_if(
+        feature = "i-implement-a-third-party-backend-and-opt-into-breaking-changes"
+    )]
+    pub(crate) mod array_comparison {
 
         /// Indicates that this backend requires a single bind
         /// per array element in `IN()` and `NOT IN()` expression

diesel/src/expression/array_comparison.rs

@@ -23,7 +23,7 @@ use std::marker::PhantomData;
 ///
 /// Third party backend can customize the [`QueryFragment`]
 /// implementation of this query dsl node via
-/// [`SqlDialect::ArrayComparision`]. A customized implementation
+/// [`SqlDialect::ArrayComparison`]. A customized implementation
 /// is expected to provide the same sematics as a ANSI SQL
 /// `IN` expression.
 ///
@@ -43,7 +43,7 @@ pub struct In<T, U> {
 ///
 /// Third party backend can customize the [`QueryFragment`]
 /// implementation of this query dsl node via
-/// [`SqlDialect::ArrayComparision`]. A customized implementation
+/// [`SqlDialect::ArrayComparison`]. A customized implementation
 /// is expected to provide the same sematics as a ANSI SQL
 /// `NOT IN` expression.0
 ///
@@ -89,18 +89,17 @@ where
 impl<T, U, DB> QueryFragment<DB> for In<T, U>
 where
     DB: Backend,
-    Self: QueryFragment<DB, DB::ArrayComparision>,
+    Self: QueryFragment<DB, DB::ArrayComparison>,
 {
     fn walk_ast<'b>(&'b self, pass: AstPass<'_, 'b, DB>) -> QueryResult<()> {
-        <Self as QueryFragment<DB, DB::ArrayComparision>>::walk_ast(self, pass)
+        <Self as QueryFragment<DB, DB::ArrayComparison>>::walk_ast(self, pass)
     }
 }
 
-impl<T, U, DB> QueryFragment<DB, sql_dialect::array_comparision::AnsiSqlArrayComparison>
-    for In<T, U>
+impl<T, U, DB> QueryFragment<DB, sql_dialect::array_comparison::AnsiSqlArrayComparison> for In<T, U>
 where
     DB: Backend
-        + SqlDialect<ArrayComparision = sql_dialect::array_comparision::AnsiSqlArrayComparison>,
+        + SqlDialect<ArrayComparison = sql_dialect::array_comparison::AnsiSqlArrayComparison>,
     T: QueryFragment<DB>,
     U: QueryFragment<DB> + MaybeEmpty,
 {
@@ -120,18 +119,18 @@ where
 impl<T, U, DB> QueryFragment<DB> for NotIn<T, U>
 where
     DB: Backend,
-    Self: QueryFragment<DB, DB::ArrayComparision>,
+    Self: QueryFragment<DB, DB::ArrayComparison>,
 {
     fn walk_ast<'b>(&'b self, pass: AstPass<'_, 'b, DB>) -> QueryResult<()> {
-        <Self as QueryFragment<DB, DB::ArrayComparision>>::walk_ast(self, pass)
+        <Self as QueryFragment<DB, DB::ArrayComparison>>::walk_ast(self, pass)
     }
 }
 
-impl<T, U, DB> QueryFragment<DB, sql_dialect::array_comparision::AnsiSqlArrayComparison>
+impl<T, U, DB> QueryFragment<DB, sql_dialect::array_comparison::AnsiSqlArrayComparison>
     for NotIn<T, U>
 where
     DB: Backend
-        + SqlDialect<ArrayComparision = sql_dialect::array_comparision::AnsiSqlArrayComparison>,
+        + SqlDialect<ArrayComparison = sql_dialect::array_comparison::AnsiSqlArrayComparison>,
     T: QueryFragment<DB>,
     U: QueryFragment<DB> + MaybeEmpty,
 {
@@ -234,7 +233,7 @@ where
 ///
 /// Third party backend can customize the [`QueryFragment`]
 /// implementation of this query dsl node via
-/// [`SqlDialect::ArrayComparision`]. The default
+/// [`SqlDialect::ArrayComparison`]. The default
 /// implementation does generate one bind per value
 /// in the `values` field.
 ///
@@ -290,20 +289,20 @@ where
 
 impl<ST, I, DB> QueryFragment<DB> for Many<ST, I>
 where
-    Self: QueryFragment<DB, DB::ArrayComparision>,
+    Self: QueryFragment<DB, DB::ArrayComparison>,
     DB: Backend,
 {
     fn walk_ast<'b>(&'b self, pass: AstPass<'_, 'b, DB>) -> QueryResult<()> {
-        <Self as QueryFragment<DB, DB::ArrayComparision>>::walk_ast(self, pass)
+        <Self as QueryFragment<DB, DB::ArrayComparison>>::walk_ast(self, pass)
     }
 }
 
-impl<ST, I, DB> QueryFragment<DB, sql_dialect::array_comparision::AnsiSqlArrayComparison>
+impl<ST, I, DB> QueryFragment<DB, sql_dialect::array_comparison::AnsiSqlArrayComparison>
     for Many<ST, I>
 where
     DB: Backend
         + HasSqlType<ST>
-        + SqlDialect<ArrayComparision = sql_dialect::array_comparision::AnsiSqlArrayComparison>,
+        + SqlDialect<ArrayComparison = sql_dialect::array_comparison::AnsiSqlArrayComparison>,
     ST: SingleValue,
     I: ToSql<ST, DB>,
 {

diesel/src/mysql/backend.rs

@@ -89,7 +89,7 @@ impl SqlDialect for Mysql {
     type EmptyFromClauseSyntax = sql_dialect::from_clause_syntax::AnsiSqlFromClauseSyntax;
     type ExistsSyntax = sql_dialect::exists_syntax::AnsiSqlExistsSyntax;
 
-    type ArrayComparision = sql_dialect::array_comparision::AnsiSqlArrayComparison;
+    type ArrayComparison = sql_dialect::array_comparison::AnsiSqlArrayComparison;
 }
 
 impl DieselReserveSpecialization for Mysql {}

diesel/src/pg/backend.rs

@@ -140,7 +140,7 @@ impl SqlDialect for Pg {
 
     type EmptyFromClauseSyntax = sql_dialect::from_clause_syntax::AnsiSqlFromClauseSyntax;
     type ExistsSyntax = sql_dialect::exists_syntax::AnsiSqlExistsSyntax;
-    type ArrayComparision = PgStyleArrayComparision;
+    type ArrayComparison = PgStyleArrayComparision;
 }
 
 impl DieselReserveSpecialization for Pg {}

diesel/src/sqlite/backend.rs

@@ -59,7 +59,7 @@ impl SqlDialect for Sqlite {
     #[cfg(feature = "returning_clauses_for_sqlite_3_35")]
     type ReturningClause = sql_dialect::returning_clause::PgLikeReturningClause;
 
-    type OnConflictClause = SqliteOnConflictClaues;
+    type OnConflictClause = SqliteOnConflictClause;
 
     type InsertWithDefaultKeyword =
         sql_dialect::default_keyword_for_insert::DoesNotSupportDefaultKeyword;
@@ -68,16 +68,16 @@ impl SqlDialect for Sqlite {
 
     type EmptyFromClauseSyntax = sql_dialect::from_clause_syntax::AnsiSqlFromClauseSyntax;
     type ExistsSyntax = sql_dialect::exists_syntax::AnsiSqlExistsSyntax;
-    type ArrayComparision = sql_dialect::array_comparision::AnsiSqlArrayComparison;
+    type ArrayComparison = sql_dialect::array_comparison::AnsiSqlArrayComparison;
 }
 
 impl DieselReserveSpecialization for Sqlite {}
 impl TrustedBackend for Sqlite {}
 
 #[derive(Debug, Copy, Clone)]
-pub struct SqliteOnConflictClaues;
+pub struct SqliteOnConflictClause;
 
-impl sql_dialect::on_conflict_clause::SupportsOnConflictClause for SqliteOnConflictClaues {}
+impl sql_dialect::on_conflict_clause::SupportsOnConflictClause for SqliteOnConflictClause {}
 
 #[derive(Debug, Copy, Clone)]
 pub struct SqliteBatchInsert;