General usage instructions on a README.md per crate. (Best practices, basic patterns, more docs...) <enhancement>

[aaronpeacock]

Not a bug, possibly an enhancement. Solid awesome driver. Focused. I appreciate what an absolute PILLAR of the community this driver is!

Please take the following as constructive criticism, and I will be happy to help make it possible ONCE I LEARN HOW this pocket of the Rust culture functions. In a nutshell, I see a communication issue and the classic "insider/outsider" dichotomy of knowledge vs the lack thereof.

I see a million "how the heck does one use this?" questions on Rust forums, and here in the github "issues", not to pick on anyone particular but here's an egregious example of where steerage could be better done if the folks in the know would share their knowhow: https://users.rust-lang.org/t/tokio-postgres-and-database-query/48329
(yikes. look at the response. some docs here would do damage control... )

I can interpret: people who maintain this lovely crate know stuff. The rest of us do not, until we do. People can learn things by trial and error. They can also learn the wrong way to do things by trial and error.

I can peruse the various crates all stuck together here in one repo (unconventional) but I don't find usage documentation anywhere.

I am not referring to the API docs, which is a microscope on how to use a given trait/function/struct/module/whatever. I am speaking of the convention on Github and in FOSS in general to have a "README.md" in the root of the directory that explains to humans 1) what this crate is and isn't, a description of it's features. 2) a basic example of how to use in each kind of query as it pertains to

• query syntax
• Rust types, the internal type conversion (postgres_types) (of which ONE example of a query exists on the API docs, for a SELECT. I saw 3 issues on the Rust language forum having questions about syntax of insert queries with regards to single quotes around the $n variables.) 3) Since 5 crates share one Git repo, perhaps explain WHY and how they inter-relate.

Due to the fact that there are 5 crates here in one repo, I will suggest we can add a README.md to each crates directory. Convention seems to be that project development instructions goes below usage instructions, FWIW. My guess is that the most urgent need is for the tokio-postgres (tokio_postgres) crate to have a basic README.md I will suggest that such a README.md needs a usage example for:

• install crate and features
• establish connection
• passing connection
• insert query
• select query (exists)
• error handling With some mention of the type -conversions.

People often ask about "prepared statements" There's no "production guide" to using this crate. Best-practices and secure usage and how this relates to the various features that ARE documented. A 'guide' usually features a soup-to-dessert approach, which I think would be highly useful. I think that outlining the BOUNDARIES of where this crate integrates with other crates would be highly useful: "A connection pool such as: X, Y, or Z, should be used in production due to pdq" We can have an explanation as to when one will use which postgres crate and why. We can have an "ecosystem" of links (like sqlx does on their page) that show how this crate relates to others built upon it, or the contrary.

I am personally unclear on what ToSql and FromSql actually do and where/how they are used. If they are implemented for primitive Types, how does one implement them for a struct composed of primitive types, etc. (when would someone implement their own ToSql/FromSql and why? My confusion is: if ToSql and FromSql is already implemented for primitive types, what does "deriving" it for our custom type provide and what do we need to write?)

People coming from sqlx will want to know about from_row kinds of things, and how one can take a DB row and inflate a struct and vice-versa. I saw people asking if they should use serde!? for the mercy of the future codebase, we need a guide, in addition to the API docs.

There are many features in the vast API docs, but how one should wield them is what a guide is for. I only learned about Row https://docs.rs/tokio-postgres/0.7.12/tokio_postgres/row/struct.Row.html from someone ELSES crate that showed me a typical example from tokio-postgres and why it was tedious and what their crate (tokio-postgres-mapper ) did that was supposedly easier. https://github.com/Dowwie/tokio-postgres-mapper I would think that there are some examples we can have here inside the tokio-postgres folder on its own README.md (vetted approved examples. I will be happy to be shown some, many thanks for any suggestions in advance.)

Tera template engine is a good example:

• their API docs = https://docs.rs/tera/latest/tera/
• their guide = https://keats.github.io/tera/docs (it's a common convention in many projects. I think a reasonable README.md per crate that shows usage examples for as much of the featureset as possible is in order. The particular format of API docs does not give any overview of such, IMO)

Thank you for reading this far. I want to help, as soon as I learn how to use this crate properly, and so this is basically me justifying why I think it is needed.

[aaronpeacock]

Example on how API doc is completely inadequate for learning a crate: https://docs.rs/tokio-postgres/0.7.12/tokio_postgres/types/macro.to_sql_checked.html What does this mean?

