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.
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
diesel print-schema can be used
to automatically generate these macro calls
(by connecting to your database and querying its schema).
Diesel provides a
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
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
WHERE). These methods usually have the same name as the SQL they map to, except for
WHEREwhich is called
filterin Diesel (To not conflict with the Rust keyword). These methods live in the
- “Expression methods” are things you would call on columns
or other individual values.
These methods live in the
expression_methodsmodule 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.
likein Diesel). Most operators are named based on the Rust function which maps to that operator in
- “Bare functions” are normal SQL functions
sum. They live in the
dslmodule. Diesel only supports a very small number of these functions. You can declare additional functions you want to use with the
Types which represent the result of a SQL query implement
a trait called
Diesel maps “Rust types” (e.g.
i32) to and from “SQL types”
You can find all the types supported by Diesel in the
These types are only used to represent a SQL type.
You should never put them on your
To find all the Rust types which can be used with a given SQL type, see the documentation for that SQL type.
The following feature flags are considered to be part of diesels public API. Any feature flag that is not listed here is not considered to be part of the public API and can disappear at any point in time:
sqlite: This feature enables the diesel sqlite backend. Enabling this feature requires a compatible copy of
libsqlite3for your target architecture.
postgres: This feature enables the diesel postgres backend. Enabling this feature requires a compatible copy of
libpqfor your target architecture. This features implies
mysql: This feature enables the idesel mysql backend. Enabling this feature requires a compatible copy of
libmysqlclientfor your target architecture. This feature implies
postgres_backend: This feature enables those parts of diesels postgres backend, that are not dependend on
libpq. Diesel does not provide any connection implementation with only this feature enabled. This feature can be used to implement a custom implementation of diesels
Connectiontrait for the postgres backend outside of diesel itself, while reusing the existing query dsl extensions for the postgres backend
mysql_backend: This feature enables those parts of diesels mysql backend, that are not dependend on
libmysqlclient. Diesel does not provide any connection implementation with only this feature enabled. This feature can be used to implement a custom implementation of diesels
Connectiontrait for the mysql backend outside of diesel itself, while reusing the existing query dsl extensions for the mysql backend
returning_clauses_for_sqlite_3_35: This feature enables support for
RETURNINGclauses in the sqlite backend. Enabling this feature requires sqlite 3.35.0 or newer.
32-column-tables: This feature enables support for tables with up to 32 columns. This feature is enabled by default. Consider disabling this feature if you write a library crate providing general extensions for diesel or if you do not need to support tables with more than 16 columns and you want to minimize your compile times.
64-column-tables: This feature enables support for tables with up to 64 columns. It implies the
32-column-tablesfeature. Enabling this feature will increase your compile times.
128-column-tables: This feature enables support for tables with up to 128 columns. It implies the
64-column-tablesfeature. Enabling this feature will increase your compile times significantly.
i-implement-a-third-party-backend-and-opt-into-breaking-changes: This feature opens up some otherwise private API, that can be useful to implement a third party
Backendor write a custom
Connectionimplementation. Do not use this feature for any other usecase. By enabling this feature you explicitly opt out diesel stability guarantees. We explicitly reserve us the right to break API’s exported under this feature flag in any upcoming minor version release. If you publish a crate depending on this feature flag consider to restrict the supported diesel version to the currently released minor version.
serde_json: This feature flag enables support for (de)serializing json values from the database using types provided by
chrono: This feature flags enables support for (de)serializing date/time values from the database using types provided by
uuid: This feature flag enables support for (de)serializing uuid values from the database using types provided by
network-address: This feature flag enables support for (de)serializing IP values from the database using types provided by
ipnet-address: This feature flag enables support for (de)serializing IP values from the database using types provided by
numeric: This feature flag enables support for (de)serializing numeric values from the database using types provided by
r2d2: This feature flag enables support for the
r2d2connection pool implementation.
extras: This feature enables the feature flaged support for any third party crate. This implies the following feature flags:
with-deprecated: This feature enables items marked as
#[deprecated]. It is enabled by default. disabling this feature explicitly opts out diesels stability guarantee.
without-deprecated: This feature disables any item marked as
#[deprecated]. Enabling this feature explicitly opts out the stability guarantee given by diesel. This feature overrides the
with-deprecated. Note that this may also remove items that are not shown as
#[deprecated]in our documentation, due to various bugs in rustdoc. It can be used to check if you depend on any such hidden
nightly-error-messages: This feature enables the generation of improved compiler error messages for common mistakes using diesel. This feature requires a nightly rust compiler and is considered to be unstable. We might remove it in future diesel versions without replacement or deprecation.
By default the following features are enabled:
nowfor example output.
nowwas generated using:
Addfor types which implement
Expression, under its orphan rules.
Addand other traits from
std::ops, under its orphan rules.
table, and a unit struct with the names of each of the columns.
QueryFragmentexpression as an argument and returns a type that implements
fmt::Debugto show the query.
INSERTstatement for the target table.
INSERT [OR] IGNOREstatement.