Expand description
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
For Diesel 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
andWHERE
). These methods usually have the same name as the SQL they map to, except forWHERE
which is calledfilter
in Diesel (To not conflict with the Rust keyword). These methods live in thequery_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 calledlike
in Diesel). Most operators are named based on the Rust function which maps to that operator instd::ops
(For example==
is called.eq
, and!=
is called.ne
). - “Bare functions” are normal SQL functions
such as
sum
. They live in thedsl
module. Diesel only supports a very small number of these functions. You can declare additional functions you want to use with thesql_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.
Getting help
If you run into problems, Diesel has a very active Gitter room. You can come ask for help at gitter.im/diesel-rs/diesel
Re-exports
Modules
Traits related to relationships between multiple tables.
Types which represent various database backends
Types related to database connections
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.
Types and traits related to deserializing values from the database
Includes various helper types and bare functions which are named too generically to be included in prelude, but are often used when using Diesel.
AST types representing various typed SQL expressions.
Adds various methods to construct new expressions. These traits are exported by default, and implemented automatically.
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.
Representation of migrations
Re-exports important traits and types. Meant to be glob imported when using Diesel.
Contains traits responsible for the actual construction of SQL statements
Traits that construct SELECT statements
Types related to describing schema, and interactions between tables.
Connection pooling via r2d2.
Errors, type aliases, and functions related to working with Result
.
Contains the Row
trait
Types and traits related to serializing values for the database
Types which represent a SQL data type.
Macros
Allow two or more tables which are otherwise unrelated to be used together in a query.
Useful for libraries adding support for new SQL types. Apps should never need to call this.
Useful for libraries adding support for new SQL types. Apps should never need to call this.
Useful for libraries adding support for new SQL types. Apps should never need to call this.
Provides a standard implementation of QueryId
.
Apps should not need to concern themselves with this macro.
Allow two tables to be referenced in a join query without providing an
explicit ON
clause.
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:
Gets the value out of an option, or returns an error.
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.
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.
Declare a sql function for use in your code.
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.
Functions
Takes a query QueryFragment
expression as an argument and returns a type
that implements fmt::Display
and fmt::Debug
to show the query.
Creates a DELETE
statement.
Creates an INSERT
statement for the target table.
Creates an INSERT [OR] IGNORE
statement.
Creates a REPLACE
statement.
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.
Construct a full SQL query using raw SQL.
Creates an UPDATE
statement.