# Diesel
*Diesel is a Safe, Extensible ORM and Query Builder for Rust*
- Home page: [diesel.rs](https://diesel.rs/)
- [Guides](https://diesel.rs/guides/)
- [API docs](https://diesel.rs/docs/)
- [docs.rs](https://docs.rs/diesel/latest/diesel/)
- [GitHub repo](https://github.com/diesel-rs/diesel)
- Supported databases:
- [[Postgres]]
- [[MySQL]]
- [[SQLite]]
### Alternative Rust ORM: [sea-orm](https://github.com/SeaQL/sea-orm)
*An async & dynamic ORM for Rust*
- 2.1k stars ATTOW
### Issue [#399](https://github.com/diesel-rs/diesel/issues/399): Async I/O
- [2018 comment](https://github.com/diesel-rs/diesel/issues/399#issuecomment-357361992) explaining why Diesel is not going with async yet
- [Dec 23, 2021 comment](https://github.com/diesel-rs/diesel/issues/399#issuecomment-1000169258) introducing [diesel-async](https://github.com/weiznich/diesel_async)
- The current native library that [[Diesel]] depends on (`libpq`) is what's preventing [[Diesel]] from being async
### diesel-async
- [Reddit post](https://www.reddit.com/r/rust/comments/s5cgbx/dieselasync_an_async_version_of_diesel/hswio5z/) introducing it
- [GitHub](https://github.com/weiznich/diesel_async) (22 commits, broken build ATTOW)
### Stalled PR [#2257](https://github.com/diesel-rs/diesel/pull/2257) to use pure Rust driver
## [Getting started](https://diesel.rs/guides/getting-started.html)
### Add to dependencies
`Cargo.toml`
```toml
[dependencies]
diesel = { version = "1.4.4", features = ["postgres"] }
dotenvy = "0"
```
- `dotenvy` is a better-maintained fork of `dotenv`, which the owner appears to have abandoned.
### Install DB native client library
- [`libpq`](https://www.postgresql.org/docs/current/libpq.html) for the PostgreSQL backend
- [`libmysqlclient`](https://dev.mysql.com/doc/c-api/8.0/en/c-api-implementations.html) for the Mysql backend
- [`libsqlite3`](https://www.sqlite.org/index.html) for the SQlite backend
For [[Postgres|Postgres]]:
![[Postgres#Install native client library libpq]]
### Install `diesel_cli` to use with [[Postgres]]
```bash
cargo install diesel_cli --no-default-features --features postgres
```
- If there is a linker error, that means that the specified DB native client library is missing.
### Set `DATABASE_URL` in `.env`
```bash
echo DATABASE_URL=postgresql://kek:sadge@localhost:5432/<appname>-dev > .env
```
### Run automatic setup
```bash
diesel setup
```
"This will create our database (if it didn’t already exist), and create an empty migrations directory that we can use to manage our schema (more on that later)."
### Create migration for a `users` table
Generate the new migration named `create_users`
```bash
diesel migration generate create_users
```
`migrations/<datetime>_create_users/up.sql`
```sql
CREATE TABLE users (
id SERIAL PRIMARY KEY,
)
```
`migrations/<datetime>_create_users/down.sql`
```sql
DROP TABLE users
```
### Apply the migration
```bash
diesel migration run
```
### Verify that `down.sql` reverts `up.sql`
```bash
diesel migration redo
```
### Run migrations at application startup using `diesel_migrations` crate
`Cargo.toml`
```toml
[dependencies]
diesel_migrations = "1"
```
`main.rs`
```rust
use std::env;
use diesel::connection::Connection;
use diesel::pg::PgConnection;
fn main() {
let _ = dotenvy::dotenv();
let db_url = env::var("DATABASE_URL")
.expect("DATABASE_URL must be defined in environment");
let db_conn = PgConnection::establish(&db_url)
.unwrap_or_else(|_| panic!("Could not connect to {}", db_url));
// Run any pending migrations
diesel_migrations::run_pending_migrations(&db_conn)
.expect("Could not run pending migrations");
println!("Started application");
}
```
### Add `schema` and `models` modules
`src/models.rs`
```rust
use diesel::deserialize::Queryable;
#[derive(Queryable)]
pub struct User {
pub id: i32,
}
```
- `src/schema.rs` should have been generated
`main.rs`
```rust
mod schema;
mod models;
```
### Nevermind, [[Diesel]] is really annoying to work with using idiomatic (non-magical) Rust 2018 syntax and the maintainers do not appear to care
- https://github.com/diesel-rs/diesel/issues/1764
- https://github.com/diesel-rs/diesel/issues/3065