Better "database" documentation

[Owez]

Feature Request

The database section of the rocket.rs guide, found here feel too sparse and confusing. There are no real links to further details of higher-level implementation of something like diesel and the links that are there seem to be middleware-like for r2d2 -> rocket.rs bindings.

I have also searched online for more guides with setting up diesel-based databases but all I have so far came across is an external article on medium.com (source) which isn't what i'm looking for and a SQLite-based examples/ todo list which doesn't seem to mirror the official guide tutorial, importing diesel and such directly.

Overall, my request is more higher-level documentation for databases as the current guide feels more like an insignificant footnote in the docs.

General Comments

Apologies that this issue is quite broad; just feels like this section of the guide is not up to par with many other parts. Not a contributer myself, just a user of rocket.

[jebrosen]

There are no real links to further details of higher-level implementation of something like diesel and the links that are there seem to be middleware-like for r2d2 -> rocket.rs bindings.

Yes, the main purpose of that page is to demonstrate how to use the database pools. I don't know why diesel was originally chosen for the example, but unfortunately I think it's a uniquely bad example for the documentation today for two reasons:

First, in my opinion, diesel's own getting started guide ("Get Started" on http://diesel.rs/) is pretty much mandatory reading in order to use diesel at all. Most idiomatic diesel code relies heavily on code generated by the table! macro, which is difficult to see without going through that guide.

The second reason is that the diesel CLI tool assumes a few things about your project: 1) you have a single database, located at DATABASE_URL - in contrast to rocket's support for database pools, which allows for multiple database connections in the configuration file. And 2) the CLI generates a file, schema.rs, that requires a #[macro_use] extern crate diesel; and a mod schema; in your crate root.

All that said, I see a few ways to improve the documentation. We could make the changes I suggested in #950 (comment), if they would have helped clear up any of your confusion. If not, what would have? Another option might be to replace diesel with something else, such as rusqlite, in that part of the documentation.

[Owez]

Having a simpler database showcased would help a bunch but could also be beneficial to generally expand the database section to give the user a simple, most likely sqlite-based solution to show a simple database setup; and then in another subheading provide briefing to diesel (which may be used most commonly in production), with external links to more diesel getting started tutorials externally for further reading. Layout would be something like this:

# Databases

[introduction to how rocket.rs works with fairings and databases]

## [Simple sqlite]

[basic `usage`-like showcase of a simple sqlite crud]

## Diesel

[beginnings of how to setup diesel fairings/structure application with diesel and proper "further reading" integration]

[swapsCAPS]

For me as a rust beginner, a working, properly implemented sqlite example would be extremely helpful.

[stappersg]

I think a list of URLs to projects that use Rocket with a database connection would help.
Yes, I do learn from reading existing code in addition to actual coding myself.

[Ran4]

I would love for including information on how to set up tests using a test db (where you drop the database and re-create it before every test, or run every test in a transaction that is then rolled back, whichever Rocket would recommend doing).

[MorezMartin]

I'm playing with sled, pretty cool, with sled_extensions you quickly have a json storage for your structs / enums. To be considered as unstable...

[SergioBenitez]

I'm playing with sled, pretty cool, with sled_extensions you quickly have a json storage for your structs / enums. To be considered as unstable...

I would caution anyone from using sled at this point in time, giving the various known bugs, which include segfaults (memory unsafety), self-DoS due to exuberant memory usage, panics, deadlocks, and functional correctness issues.

[tobymurray]

Just to be explicit if anyone else ends up here, a whack load of examples have been added, see https://github.com/SergioBenitez/Rocket/tree/master/examples. The databases ones in particular appear to address the concerns in this issue