Crate diesel[−][src]

Diesel

Diesel is an ORM and query builder designed to reduce the boilerplate for database interactions. If this is your first time reading this documentation, we recommend you start with the getting started guide. We also have many other long form guides.

Where to find things

Declaring your schema

So Diesel is able to validate your queries at compile time, it requires you to specify your schema in your code, which you can do with the table! macro. diesel print-schema or infer_schema! can be used to automatically generate these macro calls (by connecting to your database and querying its schema).

Getting started

Queries usually start from either a table, or a function like update. Those functions can be found here.

Diesel provides a prelude module, which exports most of the typically used traits and types. We are conservative about what goes in this module, and avoid anything which has a generic name. Files which use Diesel are expected to have use diesel::prelude::*;.

Constructing a query

The tools the query builder gives you can be put into these three categories:

"Query builder methods" are things that map to portions of a whole query (such as ORDER and WHERE). These methods usually have the same name as the SQL they map to, except for WHERE which is called filter in Diesel (To not conflict with the Rust keyword). These methods live in the query_dsl module.
"Expression methods" are things you would call on columns or other individual values. These methods live in the expression_methods module You can often find these by thinking "what would this be called" if it were a method and typing that into the search bar (e.g. LIKE is called like in Diesel). Most operators are named based on the Rust function which maps to that operator in std::ops (For example == is called .eq, and != is called .ne).
"Bare functions" are normal SQL functions such as sum. They live in the dsl module. Diesel only supports a very small number of these functions. You can declare additional functions you want to use with the sql_function! macro.

Serializing and Deserializing

Types which represent the result of a SQL query implement a trait called Queryable.

Diesel maps "Rust types" (e.g. i32) to and from "SQL types" (e.g. diesel::sql_types::Integer). You can find all the types supported by Diesel in the sql_types module. These types are only used to represent a SQL type. You should never put them on your Queryable structs.

To find all the Rust types which can be used with a given SQL type, see the documentation for that SQL type.

To find all the SQL types which can be used with a Rust type, go to the docs for either ToSql or FromSql, go to the "Implementors" section, and find the Rust type you want to use.

associations	Traits related to relationships between multiple tables.
backend	Types which represent various database backends
connection	Types related to database connections
data_types	Structs to represent the primitive equivalent of SQL types where there is no existing Rust primitive, or where using it would be confusing (such as date and time types). This module will re-export all backend specific data structures when compiled against that backend.
deserialize	Types and traits related to deserializing values from the database
dsl	Includes various helper types and bare functions which are named too generically to be included in prelude, but are often used when using Diesel.
expression	AST types representing various typed SQL expressions.
expression_methods	Adds various methods to construct new expressions. These traits are exported by default, and implemented automatically.
helper_types	Provide helper types for concisely writing the return type of functions. As with iterators, it is unfortunately difficult to return a partially constructed query without exposing the exact implementation of the function. Without higher kinded types, these various DSLs can't be combined into a single trait for boxing purposes.
migration	Representation of migrations
mysql	Provides types and functions related to working with MySQL
pg	Provides types and functions related to working with PostgreSQL
prelude	Re-exports important traits and types. Meant to be glob imported when using Diesel.
query_builder	Contains traits responsible for the actual construction of SQL statements
query_dsl	Traits that construct SELECT statements
query_source	Types related to describing schema, and interactions between tables.
r2d2	Connection pooling via r2d2
result	Errors, type aliases, and functions related to working with `Result`.
row	Contains the `Row` trait
serialize	Types and traits related to serializing values for the database
sql_types	Types which represent a SQL data type.
sqlite	Provides types and functions related to working with SQLite
types	[ Deprecated ]

Macros

__diesel_for_each_tuple
allow_tables_to_appear_in_same_query	Allow two or more tables which are otherwise unrelated to be used together in a query.
diesel_infix_operator	Useful for libraries adding support for new SQL types. Apps should never need to call this.
diesel_postfix_operator	Useful for libraries adding support for new SQL types. Apps should never need to call this.
diesel_prefix_operator	Useful for libraries adding support for new SQL types. Apps should never need to call this.
impl_query_id	[ Deprecated ] Provides a standard implementation of `QueryId`. Apps should not need to concern themselves with this macro.
joinable	Allow two tables to be referenced in a join query without providing an explicit `ON` clause.
no_arg_sql_function	Declare a 0 argument SQL function for use in your code. This will generate a unit struct, which is an expression representing calling this function. See `now` for example output. `now` was generated using:
not_none	Gets the value out of an option, or returns an error.
numeric_expr	Indicates that an expression allows all numeric operators. If you create new SQL functions that return a numeric type, you should invoke this macro that type. Unfortunately, Rust disallows us from automatically implementing `Add` for types which implement `Expression`, under its orphan rules.
operator_allowed	Implements the Rust operator for a given type. If you create a new SQL function, which returns a type that you'd like to use an operator on, you should invoke this macro. Unfortunately, Rust disallows us from automatically implementing `Add` and other traits from `std::ops`, under its orphan rules.
sql_function	Declare a sql function for use in your code.
table	Specifies that a table exists, and what columns it has. This will create a new public module, with the same name, as the name of the table. In this module, you'll find a unit struct named `table`, and a unit struct with the names of each of the columns. In the definition, you can also specify an additional set of columns which exist, but should not be selected by default (for example, for things like full text search)

Functions

debug_query	Takes a query `QueryFragment` expression as an argument and returns a type that implements `fmt::Display` and `fmt::Debug` to show the query.
delete	Creates a `DELETE` statement.
insert_into	Creates an `INSERT` statement for the target table.
insert_or_ignore_into	Creates an `INSERT [OR] IGNORE` statement.
replace_into	Creates a `REPLACE` statement.
select	Creates a bare select statement, with no from clause. Primarily used for testing diesel itself, but likely useful for third party crates as well. The given expressions must be selectable from anywhere.
sql_query	Construct a full SQL query using raw SQL.
update	Creates an `UPDATE` statement.