sgrif / diesel.rs-website

MIT License
32 stars 97 forks source link

Add example code from other databases to Getting Started document #229

Closed zacharesmer closed 1 month ago

zacharesmer commented 1 month ago

Hi, I followed your getting started guide earlier using SQLite (and thank you--it successfully got me started!), and I agreed with issue #130.

I put together some javascript to show the blocks of code for the examples using different databases. This is not quite as nice as the mock up in that issue, but the code-blocks seemed like they would be more complicated to add buttons to. Let me know if you think that (or anything else) should work differently and I can try to fix it.

The code examples I added were all copied and pasted out of here. Any examples that were exactly the same across the 3 databases I just left as they were and they still link to the PostgreSQL on github since I didn't want to add 3 copies of the same code just to update the github link. If you think that should be more consistent I can take another look and maybe find some better way to update the link.

Some specific questions I guessed on for now but should be answered definitively if you want to merge this:

Example of the markdown format to make a new code block that has different code for the different database options:

::: postgres-example
::: code-block

[Cargo.toml](https://github.com/diesel-rs/diesel/blob/2.2.x/examples/postgres/getting_started_step_1/Cargo.toml)

```toml
[dependencies]
diesel = { version = "2.2.0", features = ["postgres"] }
dotenvy = "0.15"
```
:::
:::

::: sqlite-example
::: code-block 

[Cargo.toml (SQLite)](https://github.com/diesel-rs/diesel/blob/2.2.x/examples/sqlite/getting_started_step_1/Cargo.toml)

```toml
[dependencies]
diesel = { version = "2.2.0", features = ["sqlite"] }
dotenvy = "0.15"
```
:::
:::

::: mysql-example
::: code-block 

[Cargo.toml (MySQL)](https://github.com/diesel-rs/diesel/blob/2.2.x/examples/mysql/getting_started_step_1/Cargo.toml)

```toml
[dependencies]
diesel = { version = "2.2.0", features = ["mysql"] }
dotenvy = "0.15"
```
:::
:::
weiznich commented 1 month ago

Thanks for opening this PR. This is really great to see :heart: I just spend some time on polishing this up so that this can be deployed soonish.

The most important change that I introduced is that we now have an additional custom pandoc filter that allows to only put code examples that are literally the same in there once. The filter will then duplicate the code on the webpage with the right labels and links.

I also fixed minor inconsistencies I've noticed while working on that, which mostly existed before. I filled https://github.com/diesel-rs/diesel/pull/4238 for some fixes it in the diesel repo as well.

Finally I've put the javascript code into the application.js file, so that we can easily use that in other guides as well. The "All about Inserts" guide should have a complete coverage for all backends as well, so we might want to update that one next.

To answer the questions:

Does this example, step 1 lib.rs need to include the line use diesel::sqlite::SqliteConnection; (or in the others, PgConnection or MySQLConnection)? The current getting started example includes the line use diesel::pg::PgConnection;, but in the linked file on github that line is not included. It compiled and ran for me on SQLite without including that line.

It's not required to have this line, as this type is part of the diesel::preluded:* import. So it's already there if you have that wild card import. I think we removed them from the examples in the repo at some point as rustc/clippy pointed out that they are unneeded.

In the table macro example of schema.rs, does that actually vary by database type? I copied the generated schema.rs files from the examples, but I'm not sure if that is supposed to be different because it's not the auto-generated file.

This is expected as the naming rules for the generated types not very intelligent. Essentially we convert everything to uppercase and afterwards expect that the type exists in diesel::sql_types, so it really depends on the database how exactly these types look like. Functionally all the variants are the same, we handle that by having "some" type-defs in the diesel::sql_types module.