#orm #database #blockchain #sql

diesel

A safe, extensible ORM and Query Builder for PostgreSQL, SQLite, and MySQL

47 releases (10 stable)

1.3.2 Jun 14, 2018
1.2.2 Apr 12, 2018
1.1.1 Jan 16, 2018
1.0.0-rc1 Dec 23, 2017
0.2.0 Nov 30, 2015

#3 in Database interfaces

Download history 2353/week @ 2018-09-10 4169/week @ 2018-09-17 3682/week @ 2018-09-24 4112/week @ 2018-10-01 3186/week @ 2018-10-08 3634/week @ 2018-10-15 4054/week @ 2018-10-22 3860/week @ 2018-10-29 3301/week @ 2018-11-05 3480/week @ 2018-11-12 3385/week @ 2018-11-19 2525/week @ 2018-11-26 2288/week @ 2018-12-03

10,060 downloads per month
Used in 63 crates (60 directly)

MIT/Apache

1MB
25K SLoC

Diesel

Diesel - A safe, extensible ORM and Query Builder for Rust

Diesel is the most productive way to interact with databases in Rust because of its safe and composable abstractions over queries.

Getting Started

This is the Readme of the main crate. You can find an extensive Getting Started tutorial and more information on our website.


lib.rs:

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.

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 Includes various helper types and bare functions which are named too generically to be included in prelude, but are often used when using Diesel. 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.

All types here are in the form <FirstType as DslName<OtherTypes>>::Output. So the return type of users.filter(first_name.eq("John")).order(last_name.asc()).limit(10) would be Limit<Order<FindBy<users, first_name, &str>, Asc<last_name>>> Re-exports important traits and types. Meant to be glob imported when using Diesel.

Dependencies

~5MB
~102K SLoC