1 //! # Diesel 2 //! 3 //! Diesel is an ORM and query builder designed to reduce the boilerplate for database interactions. 4 //! If this is your first time reading this documentation, 5 //! we recommend you start with the [getting started guide]. 6 //! We also have [many other long form guides]. 7 //! 8 //! [getting started guide]: https://diesel.rs/guides/getting-started/ 9 //! [many other long form guides]: https://diesel.rs/guides 10 //! 11 //! # Where to find things 12 //! 13 //! ## Declaring your schema 14 //! 15 //! For Diesel to validate your queries at compile time 16 //! it requires you to specify your schema in your code, 17 //! which you can do with [the `table!` macro][`table!`]. 18 //! `diesel print-schema` or `infer_schema!` can be used 19 //! to automatically generate these macro calls 20 //! (by connecting to your database and querying its schema). 21 //! 22 //! [`table!`]: macro.table.html 23 //! 24 //! ## Getting started 25 //! 26 //! Queries usually start from either a table, or a function like [`update`]. 27 //! Those functions can be found [here](#functions). 28 //! 29 //! Diesel provides a [`prelude` module](prelude), 30 //! which exports most of the typically used traits and types. 31 //! We are conservative about what goes in this module, 32 //! and avoid anything which has a generic name. 33 //! Files which use Diesel are expected to have `use diesel::prelude::*;`. 34 //! 35 //! [`update`]: fn.update.html 36 //! 37 //! ## Constructing a query 38 //! 39 //! The tools the query builder gives you can be put into these three categories: 40 //! 41 //! - "Query builder methods" are things that map to portions of a whole query 42 //! (such as `ORDER` and `WHERE`). These methods usually have the same name 43 //! as the SQL they map to, except for `WHERE` which is called `filter` in Diesel 44 //! (To not conflict with the Rust keyword). 45 //! These methods live in [the `query_dsl` module](query_dsl). 46 //! - "Expression methods" are things you would call on columns 47 //! or other individual values. 48 //! These methods live in [the `expression_methods` module](expression_methods) 49 //! You can often find these by thinking "what would this be called" 50 //! if it were a method 51 //! and typing that into the search bar 52 //! (e.g. `LIKE` is called `like` in Diesel). 53 //! Most operators are named based on the Rust function which maps to that 54 //! operator in [`std::ops`][] 55 //! (For example `==` is called `.eq`, and `!=` is called `.ne`). 56 //! - "Bare functions" are normal SQL functions 57 //! such as `sum`. 58 //! They live in [the `dsl` module](dsl). 59 //! Diesel only supports a very small number of these functions. 60 //! You can declare additional functions you want to use 61 //! with [the `sql_function!` macro][`sql_function!`]. 62 //! 63 //! [`std::ops`]: //doc.rust-lang.org/stable/std/ops/index.html 64 //! [`sql_function!`]: macro.sql_function.html 65 //! 66 //! ## Serializing and Deserializing 67 //! 68 //! Types which represent the result of a SQL query implement 69 //! a trait called [`Queryable`]. 70 //! 71 //! Diesel maps "Rust types" (e.g. `i32`) to and from "SQL types" 72 //! (e.g. [`diesel::sql_types::Integer`]). 73 //! You can find all the types supported by Diesel in [the `sql_types` module](sql_types). 74 //! These types are only used to represent a SQL type. 75 //! You should never put them on your `Queryable` structs. 76 //! 77 //! To find all the Rust types which can be used with a given SQL type, 78 //! see the documentation for that SQL type. 79 //! 80 //! To find all the SQL types which can be used with a Rust type, 81 //! go to the docs for either [`ToSql`] or [`FromSql`], 82 //! go to the "Implementors" section, 83 //! and find the Rust type you want to use. 84 //! 85 //! [`Queryable`]: deserialize/trait.Queryable.html 86 //! [`diesel::sql_types::Integer`]: sql_types/struct.Integer.html 87 //! [`ToSql`]: serialize/trait.ToSql.html 88 //! [`FromSql`]: deserialize/trait.FromSql.html 89 //! 90 //! ## Getting help 91 //! 92 //! If you run into problems, Diesel has a very active Gitter room. 93 //! You can come ask for help at 94 //! [gitter.im/diesel-rs/diesel](https://gitter.im/diesel-rs/diesel) 95 96 #![cfg_attr( 97 feature = "large-tables", 98 deprecated( 99 since = "1.2.0", 100 note = "The large-tables feature has been renamed to 32-column-tables" 101 ) 102 )] 103 #![cfg_attr( 104 feature = "huge-tables", 105 deprecated( 106 since = "1.2.0", 107 note = "The huge-tables feature has been renamed to 64-column-tables" 108 ) 109 )] 110 #![cfg_attr( 111 feature = "x32-column-tables", 112 deprecated( 113 since = "1.2.1", 114 note = "The x32-column-tables feature has been reanmed to 32-column-tables. The x was a workaround for a bug in crates.io that has since been resolved" 115 ) 116 )] 117 #![cfg_attr( 118 feature = "x64-column-tables", 119 deprecated( 120 since = "1.2.1", 121 note = "The x64-column-tables feature has been reanmed to 64-column-tables. The x was a workaround for a bug in crates.io that has since been resolved" 122 ) 123 )] 124 #![cfg_attr( 125 feature = "x128-column-tables", 126 deprecated( 127 since = "1.2.1", 128 note = "The x128-column-tables feature has been reanmed to 128-column-tables. The x was a workaround for a bug in crates.io that has since been resolved" 129 ) 130 )] 131 #![cfg_attr(feature = "unstable", feature(specialization, try_from))] 132 // Built-in Lints 133 #![deny( 134 missing_debug_implementations, 135 missing_copy_implementations, 136 missing_docs 137 )] 138 // Clippy lints 139 #![allow( 140 clippy::option_map_unwrap_or_else, 141 clippy::option_map_unwrap_or, 142 clippy::match_same_arms, 143 clippy::type_complexity, 144 clippy::redundant_field_names, 145 // we don't fix that in backports 146 unused_parens 147 )] 148 #![cfg_attr(test, allow(clippy::option_map_unwrap_or, clippy::result_unwrap_used))] 149 #![warn( 150 clippy::option_unwrap_used, 151 clippy::result_unwrap_used, 152 clippy::print_stdout, 153 clippy::wrong_pub_self_convention, 154 clippy::mut_mut, 155 clippy::non_ascii_literal, 156 clippy::similar_names, 157 clippy::unicode_not_nfc, 158 clippy::enum_glob_use, 159 clippy::if_not_else, 160 clippy::items_after_statements, 161 clippy::used_underscore_binding 162 )] 163 164 #[cfg(feature = "postgres")] 165 #[macro_use] 166 extern crate bitflags; 167 extern crate byteorder; 168 #[macro_use] 169 extern crate diesel_derives; 170 #[doc(hidden)] 171 pub use diesel_derives::*; 172 173 #[macro_use] 174 mod macros; 175 176 #[cfg(test)] 177 #[macro_use] 178 extern crate cfg_if; 179 180 #[cfg(test)] 181 pub mod test_helpers; 182 183 pub mod associations; 184 pub mod backend; 185 pub mod connection; 186 pub mod data_types; 187 pub mod deserialize; 188 #[macro_use] 189 pub mod expression; 190 pub mod expression_methods; 191 #[doc(hidden)] 192 pub mod insertable; 193 pub mod query_builder; 194 pub mod query_dsl; 195 pub mod query_source; 196 #[cfg(feature = "r2d2")] 197 pub mod r2d2; 198 pub mod result; 199 pub mod serialize; 200 #[macro_use] 201 pub mod sql_types; 202 pub mod migration; 203 pub mod row; 204 pub mod types; 205 206 #[cfg(feature = "mysql")] 207 pub mod mysql; 208 #[cfg(feature = "postgres")] 209 pub mod pg; 210 #[cfg(feature = "sqlite")] 211 pub mod sqlite; 212 213 mod type_impls; 214 mod util; 215 216 pub mod dsl { 217 //! Includes various helper types and bare functions which are named too 218 //! generically to be included in prelude, but are often used when using Diesel. 219 220 #[doc(inline)] 221 pub use helper_types::*; 222 223 #[doc(inline)] 224 pub use expression::dsl::*; 225 226 #[doc(inline)] 227 pub use query_builder::functions::{ 228 delete, insert_into, insert_or_ignore_into, replace_into, select, sql_query, update, 229 }; 230 } 231 232 pub mod helper_types { 233 //! Provide helper types for concisely writing the return type of functions. 234 //! As with iterators, it is unfortunately difficult to return a partially 235 //! constructed query without exposing the exact implementation of the 236 //! function. Without higher kinded types, these various DSLs can't be 237 //! combined into a single trait for boxing purposes. 238 //! 239 //! All types here are in the form `<FirstType as 240 //! DslName<OtherTypes>>::Output`. So the return type of 241 //! `users.filter(first_name.eq("John")).order(last_name.asc()).limit(10)` would 242 //! be `Limit<Order<FindBy<users, first_name, &str>, Asc<last_name>>>` 243 use super::query_builder::locking_clause as lock; 244 use super::query_dsl::methods::*; 245 use super::query_dsl::*; 246 use super::query_source::joins; 247 248 #[doc(inline)] 249 pub use expression::helper_types::*; 250 251 /// Represents the return type of `.select(selection)` 252 pub type Select<Source, Selection> = <Source as SelectDsl<Selection>>::Output; 253 254 /// Represents the return type of `.filter(predicate)` 255 pub type Filter<Source, Predicate> = <Source as FilterDsl<Predicate>>::Output; 256 257 /// Represents the return type of `.filter(lhs.eq(rhs))` 258 pub type FindBy<Source, Column, Value> = Filter<Source, Eq<Column, Value>>; 259 260 /// Represents the return type of `.for_update()` 261 #[cfg(feature = "with-deprecated")] 262 #[allow(deprecated)] 263 pub type ForUpdate<Source> = <Source as ForUpdateDsl>::Output; 264 265 /// Represents the return type of `.for_update()` 266 #[cfg(not(feature = "with-deprecated"))] 267 pub type ForUpdate<Source> = <Source as LockingDsl<lock::ForUpdate>>::Output; 268 269 /// Represents the return type of `.for_no_key_update()` 270 pub type ForNoKeyUpdate<Source> = <Source as LockingDsl<lock::ForNoKeyUpdate>>::Output; 271 272 /// Represents the return type of `.for_share()` 273 pub type ForShare<Source> = <Source as LockingDsl<lock::ForShare>>::Output; 274 275 /// Represents the return type of `.for_key_share()` 276 pub type ForKeyShare<Source> = <Source as LockingDsl<lock::ForKeyShare>>::Output; 277 278 /// Represents the return type of `.skip_locked()` 279 pub type SkipLocked<Source> = <Source as ModifyLockDsl<lock::SkipLocked>>::Output; 280 281 /// Represents the return type of `.no_wait()` 282 pub type NoWait<Source> = <Source as ModifyLockDsl<lock::NoWait>>::Output; 283 284 /// Represents the return type of `.find(pk)` 285 pub type Find<Source, PK> = <Source as FindDsl<PK>>::Output; 286 287 /// Represents the return type of `.or_filter(predicate)` 288 pub type OrFilter<Source, Predicate> = <Source as OrFilterDsl<Predicate>>::Output; 289 290 /// Represents the return type of `.order(ordering)` 291 pub type Order<Source, Ordering> = <Source as OrderDsl<Ordering>>::Output; 292 293 /// Represents the return type of `.then_order_by(ordering)` 294 pub type ThenOrderBy<Source, Ordering> = <Source as ThenOrderDsl<Ordering>>::Output; 295 296 /// Represents the return type of `.limit()` 297 pub type Limit<Source> = <Source as LimitDsl>::Output; 298 299 /// Represents the return type of `.offset()` 300 pub type Offset<Source> = <Source as OffsetDsl>::Output; 301 302 /// Represents the return type of `.inner_join(rhs)` 303 pub type InnerJoin<Source, Rhs> = 304 <Source as JoinWithImplicitOnClause<Rhs, joins::Inner>>::Output; 305 306 /// Represents the return type of `.left_join(rhs)` 307 pub type LeftJoin<Source, Rhs> = 308 <Source as JoinWithImplicitOnClause<Rhs, joins::LeftOuter>>::Output; 309 310 use super::associations::HasTable; 311 use super::query_builder::{AsChangeset, IntoUpdateTarget, UpdateStatement}; 312 /// Represents the return type of `update(lhs).set(rhs)` 313 pub type Update<Target, Changes> = UpdateStatement< 314 <Target as HasTable>::Table, 315 <Target as IntoUpdateTarget>::WhereClause, 316 <Changes as AsChangeset>::Changeset, 317 >; 318 319 /// Represents the return type of `.into_boxed::<'a, DB>()` 320 pub type IntoBoxed<'a, Source, DB> = <Source as BoxedDsl<'a, DB>>::Output; 321 322 /// Represents the return type of `.distinct()` 323 pub type Distinct<Source> = <Source as DistinctDsl>::Output; 324 325 /// Represents the return type of `.distinct_on(expr)` 326 #[cfg(feature = "postgres")] 327 pub type DistinctOn<Source, Expr> = <Source as DistinctOnDsl<Expr>>::Output; 328 329 /// Represents the return type of `.single_value()` 330 pub type SingleValue<Source> = <Source as SingleValueDsl>::Output; 331 332 /// Represents the return type of `.nullable()` 333 pub type NullableSelect<Source> = <Source as SelectNullableDsl>::Output; 334 } 335 336 pub mod prelude { 337 //! Re-exports important traits and types. Meant to be glob imported when using Diesel. 338 pub use associations::{GroupedBy, Identifiable}; 339 pub use connection::Connection; 340 #[deprecated( 341 since = "1.1.0", 342 note = "Explicitly `use diesel::deserialize::Queryable" 343 )] 344 pub use deserialize::Queryable; 345 pub use expression::{ 346 AppearsOnTable, BoxableExpression, Expression, IntoSql, SelectableExpression, 347 }; 348 pub use expression_methods::*; 349 #[doc(inline)] 350 pub use insertable::Insertable; 351 #[doc(hidden)] 352 pub use query_dsl::GroupByDsl; 353 pub use query_dsl::{BelongingToDsl, JoinOnDsl, QueryDsl, RunQueryDsl, SaveChangesDsl}; 354 355 pub use query_source::{Column, JoinTo, QuerySource, Table}; 356 pub use result::{ConnectionError, ConnectionResult, OptionalExtension, QueryResult}; 357 358 #[cfg(feature = "mysql")] 359 pub use mysql::MysqlConnection; 360 #[cfg(feature = "postgres")] 361 pub use pg::PgConnection; 362 #[cfg(feature = "sqlite")] 363 pub use sqlite::SqliteConnection; 364 } 365 366 pub use prelude::*; 367 #[doc(inline)] 368 pub use query_builder::debug_query; 369 #[doc(inline)] 370 pub use query_builder::functions::{ 371 delete, insert_into, insert_or_ignore_into, replace_into, select, sql_query, update, 372 }; 373 pub use result::Error::NotFound; 374 375 pub(crate) mod diesel { 376 pub use super::*; 377 } 378