NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #2038 most downloaded on crates.io
Codegeneration macros for diesels embedded migrations
Latest stable
2.3.1
Last release 1 months ago
07 Oct 2026
Release timing varies
gaps range from 5 weeks to 2.1 years
Nearly every release is documented
notes for 14 of 15 stable releases
Nothing withdrawn
no release was ever pulled
9 years old
19 releases · first in 2017
Drag across the ruler to compare, or tap a release to open it.
This version did not contain any changes, but only a version bump to retrigger the docs.rs build
This version did not contain any changes, but only a version bump to retrigger the docs.rs build
This release includes a several large extensions to the query DSL provided by Diesel and also helps increases the number of platforms you can use Dies
This release includes a several large extensions to the query DSL provided by Diesel and also helps increases the number of platforms you can use Diesel on out of the box. Notable changes include:
#[derive(HasQuery)]JSON and JSONB in the SQLite backendSee the release blog for the full announcement
You can support the development of Diesel by:
limit() and offset() DSL to combination clauses such as UNION#[derive(Identifiable)] ignoring attribute #[diesel(serialize_as)] on primary keysAsChangeset via #[diesel(embed)]#[diesel(skip_update)] attribute for the AsChangeset derive to skip updating a field present in the structdiesel::r2d2::TestCustomizer, which allows users to customize their diesel::r2d2::Pools
in a way that makes the pools suitable for use in parallel tests.Json and Jsonb support for the SQLite backend.#[diesel::declare_sql_function] attribute macro to easily define support for
multiple sql functions at once via an extern "SQL" block[print_schema] allow_tables_to_appear_in_same_query_config = "fk_related_tables" to generate separate allow_tables_to_appear_in_same_query! calls containing only tables that are related through foreign keys. (Default: "all_tables".) It is not possible to build queries using two tables that don't appear in the same allow_tables_to_appear_in_same_query! call, but that macro generates O(n²) rust code, so this option may be useful to reduce compilation time. (#4333)wasm32-unknown-unknown target support for sqlite backend.CAST operator[print_schema] allow_tables_to_appear_in_same_query_config = "none" to generate no allow_tables_to_appear_in_same_query! calls. (Default: "all_tables".). (#4333)[print_schema] pg_domains_as_custom_types parameter to generate custom types for PostgreSQL domains that matches any of the regexes in the given list. (Default: [].) This option allows an application to selectively give special meaning for the serialization/deserialization of these types, avoiding the default behavior of treating the domain as the underlying type. (#4592)a.eq_any(b) was non-nullable even if a and b were nullable.InstrumentationEvent::BeginTransaction for immediate and exclusive transactions in SQLiteDELETE FROM.ipnetwork to allow version 0.21.DIESEL_LOG logging filter env variable instead of the default RUST_LOG one (#4575)Full Changelog: https://github.com/diesel-rs/diesel/compare/v2.2.0...v2.3.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Deprecated sql_function! in favour of define_sql_function! which provides compatibility with #[dsl::auto_type]
This release wouldn't be possible without the support of our contributors and sponsors. If you want to support diesels development, consider joining the reviewer team, submitting PR's, help writing documentation or sponsor the maintainers.
[print_schema] exclude_custom_type_definitions = ["Vector"]. If a custom type matches one element on the list it's skipped.rowid aliases when no explicit primary key is defined for print-schema#[dsl::auto_type] attribute macro, allowing to infer type of query fragment functionsSelectable derives, which allows skipping specifying select_expression_type most of the time, in turn enabling most queries to be written using just a Selectable derive.#[diesel(skip_insertion)] field attribute to the Insertable derive macro, allowing fields which map to generated columns to be skipped during insertion.sqlite-integer-primary-key-is-bigint configuration option, usable with SQLite 3.37 or above, allowing to use BigInt for INTEGER PRIMARY KEY columns in SQLite for tables without the WITHOUT ROWID attribute (SQLite doc).print_schema entry in diesel.toml (e.g. [print_schema.user1]), which allows generating multiple schema.rs filesCOPY TO and COPY FROM statementschrono::Duration to postgresql's INTERVAL sql typeserialize_database_to_buffer and deserialize_readonly_database_from_buffer methods in SqliteConnection to support serialization/deserialization of SQLite databases to and from byte buffers.SerializedDatabase wrapper type for a serialized database that is dynamically allocated by calling serialize_database_to_buffer. This RAII wrapper deallocates the memory when it goes out of scope with sqlite3_free.sql_function! in favour of define_sql_function! which provides compatibility with #[dsl::auto_type]Full Changelog: https://github.com/diesel-rs/diesel/compare/v2.1.0...v2.2.0
Diesel 2.1.0 contains the contributions of 42 people. More than 380 commits were submitted over a span of 9 months.
Diesel 2.1.0 contains the contributions of 42 people. More than 380 commits were submitted over a span of 9 months.
This release contains several new features and improves existing features. It introduces support for generating migrations based on the diff between your schema.rs file and your database via Diesel CLI. Diesel derives now provides a #[derive(MultiConnection)] derive macro that allows to easily combine different database connections into a single enum, which implements Connection on its own. The MySQL backend gets support for upsert queries via the ON DUPLICATE KEYS syntax. Finally we provide new tooling to improve complex error messages generated for common error cases. Check out our changelog for a complete list of changes.
This release wouldn't be possible without the support of our contributors and sponsors. If you want to support diesels development, consider joining the reviewer team, submitting PR's, help writing documentation or sponsor the maintainers.
Diesel CLI now includes support for generating migrations based on the difference of your schema.rs file and your local database.
This works as following:
schema.rs file, for example by adding your first table:diesel::table! {
users {
id -> Integer,
name -> Text,
}
}
diesel migration generate my_first_migration --diff-schema --database-url DATABASE_URL-- Your SQL goes here
CREATE TABLE `users`(
`id` INTEGER NOT NULL PRIMARY KEY,
`name` TEXT NOT NULL
);
diesel migration run --database-url DATABASE_URLIt's important to note that the generated migrations can only contain information that are part of the schema.rs file. This explicitly excludes default value, custom check constraints and similar SQL features. We expect the generated migrations to be a good starting point for writing the actual migration you need, we do not expect them to include all necessary information in all cases or to provide the perfect solution in each scenario.
MultiConnection supportDiesel now includes a #[derive(MultiConnection)] proc macro derive, which allows to easily support more than one database backend in a single application. It can be applied to an enum of different connections:
#[derive(diesel::MultiConnection)]
pub enum AnyConnection {
Postgresql(diesel::PgConnection),
Mysql(diesel::MysqlConnection),
Sqlite(diesel::SqliteConnection),
}
Afterwards the AnyConnection type can be used as ordinary connection:
fn use_multi(conn: &mut AnyConnection) -> QueryResult<()> {
// Use the connection enum as any other connection type
// for inserting/updating/loading/…
diesel::insert_into(users::table)
.values(users::name.eq("Sean"))
.execute(conn)?;
let users = users::table.load::<(i32, String)>(conn)?;
Ok(())
}
By default this connection type will only support a subset of SQL that's supported by all inner connection types. By being an enum it's easy to fallback to backend specific SQL as soon as required. We provide this feature as derive macro so that it is possible to:
MultiConnectionHelper trait in addition to the existing Connection trait.Diesel 2.1 adds support for INSERT INTO … ON DUPLICATE KEYS … queries for the MySQL backend using the existing upsert framework. It's now possible to write such queries using the diesel provided DSL:
diesel::insert_into(users)
.values(&user2)
.on_conflict(diesel::dsl::DuplicatedKeys)
.do_update()
.set(name.eq("I DONT KNOW ANYMORE"))
.execute(conn)?;
We spend some effort to improve error messages generated by rustc for common diesel issues further.
Consider the following example:
table! {
users {
id -> Integer,
name -> Text,
}
}
#[derive(Queryable)]
struct User {
name: String,
id: i32,
}
users::table.load::<User>(&mut conn)
which would generate the following error message:
error[E0277]: the trait bound `(diesel::sql_types::Integer, diesel::sql_types::Text): load_dsl::private::CompatibleType<User, Mysql>` is not satisfied
--> src/main.rs:20:31
|
20 | users::table.load::<User>(&mut conn);
| ---- ^^^^^^^^^ the trait `load_dsl::private::CompatibleType<User, Mysql>` is not implemented for `(diesel::sql_types::Integer, diesel::sql_types::Text)`
| |
| required by a bound introduced by this call
|
= help: the following other types implement trait `load_dsl::private::CompatibleType<U, DB>`:
(ST0, ST1)
(ST0, ST1, ST2)
(ST0, ST1, ST2, ST3)
(ST0, ST1, ST2, ST3, ST4)
(ST0, ST1, ST2, ST3, ST4, ST5)
(ST0, ST1, ST2, ST3, ST4, ST5, ST6)
(ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7)
(ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8)
and 24 others
= note: required for `users::table` to implement `LoadQuery<'_, _, User>`
note: required by a bound in `diesel::RunQueryDsl::load`
--> /home/weiznich/.cargo/git/checkouts/diesel-6e3331fb3b9331ec/ef6252e/diesel/src/query_dsl/mod.rs:1543:15
|
1543 | Self: LoadQuery<'query, Conn, U>,
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `diesel::RunQueryDsl::load`
This is caused by an field order mismatch between what your query returns and what your struct expects the query to return.
With diesel 2.0 we introduced the Selectable trait and a corresponding derive. That allows to automatically generate a matching select clause to prevent such issues from happening. While this already solved parts of the problem it does not solve the following case:
#[derive(Queryable, Selectable)]
struct User {
name: i32,
id: i32,
}
users::table.select(User::as_select()).load(&mut conn);
which generates the following error message:
error[E0277]: the trait bound `expression::select_by::SelectBy<User, _>: load_dsl::private::CompatibleType<_, _>` is not satisfied
--> src/main.rs:20:49
|
20 | users::table.select(User::as_select()).load(&mut conn);
| ---- ^^^^^^^^^ the trait `load_dsl::private::CompatibleType<_, _>` is not implemented for `expression::select_by::SelectBy<User, _>`
| |
| required by a bound introduced by this call
|
= help: the trait `load_dsl::private::CompatibleType<U, DB>` is implemented for `expression::select_by::SelectBy<U, DB>`
= note: required for `SelectStatement<FromClause<users::table>, query_builder::select_clause::SelectClause<expression::select_by::SelectBy<User, _>>>` to implement `LoadQuery<'_, _, _>`
note: required by a bound in `diesel::RunQueryDsl::load`
--> /home/weiznich/.cargo/git/checkouts/diesel-6e3331fb3b9331ec/ef6252e/diesel/src/query_dsl/mod.rs:1543:15
|
1543 | Self: LoadQuery<'query, Conn, U>,
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `diesel::RunQueryDsl::load`
This is caused by a type mismatch in the name field. With diesel 2.1 we now introduce an additional #[diesel(check_for_backend(diesel::backend::BackendType))] attribute that greatly improves the error messages generated for these cases. This helps pining down which field exactly causes a type mismatch.
By applying this attribute to our example:
#[derive(Queryable, Selectable)]
#[diesel(check_for_backend(diesel::mysql::Mysql))]
struct User {
name: i32,
id: i32,
}
we get the following error message:
error[E0277]: the trait bound `i32: FromSql<diesel::sql_types::Text, Mysql>` is not satisfied
--> src/main.rs:13:11
|
13 | name: i32,
| ^^^ the trait `FromSql<diesel::sql_types::Text, Mysql>` is not implemented for `i32`
|
= help: the trait `FromSql<diesel::sql_types::Integer, Mysql>` is implemented for `i32`
= note: required for `i32` to implement `diesel::Queryable<diesel::sql_types::Text, Mysql>`
= note: required for `i32` to implement `FromSqlRow<diesel::sql_types::Text, Mysql>`
= help: see issue #48214
This error message now points to the exact cause of the issue: You cannot deserialize an Text value into a i32 field. This attribute accepts one or more diesel backend type to check the struct definition against. It requires that the struct is using either both, #[derive(Queryable)] and #[derive(Selectable)] or #[derive(QueryableByName)].
Changes listed here are relevant for crates using the i-implement-a-third-party-backend-and-opt-into-breaking-changes feature flag.
With Diesel 2.1 we have migrated some traits to use GAT. This affects the following traits:
RowGatWorkaroundConnectionGatWorkaroundHasRawValueHasBindCollectorThese traits are removed in favour of generic associated types on the corresponding child trait.
Additionally we slightly relaxed one trait bound on BindCollector::push_bound_value to allow unsized values there as well.
Thank you to everyone who helped make this release happen through sponsoring, bug reports, and discussion on GitHub and Gitter. While we don't have a way to collect stats on that form of contribution, it's greatly appreciated.
In addition to the Diesel core team, 42 people contributed code to this release. A huge thank you to:
custom_type_derives config option to customize the derives for SQL
type definitions automatically generated by Diesel CLI.#[derive(MultiConnection)] proc-macro that lets you easily implement diesel::Connection
for an enum of connections to different database backends.--diff-schema flag to the diesel migration generate command that generates a migration based
on the difference between your database and the provided schema.rs fileON CONFLICT (...) DO UPDATE ... [WHERE ...] conditional clause support for PostgreSQL.ON DUPLICATE KEY DO UPDATE syntax through the existing upsert functions.distinct_on for PostgreSQL,
like: .distinct_on((column_a, column_b)).schema.rs fileCheck out our changelog for a complete list of changes. As this is a new major Diesel release it contains a number of breaking changes. Checkout our m…
Diesel 2.0.0 contains the contributions of more than 130 people. More than 1700 commits were submitted over a span of 3 years.
As part of this release we introduced numerous new features and rewrote large parts of the internal structure. Check out our changelog for a complete list of changes. As this is a new major Diesel release it contains a number of breaking changes. Checkout our migration guide for details about how to handle those breaking changes.
This release contains the following parts:
This release marks a first prerelease of the upcoming Diesel 2.0 release. We ask you for your help to finalise the release. Checkout the "Timeline for a Diesel 2.0 release" section for details about how you can help us finishing the release.
As a highlight Diesel 2.0.0 adds support for the following features:
GROUP BY supportUNION/INTERSECT queriesGROUP BY clausesDiesel 2.0 adds support for GROUP BY clauses for select queries.
This means queries like the following one will just work.
users::table.inner_join(posts::table)
.group_by(users::id)
.select((users::name, count(posts::id)))
As this is the case for all other Diesel built-in query dsl, this construct is fully checked at compile time. This means Diesel
will ensure that the GROUP BY clause is valid for the current query and it will also ensure that expressions appearing inside
of your SELECT clause will match the aggregation rules provided by the current GROUP BY clause.
Diesel 2.0 adds support for table aliasing. This enables users to write queries, where a table appears more than once in the corresponding
FROM clause. For this Diesel provides a Diesel::alias! macro that allows to define new alias for existing tables.
The following query demonstrates the support for this feature:
// Define new table alias for the existing `users` table
let users1 = diesel::alias!(schema::users as user1);
// Use the corresponding alias inside any existing query
users::table
.inner_join(users1.on(users::id).eq(users1.field(users::id))))
.select((users::id, users::name, users1.field(users::name)))
.order_by(users1.field(users::id))
Again all of this is checked at compile time. So similar to a normal table, columns from aliases are only allowed to appear if the corresponding query actually uses the alias.
Selectable traitDiesel 2.0 features a new Selectable trait and derive that lets users declare that a type expects a certain kind of select clause.
The major use case for this feature is to ensure that columns from a specific query are always requested in the right order
for a corresponding type implementing Queryable. This also works for complex queries involving joins or other kinds of nesting.
#[derive(Queryable, Selectable)]
struct User {
id: i32,
name: String,
}
let first_user = users.select(User::as_select()).first(connection)?;
Diesel enforces at type system level that once you provided such a select clause via User::as_select() you are only allowed
to construct this type from the returned result of the corresponding query. This means there is no need to specify the User type
twice in the query above.
UNION/INTERSECT/EXCEPT queriesDiesel 2.0 extents the query builder to support query combinations via UNION/INTERSECT/EXCEPT. This allows you
to easily chain multiple queries together as long as they return fields of the same type. Queries like the following
one are now supported:
users.select(user_name.nullable())
.union(animals.select(animal_name).filter(animal_name.is_not_null()))
As always this is checked at compile time to reject invalid queries, like for example that ones containing select clauses with different fields.
The release of Diesel 2.0 does not only include the features listed above, but also marks the point where the following things can be provided by third party crates:
QueryDsl extensions to support previously unsupported SQL features. Checkout
diesel_full_text_search for an exampleConnection infrastructureConnection implementations for existing backendsConnection
and Backend implementations for previously unsupported backends. Checkout diesel-oci for an example.We encourage our community to try out those features. Especially we would like to see experimentation around:
Please get in touch with us for pointers, help and details.
With the release of Diesel 2.0 the planing for our next releases start. Hopefully they will not take as long as Diesel 2.0. We are looking for input on which features are wanted by our community. Please open a discussion thread with your idea in our discussion forum.
Weiznich will work on improving error messages for trait heavy crates based on a Rust Foundation Project Grant. This work will hopefully improve error messages for Diesel as well. If you are aware of bad error messages please submit a minimal example here.
As part of this release we would like to welcome @Ten0 as part of the diesel core team.
Thank you to everyone who helped make this release happen through bug reports, and discussion on Gitter. While we don't have a way to collect stats on that form of contribution, it's greatly appreciated.
In addition to the Diesel core team, 141 people contributed code to this release. A huge thank you to:
MysqlConnection::establish is able to initiate an SSL connection while specifying certificate roots. The database URL should contain an ssl_ca parameter with a path pointing to the certificate roots. See docs if desired.
MysqlConnection::establish is able to initiate an SSL connection. The database URL should contain ssl_mode parameter with a value of the MySQL client command option --ssl-mode if desired.
Connection and SimpleConnection traits are implemented for a broader range
of r2d2::PooledConnection<M> types when the r2d2 feature is enabled.
Added DatabaseErrorKind::ReadOnlyTransaction to allow applications to
handle errors caused by writing when only allowed to read.
All expression methods can now be called on expressions of nullable types.
Added BoxedSqlQuery. This allows users to do a variable amount of .sql or
.bind calls without changing the underlying type.
Added .sql to SqlQuery and UncheckedBind to allow appending SQL code to
an existing query.
The MacAddr SQL type can now be used without enabling the network-address
feature.
Added support for SQLite's UPSERT.
You can use this feature above SQLite version 3.24.0.
Added ability to create custom aggregate functions in SQLite.
Multiple aggregate expressions can now appear together in the same select clause. See the upgrade notes for details.
ValidGrouping has been added to represent whether an expression is valid for
a given group by clause, and whether or not it's aggregate. It replaces the
functionality of NonAggregate. See the upgrade
notes for details.
It is now possible to inspect the type of values returned from the database in such a way to support constructing a dynamic value depending on this type.
Added a without-deprecated feature that unconditionally disables deprecated items.
Use this feature flag to verify that none of your dependencies is setting
the with-deprecated flag internally.
Added support for PostgreSQL's SIMILAR TO and NOT SIMILAR TO.
Added #[diesel(serialize_as)] analogous to #[diesel(deserialize_as)]. This allows
customization of the serialization behaviour of Insertable and AsChangeset structs.
Added support for GROUP BY clauses
Added support for UNION, UNION ALL, INTERSECT, INTERSECT ALL, EXCEPT, EXCEPT ALL clauses
Added the error position for PostgreSQL errors
Added ability to create custom collation functions in SQLite.
Added support for SQLite's IS and IS NOT.
Add support for HAVING clauses.
Added support for SQL functions without arguments for SQLite.
Diesel CLI will now generate SQL type definitions for SQL types that are not supported by diesel out of the box. It's possible to disable this behavior via the generate_missing_sql_type_definitions config option.
Added an option to #[derive(Insertable)] that let you insert NULL values instead of DEFAULT values for Option<T>
Added support for all the derive attributes being inside #[diesel(...)]
Added support for RETURNING expressions for Sqlite via the returning_clauses_for_sqlite_3_35 feature
Added support for table aliasing via the alias! macro
Added support for the usage of slices of references with belonging_to from BelongingToDsl
Added support for updating individual array elements UPDATE table SET array_column[1] = true
Adds an ipnet-address feature flag, allowing support (de)serializing IP
values from the database using types provided by ipnet. This feature
may be enabled concurrently with the previously existing network-address
feature.
We've added support for loading values using libpq's row-by-row mode via the new iterator interface
Adds Timestamp, Timestamptz support for appropriate types for time v0.3.9.
This feature enables using the time crate as an alternative to chrono.
uuid version < 0.7.0 has been removed.bigdecimal < 0.0.13 has been removed.pq-sys < 0.4.0 has been removed.mysqlclient-sys < 0.2.5 has been removed.time (0.1) types has been removed.chrono < 0.4.19 has been removed.NonNull trait for sql types has been removed in favour of the new SqlType trait.no_arg_sql_function! has been deprecated without replacement.
[sql_function!][sql-function-2-0-0] can now be used for functions with zero
arguments. See the migration guide for more details.barrel based migrations has been removed for now. We are happy to
add this support back as soon as barrel integrates with our new migration framework.diesel bash-completions) has been removed.
Use diesel completions <shell> instead.The minimal officially supported rustc version is now 1.56.0
Interacting with a database requires a mutable connection.
The way the Backend trait handles its RawValue type has
been changed to allow non-references. Users of this type (e.g. code written
&DB::RawValue or &<DB as Backend>::RawValue>) should use
backend::RawValue<DB> instead. Implementors of Backend
should check the relevant section of the migration guide.
The type metadata for MySQL has been changed to include sign information. If
you are implementing HasSqlType for Mysql manually, you may need to adjust
your implementation to fully use the new unsigned variants in MysqlType
The RawValue types for the Mysql and Postgresql backend where changed
from [u8] to distinct opaque types. If you used the concrete RawValue type
somewhere you need to change it to mysql::MysqlValue or pg::PgValue.
The uuidv07 feature was renamed to uuid, due to the removal of support for older uuid versions
Boxed queries (constructed from .into_boxed()) are now Send.
The handling of mixed aggregate values is more robust. Invalid queries such as
.select(max(id) + other_column) are now correctly rejected, and valid
queries such as .select((count_star(), max(other_column))) are now correctly
accepted. For more details, see the migration guide.
NonAggregate is now a trait alias for ValidGrouping<()> for expressions
that are not aggregate. On stable this is a normal trait with a blanket impl,
but it should never be implemented directly. With the unstable feature, it
will use trait aliases which prevent manual implementations.
Due to language limitations, we cannot make the new trait alias by itself represent everything it used to, so in some rare cases code changes may be required. See the migration guide for details.
Various __NonExhaustive variants in different (error-) enums are replaced with
#[non_exhaustive]. If you matched on one of those variants explicitly you need to
introduce a wild card match instead.
FromSql::from_sql is changed to construct value from non nullable database values.
To construct a rust value for nullable values use the new FromSql::from_nullable_sql
method instead.
Custom sql types are now required to implement the new SqlType trait. Diesel will
automatically create implementations of that trait for all types having a #[derive(SqlType)]
The workflow for manually implementing support custom types has changed. Implementing
FromSqlRow<ST, DB> is not required anymore, as this is now implied by implementing
FromSql<ST, DB>. The requirement of implementing Queryable<ST, DB> remains
unchanged. For types using #[derive(FromSqlRow)] no changes are required as the
derive automatically generates the correct code
The structure of our deserialization trait has changed. Loading values from the database
requires now that the result type implements FromSqlRow<ST, DB>. Diesel provides wild
card implementations for types implementing Queryable<ST, DB> or QueryableByName<DB>
so non generic code does not require any change. For generic code you likely need to
replace a trait bound on Queryable<ST, DB> with a trait bound on FromSqlRow<ST, DB>
and a bound to QueryableByName<DB> with FromSqlRow<Untyped, DB>.
CLI flags of only-tables and except-tables are now interpreted as regular expressions.
Similarly, only_tables and except_tables in diesel.toml are treated as regular expressions.
Now you can sort column fields by name with the column-sorting option.
It can be set to either ordinal_position (default) or name.
This ensures stable sorting even if columns are removed and re-added.
The Queryable<ST,DB> trait was updated to be made faillible, in order to properly handle
cases where you detect a data inconsistency between fields on deserialization
(that e.g. was supposed to be made impossible by DB CHECKs). The build function now
returns a
diesel::deserialize::Result<Self>
instead of a Self.
TypeMetadata::MetadataLookup is now ?Sized.
Multiple implementations of Connection<Backend=Pg> are now possible
because of the new PgMetadataLookup trait.
For the Pg backend, TypeMetadata::MetadataLookup has changed to dyn PgMetadataLookup.
Diesel's migration framework was rewritten from the ground. Existing migrations continue to
be compatible with the rewrite, but code calling into diesel_migrations requires an update.
See the migration guide for details.
eq_any() now emits a = ANY() expression for the postgresql backend instead of IN()
ne_all() now emits a != ALL() expression for the postgresql backend instead of NOT IN()
The sqlite backend now uses a single batch insert statement if there are now default values present in the values clause
The MySQL connection is using the CLIENT_FOUND_ROWS from now on. This means that updating rows without changing any values will return the number of matched rows (like most other SQL servers do), as opposed to the number of changed rows.
The definition of ToSql::to_sql and QueryFragment::walk_ast has changed to allow serializing values without
copying the value itself. This is useful for database backends like sqlite where you can directly share a buffer
with the database. Beside of the changed signature, existing impls of this trait should remain unchanged in almost
all cases.
The PIPES_AS_CONCAT sql_mode is no longer set
by default. This setting requires a modification to MySQL query parsing that is
not supported by certain systems (such as Vitess). If you are using MySQL and
executing raw queries with the || operator, you will need to rewrite your
queries or set PIPES_AS_CONCAT manually.
Many types were incorrectly considered non-aggregate when they should not have been. All types in Diesel are now correctly only considered non-aggregate if their parts are.
Offset clauses without limit clauses resulted into invalid sql using the mysql or
sqlite backend. Both do not support such clauses without a preceding limit clause.
For those backend Diesel does now generate a fake limit clause in case no explicit
limit clause was given. As consequence of this change generic query code may
require additional trait bounds as requested from the compiler. Third party
backends are required to explicitly provide QueryFragment impls for
LimitOffsetClause<L, O> now.
Nullability requirements are now properly enforced for nested joins.
Previously, only the rules for the outer-most join were considered. For
example, users.left_join(posts).left_join(comments) would allow selecting
any columns from posts. That will now fail to compile, and any selections
from posts will need to be made explicitly nullable.
Diesel CLI will now look for diesel.toml to determine the project root
before looking for Cargo.toml.
Any relative paths in diesel.toml will now be treated as relative to the
project root (the directory containing either diesel.toml or Cargo.toml).
They are no longer dependent on the current working directory (for all
directories in the same project)
The SQLite backend is now configured to interpret URIs. See the SQLite URI documentation for additional details.
We've refactored our type translation layer for Mysql to handle more types now.
We've refactored our type level representation of nullable values. This allowed us to fix multiple long standing bugs regarding the correct handling of nullable values in some corner cases (#104, #2274)
Parenthesis are now inserted around all infix operations provided by diesel's ExpressionMethods traits
Queries containing a distinct on clause check now on compile time that a compatible order clause was set.
Implementations of custom SQLite SQL functions now check for panics
diesel print-schema now generates Array<Nullable<ST>> rather than Array<ST> for Postgres Array types. Existence of
NULL values in database arrays would previously result in deserialization errors. Non-nullable arrays are now opt
in (by schema patching).
All the diesel derive attributes that are not inside #[diesel(...)]
diesel_(prefix|postfix|infix)_operator! have been deprecated. These macros
are now available without the diesel_ prefix. With Rust 2018 they can be
invoked as diesel::infix_operator! instead.
diesel::pg::upsert has been deprecated to support upsert queries on more than one backend.
Please use diesel::upsert instead.
diesel::dsl::any and diesel::dsl::all are now deprecated in
favour of ExpressionMethods::eq_any() and ExpressionMethods::ne_all()
Nothing published for this version
Nothing published for this version
Parenthesis are now inserted around all mathematical operations. This means that (2.into_sql() + 3) * 4 will correctly evaluate to 20 as expected. Pre
(2.into_sql() + 3) * 4 will correctly evaluate to 20 as expected.
Previously we would generate SQL that evaluated to 14. This could even result
in runtime errors if multiple types were involved (for example, interval * (integer + 1))This release fixes a minor memory safety issue in SQLite. This bug would only occur in an error handling branch that should never occur in practice.
In contrast to the last release most changes in this release are minor or internal. We've added support for newer versions of some dependency crates (
In contrast to the last release most changes in this release are minor or internal. We've added support for newer versions of some dependency crates (libsqlite-sys, uuid, ipnetwork).
Diesel CLI got a command line flag to check if a generated schema matches the already existing one. This is useful for CI setups to check there if the committed generated schema file matches the committed migrations.
We've added support for the diesel_mange_updated_at('table_name') SQL function on SQLite. This function handles the setup of an trigger that automatically updates the updated_at column on update operations.
Additionally several helpers were added to support the deserialisation of tuples and composite types on PostgreSQL.
As always, a full list of changes can be found it in the changelog
Thank you to everyone who helped make this release happen through bug reports, and discussion on Gitter. While we don't have a way to collect stats on that form of contribution, it's greatly appreciated.
In addition to the Diesel core team, 29 people contributed code to this release. A huge thank you to:
embed_migrations! will no longer emit an unused import warninguuidv07Diesel CLI can be configured to error if a command would result in changes
to your schema file by passing --locked-schema. This is intended for use
in CI and production deploys, to ensure that the committed schema file is
up to date.
A helper trait has been added for implementing ToSql for PG composite types.
See WriteTuple for details.
Added support for MySQL's UNSIGNED TINYINT
DatabaseErrorKind::SerializationFailure has been added, corresponding to
SQLSTATE code 40001 (A SERIALIZABLE isolation level transaction failed to
commit due to a read/write dependency on another transaction). This error is
currently only detected on PostgreSQL.
Diesel CLI can now generate completions for zsh and fish. See diesel completions --help for details.
#[belongs_to] can now accept types that are generic over lifetimes (for
example, if one of the fields has the type Cow<'a, str>). To define an
association to such a type, write #[belongs_to(parent = "User<'_>")]
Nullable<Text> now supports ilike expression on in PostgreSQL.
diesel_manage_updated_at('table_name') is now available on SQLite. This
function can be called in your migrations to create a trigger which
automatically sets the updated_at column, unless that column was updated in
the query.
Diesel's derives now require that extern crate diesel; be at your crate root
(e.g. src/lib.rs or src/main.rs)
Tinyint has been renamed to TinyInt and an alias has been created from Tinyint to TinyInt.
The minimal officially supported rustc version is now 1.31.0
Because of this, we are deprecating diesel_infer_schema. 1.3 will be the final release of that crate. However, diesel_infer_schema 1.3 will continue t…
This release includes a couple of major changes to how Diesel projects are developed. In the past, we've had 2 ways to generate schema.rs. A procedural macro called infer_schema!, and a CLI command diesel print-schema. We've recommended using the CLI command for a long time, but infer_schema! was still useful for early prototypes.
At the beginning of a project, your database schema changes much more frequently. It's extremely annoying to have to remember to run a second command after running your migrations.
Diesel CLI 1.3 now supports a configuration file to customize its behavior. One of the new capabilities this provides is the ability to automatically regenerate schema.rs whenever you run or revert a migration. This means you no longer have to remember to run diesel print-schema when things change.
Because of this, we are deprecating diesel_infer_schema. 1.3 will be the final release of that crate. However, diesel_infer_schema 1.3 will continue to work with diesel until at least Diesel 2.0. You can see all of the capabilities of the new configuration file at http://diesel.rs/guides/configuring-diesel-cli.
This release also includes a complete redesign of the sql_function! macro. The new syntax is significantly closer to normal Rust. For example, what used to be written as:
sql_function! {
lower, lower_t, (x: Text) -> Text,
"Here are the docs for `lower`
It's awkward to make multiline"
}
Can now be written as:
sql_function! {
/// Here are the docs for `lower`
/// It's just a normal doc comment.
fn lower(x: Text) -> Text;
}
The new form also supports much more than the old one, including aggregate functions, function renaming, and generic functions. Things like MAX could previously not be expressed with sql_function!. However, now the definition looks like this:
sql_function! {
#[aggregate]
fn max<ST: SqlOrd + IntoNullable>(expr: ST) -> ST::Nullable;
}
Finally, the redesigned sql_function! supports user defined functions on SQLite. SQLite differs from other databases, in that custom functions aren't defined in SQL. Instead you give it a C function pointer to use for the body. With Diesel, you can just give us any Rust closure that takes appropriate argument types, and we'll handle gluing that to SQLite for you.
You can find examples for all of this in the docs for sql_function!.
In addition to the headline features, this release includes a ton of quality of life changes including expanded support for locking clauses, more global support for mathematic operators, and more. As always, for a full list of changes you can find it in [the changelog].
[the changelog]: https://github.com/diesel-rs/diesel/blob/v1.3.0/CHANGELOG.md
Thank you to everyone who helped make this release happen through bug reports, and discussion on Gitter. While we don't have a way to collect stats on that form of contribution, it's greatly appreciated.
In addition to the Diesel core team, 12 people contributed code to this release. A huge thank you to:
Diesel CLI now supports a configuration file. See diesel.rs/guides/configuring-diesel-cli for details.
sql_function! now supports generic functions. See the documentation for
sql_function! for more details.
sql_function! now supports aggregate functions like sum and max, by
annotating them with #[aggregate]. This skips the implementation of
NonAggregate for your function. See the documentation for
sql_function! for more details.
sql_function! now supports renaming the function by annotating it with
#[sql_name = "SOME_FUNCTION"]. This can be used to support functions with
multiple signatures such as coalesce, by defining multiple rust functions
(with different names) that have the same #[sql_name].
Added sqlite-bundled feature to diesel_cli to make installing on
some platforms easier.
Custom SQL functions can now be used with SQLite. See the docs for details.
All functions and operators provided by Diesel can now be used with numeric operators if the SQL type supports it.
PgInterval can now be used with -, *, and /.
Vec<T> is now Insertable. It is no longer required to always place an &
in front of .values.
Added support for PG tuples. See sql_types::Record for details.
FOR SHARE,
SKIP LOCKED, NO WAIT, and more. See QueryDsl for details.sql_function! has been redesigned. The syntax is now sql_function!(fn lower(x: Text) -> Text);. The output of the new syntax is slightly different
than what was generated in the past. See the documentation for
sql_function! for more details.diesel print-schema and infer_schema! now properly handle unsigned types
in MySQLdiesel_infer_schema has been deprecated. diesel print-schema is now the
only way to generate database schema. Diesel CLI can be configured to
automatically regenerate your schema file when migrations are run. See
diesel.rs/guides/configuring-diesel-cli for details.
Uses of sql_function! in the form sql_function!(foo, foo_t, (x: Integer))
have been deprecated in favor of a new design (listed above). Note: Due to a
bug in Rust, you may not see
a deprecation warning from usage of the old form. As always, if you're
concerned about relying on deprecated code, we recommend attempting to build
your app with default-features turned off (specifically excluding the
with-deprecated feature).
The --whitelist and --blacklist options to diesel print-schema have been
deprecated and renamed --only-tables and --exclude-tables.
This release contains several long awaited features.
This release contains several long awaited features.
We've re-introduced the ability to use bind params with the sql function, in a way which is harder to mis-use. This functionality was present prior to 1.0, but was removed when sql_function was added over concerns about its use with the rest of the query builder. Recent developments have proved those concerns to be valid, but this new API fills that niche. Thanks to @notryanb for taking the lead on this feature.
We've also added the ability to insert from a select statement (e.g. queries in the form of INSERT INTO table (...) SELECT .... This is a feature request that has come up repeatedly since release, and we're happy to finally bring it to you. We've also added alternate forms of our insert API which feel better when used with select statements. You can find the full details in the CHANGELOG.
Finally, we've rewritten our custom dervies from scratch to take advantage of new diagnostic tools in recent versions of nightly Rust. If you turn on the unstable feature of Diesel on a nightly compiler, you'll find that you get dramatically improved error messages from our derives. For the best error messages, you should also set RUSTFLAGS="--cfg procmacro2_semver_exempt".
Additionally, as of this release, Diesel is now powered by the blockchain. Because it's 2018 and that's how it works now I guess. See the CHANGELOG for full details.
In addition to the headline features, there were a ton of features that we don't have time to mention here. As always, for a full list of changes you can find a full list in the CHANGELOG.
Thank you to everyone who helped make this release happen through bug reports, and discussion on Gitter. While we don't have a way to collect stats on that form of contribution...
In addition to the Diesel core team, 14 people contributed code to this release. A huge thank you to:
Added SqlLiteral::bind().
This is intended to be used for binding values to small SQL fragments.
Use sql_query if you are writing full queries.
Added support for INSERT INTO table (...) SELECT ... queries. Tables, select
select statements, and boxed select statements can now be used just like any
other Insertable value.
Any insert query written as insert_into(table).values(values) can now be
written as values.insert_into(table). This is particularly useful when
inserting from a select statement, as select statements tend to span multiple
lines.
Diesel's derives can now produce improved error messages if you are using a
nightly compiler, and enable the unstable feature. For the best errors, you
should also set RUSTFLAGS="--cfg procmacro2_semver_exempt".
Added support for specifying ISOLATION LEVEL, DEFERRABLE, and READ ONLY
on PG transactions. See PgConnection::build_transaction for details.
BEGIN IMMEDIATE and BEGIN EXCLUSIVE on SQLite.
See SqliteConnection::immediate_transaction and
SqliteConnection::exclusive_transaction for detailsTables with more than 56 columns are now supported by enabling the
128-column-tables feature.
Delete statements can now be boxed. This is useful for conditionally modifying
the where clause of a delete statement. See DeleteStatement::into_boxed
for details.
UpdateStatement::into_boxed
for details.Added order_by as an alias for order.
Added then_order_by, which appends to an ORDER BY clause rather than
replacing it. This is useful with boxed queries to dynamically construct an
order by clause containing an unknown number of columns.
#[derive(Insertable)] can now work on structs with fields that implement
Insertable (meaning one field can map to more than one column). Add
#[diesel(embed)] to the field to enable this behavior.
Queries that treat a subselect as a single value (e.g. foo = (subselect))
are now supported by calling .single_value().
#[derive(Insertable)] implements now Insertable also on the struct itself,
not only on references to the struct
ConnectionError now implements PartialEq.
Columns generated by table! now implement Default
#[derive(AsChangeset)] now implements AsChangeset on the struct itself,
and not only on a reference to the struct
Added support for deserializing Numeric into BigDecimal on SQLite. SQLite
has no arbitrary precision type, so the result will still have floating point
rounding issues. This is primarily to support things like avg(int_col),
which we define as returning Numeric
The bounds on impl ToSql for Cow<'a, T> have been loosened to no longer
require that T::Owned: ToSql.
32-column-tables are now enabled by default.
ne_any has been renamed to ne_all.
The large-tables feature has been has been renamed to 32-column-tables.
The huge-tables feature has been renamed to 64-column-tables.
IncompleteUpdateStatement has been removed. Use UpdateStatement instead.
diesel database setup now correctly handles database URLs containing query
strings
diesel migration list shows the proper migration order when mixing
old and new timestamp formats. (The migrations were always run in the correct
order, this only affects the display logic of migration list)
#[derive(Identifiable)] now correctly associates #[primary_key] with the
column name, not field name.
Select statements can no longer incorrectly appear in an expression context.
exists can no longer incorrectly receive values other than select
statements.
MysqlConnection::establish can now properly handle IPv6 addresses wrapped in
square brackets.
* No changes
Due to the design of FromSql, we can't provide impls for &str and &[u8] without a breaking change. However many impls just need to parse a string or s…
The primary focus of this release was improving the ergonomics of adding support for new types in Diesel.
For implementing new SQL types, we've added #[derive(SqlType)] which implements many traits that you need to implement for every SQL type. See the documentation for HasSqlType for details on this derive.
For implementing new mappings, we've added #[derive(FromSqlRow)] and #[derive(AsExpression)]. These derives will replace the majority of the boilerplate that was previously required when supporting new types. Adding support for new types in Diesel 1.1 should only require implementing FromSql and ToSql. The derives will handle the rest.
We've also provided FromSql impls for *const str and *const [u8]. Due to the design of FromSql, we can't provide impls for &str and &[u8] without a breaking change. However many impls just need to parse a string or some bytes, and don't need the allocation that would come from String or Vec<u8>. This will require unsafe code to use, but should make certain implementations more efficient.
Finally, we've restructured how our serialize/deserialize modules are structured, and provided type aliases to make implementations of FromSql and ToSql more consise.
r2d2_diesel is Now Part of DieselFinally, this release merges r2d2_diesel into Diesel itself. The main benefit of doing this is that we can implement Connection for PooledConnection, removing the need for explicit &* when using r2d2. This should also help to prevent version mismatches when changing Diesel versions.
To use the new r2d2 support, remove r2d2 and r2d2_diesel from your Cargo.toml. Add the r2d2 to your enabled features on diesel. Replace extern crate r2d2 with pub use diesel::r2d2. Replace any r2d2_diesel:: with diesel::r2d2::.
In addition to the headline features, there were dozens of smaller additions which should make using Diesel even better! As always, you can check the CHANGELOG for a full list of changes in this release.
In addition to the Diesel core team, 8 people contributed to this release. A huge thank you to:
r2d2-diesel has been merged into Diesel proper. You should no longer rely
directly on r2d2-diesel or r2d2. The functionality of both is exposed from
diesel::r2d2.
r2d2::PooledConnection now implements Connection. This means that you
should no longer need to write &*connection when using r2d2.
The BINARY column type name is now supported for SQLite.
The QueryId trait can now be derived.
FromSqlRow can now be derived for types which implement FromSql.
AsExpression can now be derived for types which implement ToSql.
HasSqlType, NotNull, and SingleValue can now be derived with
#[derive(SqlType)]. See the docs for those traits for more information.
The return type of FromSql, FromSqlRow, and QueryableByName can now be
written as deserialize::Result<Self>.
The return type of ToSql can now be written as serialize::Result.
Added support for SQLite's INSERT OR IGNORE and MySQL's INSERT IGNORE
via the insert_or_ignore function.
min and max can now be used with array expressions.
Added diesel::dsl::array, which corresponds to a PG ARRAY[] literal.
Added the not_none! macro, used by implementations of FromSql which do not
expect NULL.
Added result::UnexpectedNullError, an Error type indicating that an
unexpected NULL was received during deserialization.
Added .or_filter, which behaves identically to .filter, but using OR
instead of AND.
helper_types now contains a type for every method defined in
expression_methods, and every function in dsl.
Added FromSql impls for *const str and *const [u8] everywhere that
String and Vec are supported. These impls do not allocate, and are
intended for use by other impls which need to parse a string or bytes, and
don't want to allocate. These impls should never be used outside of another
FromSql impl.
with-deprecated feature by adding default-features = false to
Cargo.toml.Deprecated impl_query_id! in favor of #[derive(QueryId)]
Deprecated specifying a column name as #[column_name(foo)]. #[column_name = "foo"] should be used instead.
The types module has been deprecated. It has been split into sql_types,
serialize, and deserialize.
query_source::Queryable and query_source::QueryableByName have been
deprecated. These traits have been moved to deserialize.
backend::TypeMetadata has been deprecated. It has been moved to sql_types.
types::ToSqlOutput has been deprecated. It has been renamed to
serialize::Output.
helper_types::Not is now helper_types::not
infer_schema! generates valid code when run against a database with no
tables.Nothing published for this version
1.0.0 marks stability for Diesel. While there are many more features that will be added in the future, there will be no breaking changes from this poi…
We didn't quite make it for 2017, but Diesel 1.0 is finally here! There are no changes between Diesel 1.0 and 1.0.0-rc1.
1.0.0 marks stability for Diesel. While there are many more features that will be added in the future, there will be no breaking changes from this point forward without a major version bump (which we do not anticipate happening for many years).
A lot has happened since Diesel 0.1 was released over 2 years ago. While it would be impossible to list every major change that has happened since then, here are a few highlights:
diesel print-schema replaced infer_schema! as the go-to way to
infer your database schema.It's been a great honor to watch this community grow and thrive as this library has developed. I look forward to continuing to evolve Diesel, and seeing how far it can go.
In addition to the Diesel core team, 98 people have contributed to Diesel. A huge thank you to everyone who made this and every prior release possible:
#[derive(QueryableByName)] can now handle structs that have no associated
table. If the #[table_name] annotation is left off, you must annotate each
field with #[sql_type = "Integer"]
#[derive(QueryableByName)] can now handle embedding other structs. To have a
field whose type is a struct which implements QueryableByName, rather than a
single column in the query, add the annotation #[diesel(embed)]
The QueryDsl trait encompasses the majority of the traits that were
previously in the query_dsl module.
Executing select statements on SQLite will no longer panic when the database
returns SQLITE_BUSY
table!s which use the Datetime type with MySQL will now compile correctly,
even without the chrono feature enabled.
#[derive(QueryableByName)] will now compile correctly when there is a shadowed Result type in scope.
BoxableExpression can now be used with types that are not 'static
Connection::test_transaction now requires that the error returned implement Debug.
query_builder::insert_statement::InsertStatement is now accessed as
query_builder::InsertStatement
query_builder::insert_statement::UndecoratedInsertRecord is now accessed as
query_builder::UndecoratedInsertRecord
#[derive(QueryableByName)] now requires that the table name be explicitly
stated.
Most of the traits in query_dsl have been moved to query_dsl::methods.
These traits are no longer exported in prelude. This should not affect most
apps, as the behavior of these traits is provided by QueryDsl. However, if
you were using these traits in where clauses for generic code, you will need
to explicitly do use diesel::query_dsl::methods::WhateverDsl. You may also
need to use UFCS in these cases.
If you have a type which implemented QueryFragment or Query, which you
intended to be able to call execute or load on, you will need to manually
implement RunQueryDsl for that type. The trait should be unconditionally
implemented (no where clause beyond what your type requires), and the body
should be empty.
All deprecated items have been removed.
LoadDsl and FirstDsl have been removed. Their functionality now lives in
LoadQuery.
This release contains no major code changes. There are a handful of minor bug fixes (the most notable being that SQLite no longer panics when we recei
Happy holidays!
This release contains no major code changes. There are a handful of minor bug fixes (the most notable being that SQLite no longer panics when we receive SQLITE_BUSY), but most changes are related to ensuring that our API documentation renders better.
We do not expect any further changes to the codebase of any kind (other than the version number) between this release and 1.0.0. Assuming no critical issues are found with this release candidate, the code as it exists at this point will be released as 1.0.0 on 2017-12-30.
We do not plan on having a 1.0.0.beta2, but there may be additional minor breaking changes in that release if it is needed. If there are any code chan…
This release contains 2 major changes from 0.99.0. The first is not news, we have removed all deprecated code from the codebase. However, this release also contains some major restructuring of the query_dsl module.
Traits related to the construction of queries, such as SelectDsl, FilterDsl, etc. Have been merged into a single QueryDsl trait. Traits related to the execution of queries, such as ExecuteDsl and LoadDsl have been merged into a single RunQueryDsl trait. The individual method traits still exist under the query_dsl::methods module, but they are no longer exported from prelude.
Though we promised there would be no significant changes other than documentation, during our process of documenting this module, it became clear that making this change would make discovering how to use Diesel's query builder dramatically easier. It also gives us a much more centralized place to document these logically grouped methods. While we do not expect this change to break many apps, it is significant enough to warrant an early release.
Most applications should not need to care about this change. Code which is just doing use diesel::prelude::* and calling these methods will continue to work with no changes (though error messages will be improved if you make a mistake).
However, if you had code that was implementing QueryFragment or Query, and expected to be able to call .execute, .load, or similar on it (such as the Pagination helper in crates.io), you will need to add impl<Conn> RunQueryDsl<Conn> for YourType.
If you have code that is calling query builder methods generically (e.g. if you have where T: FilterDsl<Something>, you will likely need to explicitly import things from query_dsl::methods
In addition to those changes, there are some minor improvements to #[derive(QueryableByName)] which we had planned on releasing as 0.99.2.
With this release, 0.99.x will only receive bug fixes and security patches. No new features will be backported to that branch. However, 0.99 can be considered our first "LTS" release. While we have not yet determined what exactly that means for Diesel, you can be assured that release line will continue to be supported for as long as there is demand.
We do not plan on having a 1.0.0.beta2, but there may be additional minor breaking changes in that release if it is needed. If there are any code changes between now and 1.0.0, even non-breaking ones, we will have a release candidate before the final release.
As with 0.99.0, we expect that the only significant change between this release and 1.0.0 will be documentation. We expect that the final release of 1.0.0 will be before the end of the year.
Our only blocker for a final 1.0 release continues to be documentation. There is a lot of work to do before the end of the year. We need help from the community to reach our goal of releasing this year. If you're interested in helping out, join the impl period working group channel.
However, 1.0 will have an important significant difference. Anything that is deprecated as of this release will not be present in the 1.0 release. Thi…
This release is by far the largest Diesel has ever had. It serves 2 purposes. You can consider this release to be a beta for 1.0. However, 1.0 will have an important significant difference. Anything that is deprecated as of this release will not be present in the 1.0 release. This includes functions which were newly deprecated in 0.99. We know this may introduce a migration burden for some people, so we will continue to support the 0.99 line with bug fixes as long as there is demand and it is reasonable to do so.
This release is mainly focused on ergonomics. Our main new feature is the sql_query function. This is a new API which behaves similarly to sql, but it is entirely focused on cases where you want to write the entire query yourself. The main difference from sql is that you do not need to specify the return type of the query, and values are fetched by name rather than by index. This feature is still early, and there's a lot of features still to come (specifically evolving #[derive(QueryableByName)], but we think this feature will ease a lot of pains for cases where Diesel doesn't quite do what you need.
Additionally, you can now use tuples for inserts the same as you can for updates. If you've ever wanted to insert a row with just 1 or 2 values, and been annoyed that you needed a struct that you're only using in this one place, this feature will make you happy. We'll have new guides highlighting this feature soon.
Additionally, this release comes with a ton of quality of life features. Many of these changes are focused around making it easier to introduce line breaks naturally in your code. For example, .filter is now implemented on UpdateStatement, meaning you can write update(foo).filter(bar) instead of update(foo.filter(bar)). We've also introduced new APIs for insert and PG upsert which will have similar readability improvements.
This release includes more deprecations than any release prior. In particular, insert has been deprecated, along with our entire PG upsert API. All deprecations in this release have direct replacements, which will lead to code which formats much more nicely. It should be a mostly mechanical replacement for most apps. See the CHANGELOG file for details.
With this release, we'd like to welcome several new members to the Diesel committer team. @weiznich, @notryanb, and @katrinabrock you've all done excellent work and we're very excited to officially welcome you to the team!
In addition to the Diesel core and committer teams, 10 people contributed to this release. A huge thank you to:
Our only remaining blockers from this release and 1.0 are documentation changes, and having this tested in the wild. Thank you to every one of our users for your support, and we look forward to Diesel 1.0 by the end of the year!
The .for_update() method has been added to select statements, allowing
construction of SELECT ... FOR UPDATE.
Added insert_into(table).default_values() as a replacement for
insert_default_values()
Added insert_into(table).values(values) as a replacement for
insert(values).into(table).
Added support for MySQL's REPLACE INTO as replace_into(table).
Added replace_into(table).values(values) as a replacement for
insert_or_replace(values).into(table).
Added on_conflict_do_nothing on InsertStatement as a replacement for
on_conflict_do_nothing on Insertable structs.
Added on_conflict on InsertStatement as a replacement for
on_conflict on Insertable structs.
filter can now be called on update and delete statements. This means that
instead of update(users.filter(...)) you can write
update(users).filter(...). This allows line breaks to more naturally be
introduced.
Subselects can now reference columns from the outer table. For example,
users.filter(exists(posts.filter(user_id.eq(users::id)))) will now compile.
TextExpressionMethods is now implemented for expressions of type
Nullable<Text> as well as Text.
allow_tables_to_appear_in_same_query! can now take more than 2 tables, and is the same
as invoking it separately for every combination of those tables.
Added sql_query, a new API for dropping to raw SQL that is more pleasant to
use than sql for complete queries. The main difference from sql is that
you do not need to state the return type, and data is loaded from the query by
name rather than by index.
Added a way to rename a table in the table! macro with #[sql_name="the_table_name"]
Added support for PostgreSQL's DISTINCT ON. See
.distinct_on() for more details
The signatures of QueryId, Column, and FromSqlRow have all changed to
use associated constants where appropriate.
You will now need to invoke allow_tables_to_appear_in_same_query! any time two tables
appear together in the same query, even if there is a joinable! invocation for those tables.
diesel_codegen should no longer explicitly be used as a dependency. Unless
you are using infer_schema! or embed_migrations!, you can simply remove it
from your Cargo.toml. All other functionality is now provided by diesel
itself.
Code using infer_schema! or infer_table_from_schema! must now add
diesel_infer_schema to Cargo.toml, and #[macro_use] extern crate diesel_infer_schema to src/lib.rs
Code using embed_migrations! must now add diesel_migrations to Cargo.toml,
and #[macro_use] extern crate diesel_migrations to src/lib.rs
The migrations module has been moved out of diesel and into
diesel_migrations
Deprecated insert_default_values() in favor of
insert_into(table).default_values()
Deprecated insert(values).into(table) in favor of
insert_into(table).values(values).
Deprecated insert_or_replace(values).into(table) in favor of
replace_into(table).values(values).
Deprecated .values(x.on_conflict_do_nothing()) in favor of
.values(x).on_conflict_do_nothing()
Deprecated .values(x.on_conflict(y, do_nothing())) in favor of
.values(x).on_conflict(y).do_nothing()
Deprecated .values(x.on_conflict(y, do_update().set(z))) in favor of
.values(x).on_conflict(y).do_update().set(z)
Deprecated enable_multi_table_joins in favor of
allow_tables_to_appear_in_same_query!
Deprecated SqlLiteral#bind. sql is intended for use with small fragments
of SQL, not complete queries. Writing bind parameters in raw SQL when you are
not writing the whole query is error-prone. Use sql_query if you need raw
SQL with bind parameters.
IntoInsertStatement and BatchInsertStatement have been removed. It's
unlikely that your application is using these types, but InsertStatement is
now the only "insert statement" type.
Citext as a type alias for Text has been removed. Writing
citext_column.eq("foo") would perform a case-sensitive comparison. More
fleshed out support will be required.
When using MySQL and SQLite, dates which cannot be represented by chrono
(such as 0000-00-00) will now properly return an error instead of panicking.
MySQL URLs will now properly percent decode the username and password.
References to types other than str and slice can now appear on structs which
derive Insertable or AsChangeset.
Deserializing a date/time/timestamp column into a chrono type on SQLite will
now handle any value that is in a format documented as valid for SQLite's
strftime function except for the string 'now'.
One column per quarter.