I click 'source' and see https://docs.rs/postgres-types/0.2.8/src/postgres_types/lib.rs.html#233 wait a minute, suddenly we are looking at another crate here. Be that as it may, I read the entire postgres-types lib.rs file and am no wiser as to what this is all about. Lines 8 & 9 give us more of this circular speech with no general definition of what a crate user gets for their efforts.

//! If the `derive` cargo feature is enabled, you can derive `ToSql` and `FromSql` implementations for custom Postgres
//! types. Explicitly, modify your `Cargo.toml` file to include the following:

Is there a place in the vast API docs that defines what an implementation of ToSql does, should do, even is? Is is part of a larger strategy or workflow? WHAT DOES TOSQL & FROMSQL even mean?! What is the imagined workflow here? THAT WORKFLOW needs to be documented.

[aaronpeacock]

Example on how API doc is completely inadequate for learning a crate: https://docs.rs/tokio-postgres/0.7.12/tokio_postgres/types/macro.to_sql_checked.html What does this mean?

I click 'source' and see https://docs.rs/postgres-types/0.2.8/src/postgres_types/lib.rs.html#233 wait a minute, suddenly we are looking at another crate here. Be that as it may, I read the entire postgres-types lib.rs file and am no wiser as to what this is all about. Lines 8 & 9 give us more of this circular speech with no general definition of what a crate user gets for their efforts.

//! If the `derive` cargo feature is enabled, you can derive `ToSql` and `FromSql` implementations for custom Postgres
//! types. Explicitly, modify your `Cargo.toml` file to include the following:

Is there a place in the vast API docs that defines what an implementation of ToSql does, should do, even is? Is is part of a larger strategy or workflow? WHAT DOES TOSQL & FROMSQL even mean?! What is the imagined workflow here? THAT WORKFLOW needs to be documented.

AH HAH! I then find: https://docs.rs/tokio-postgres/0.7.12/tokio_postgres/types/trait.ToSql.html explains how ToSql and postgres-types relate. It apparently does the mapping that postgres-types has if you derive it for your struct? If so, that is where we start, so I am basically saying that the role each trait/method/struct in a crate plays in a given workflow needs to be documented, unless you want a cargo-cult of snippets proliferating on the net without any general understanding about how these interrelated crates work.

Workflows. I need to understand them

• to selfishly use them for my own work
• to document this, as I said I would do above: if I manage to figure out how to use this stuff relatively soon, I will use it, and then document it.

[aaronpeacock]

OR is the intention @sfackler to centralize ALL documentation on the https://docs.rs/tokio-postgres/latest/tokio_postgres/ API docs?

• Issue #540 says explicitly so.

We could generate a README.md per a specific page of the docs.rs for each crate.

One problem is that there is no top-level documentation at docs.rs. I think #738 alludes to this without saying so. We have documentation for each crate. Crates commonly cross boundaries (postgres using postgres-types) and I think it could use a dependency graph and general high-level document that could later be expanded upon.

I am basically saying we need a "guide" or "high level documentation" on HOW to use the various bits of this collection of crates in a common workflow people already are well familiar with: (or WHO needs to use WHICH and WHY) This guide can also delineate boundaries of responsibility, for example:

• example of making a simple database connection. Explanation that one will use a connection pool in production/common usage. (no need to give examples there, that's another crates responsibility)
• example of creating a query and executing it and receiving it's results (exists on current API doc)
• example of creating a prepared query and executing it, with a brief statement on WHY
• example of transforming a users struct to ? (I'm unclear on what one does yet. I currently just insert references to my individual field values into a simple SQL insert like a dumb noob. I need a good insert example of a prepared query, I guess. Interweb searches produce results for batch inserts but not a basic insert, and who knows what is good with so-called AI in the mix these days...) and inserting it into the database
• Explanation of all these traits and macros and freebies we get if we learn specific features of the crate(s) (of this, I see only ad-hoc cargo-cult snippet mongering = not knowledge, not understanding.)

I am presuming that opposition to having crate README.md's per crate is due to keeping files in sync with the generated docs (from code comments) which is fine, if we then incorporate this guide into the docs, or a link to it. I will be happy to learn of the general intentions here, in case I am totally wrong here.

A guide DOES mean manual writing (I'm happy to do this part, as stated) and potential sync issues resulting. However, the workflows described in a guide do not change unless major breaking changes to the code architecture and workflows occur. Individual releases do not generally invalidate a guide.

this issue I raise is due to my personal desire to use this crate and my difficulty in extracting much sense of how it works and how to use it, despite knowing that I don't want an ORM and I need to connect to postgres and do CRUD with SQL and wanting total type safety.

[aaronpeacock]

ALTERNATIVE proposal: an examples folder. Axum has a good examples folder. Each is a separate crate.

https://github.com/tokio-rs/axum/tree/main/examples