Document Diesel usage guidelines and edge cases

[killercup]

We don't (yet) have a good way to document general guidelines on how to use Diesel or, put another way, how we expect it to be used. There are a lot of implicit assumption and various edge cases to keep track of. For many, Diesel there are answers in this issue tracker, but the issues have been closed.

This meta issue wants to keep track of these undocumented pieces.

• How to write query builder return types using diesel::helper_types (Query dsl generated by select leak private types to public interface #1037)
• What to keep in mind when using diesel_derive: Name-spacing and hygiene (Insertable derive may error if used with other schema features #1032)
• When to use a table's dsl namespace: Only in functions dealing with one table (Insertable derive may error if used with other schema features #1032)

If you want to help out, we'd love to get PRs to add more information to our API docs. The linked issues usually contain the necessary information, but feel free to ask on gitter for more details.

We might also want to move some of this to a new section of the website. Either a new guide on Best Practices or a good ol' FAQ page.

---

@killercup will try to update this issue semi-regularly. Ping him on Gitter or in the issue tracker if you have suggestions or questions.

[lancecarlson]

@killercup For the last one, perhaps adding language to end of this section would make sense?

http://docs.diesel.rs/diesel/macro.table.html#dsl

Something along the lines of: Only import this into the scope of a function you a building the query in otherwise it will pollute the namespace.

Perhaps an example could be provided that looked something like this:

// bad
use diesel_demo::schema::posts::dsl::*;
fn main() {
    // good
    use diesel_demo::schema::posts::dsl::*;
}

If you're cool with this, I'll make a PR.

[killercup]

@lancecarlson sounds good!

[wt]

The issues that were tracked by this issue appear to be closed. Should this issue also be closed?

[wowinter13]

@wt Thanks, closing this one!
It appears that all related issues are closed.

---

Just in case you're looking for some issues to contribute to Diesel:

• Add support for currently unsupported postgres json/jsonb functions #4216
• Missing documentation about concurrent runs of MigrationHarness::run_pending_migrations #3707
• Add support for currently unsupported Postgres multirange functions #4240