diesel/
lib.rs

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]
166extern crate bitflags;
167extern crate byteorder;
168#[macro_use]
169extern crate diesel_derives;
170#[doc(hidden)]
171pub use diesel_derives::*;
172
173#[macro_use]
174mod macros;
175
176#[cfg(test)]
177#[macro_use]
178extern crate cfg_if;
179
180#[cfg(test)]
181pub mod test_helpers;
182
183pub mod associations;
184pub mod backend;
185pub mod connection;
186pub mod data_types;
187pub mod deserialize;
188#[macro_use]
189pub mod expression;
190pub mod expression_methods;
191#[doc(hidden)]
192pub mod insertable;
193pub mod query_builder;
194pub mod query_dsl;
195pub mod query_source;
196#[cfg(feature = "r2d2")]
197pub mod r2d2;
198pub mod result;
199pub mod serialize;
200#[macro_use]
201pub mod sql_types;
202pub mod migration;
203pub mod row;
204pub mod types;
205
206#[cfg(feature = "mysql")]
207pub mod mysql;
208#[cfg(feature = "postgres")]
209pub mod pg;
210#[cfg(feature = "sqlite")]
211pub mod sqlite;
212
213mod type_impls;
214mod util;
215
216pub 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
232pub 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
336pub 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
366pub use prelude::*;
367#[doc(inline)]
368pub use query_builder::debug_query;
369#[doc(inline)]
370pub use query_builder::functions::{
371    delete, insert_into, insert_or_ignore_into, replace_into, select, sql_query, update,
372};
373pub use result::Error::NotFound;
374
375pub(crate) mod diesel {
376    pub use super::*;
377}
diesel/lib.rs

diesel/
lib.rs
