Add a more "advanced" example #1428

sgrif · 2017-12-20T21:10:15Z

This app is eventually going to be used as part of the advanced querying
guide. Unlike the getting started guide, that guide will not be a step
by step "building this app" style guide, but will instead refer to some
of the code in this example for its code examples, as I want to have
them presented with broader context if the reader wants it.

Since this example is meant to be separate from the guide, I figured it
made sense to submit it on its own.

Originally I chose a CLI blog for the getting started guide because I
wanted the example purely focused on Diesel, with little to no noise
from CLI stuff or a web framework. Clearly that is not the case here. In
fact, a web app probably would be a better example. However, I'm so
amused by the idea of a "CLI blog" that I decided to double down on it
and make a multi-tenant blog wiht commenting functionality and
pagination. Of course this is a pointless exercise, since having auth
logic makes no sense when the client requires a direct database
connection...

Anyway, this example is meant to provide some examples for the following
more complex use cases:

Various types of joins and associations. Demonstrating data with
multiple associations that go to the same table multiple times, and is
difficult to describe unambiguously
When to use joins vs belonging_to
Nesting queryables (see the structs used in auth)
Dealing with structs that don't contain all fields from a table
Demonstrating that Queryable represents the results of a query, not
a single table
- I want to restructure how all_posts works. I really want to have
  a struct that is used for "comment with username" and "comment
  with post title" but that doesn't work well today. I'm going to
  revisit for 1.1
Real world use of returning
Real world constraint error handling (I may change this to be
.on_conflict(username).do_nothing() and handle it there so this maps
more easily to SQLite and MySQL. If we're being pedantic I should be
checking the constraint name in that match arm)
Showing how to deal with "sometimes update this field" without using
AsChangeset.
Showing that various query builder methods compose together
Generally just having more examples of non-trivial queries.

killercup

(Reviewed up to main.rs)

killercup · 2018-01-01T14:50:11Z

examples/postgres/advanced-blog-cli/Cargo.toml

+chrono = "0.4.0"
+diesel = { version = "1.0.0-beta1", features = ["postgres", "chrono"] }
+dotenv = "0.10.0"
+tempfile = "2.2.0"


Now this is weird: I just realized all the dependencies were sorted alphabetically, except for this line. And it's my fault 😅

killercup · 2018-01-01T14:51:05Z

examples/postgres/advanced-blog-cli/migrations/00000000000000_diesel_initial_setup/down.sql

@@ -0,0 +1,2 @@
+DROP FUNCTION IF EXISTS diesel_manage_updated_at(_tbl regclass);


Random remark: This file should probably have a -- This file was automatically created by Diesel header

Open an issue? ;)

killercup · 2018-01-01T15:04:08Z

examples/postgres/advanced-blog-cli/src/auth.rs

+    if_not_present(dotenv::var("BLOG_PASSWORD"), NoPasswordSet)
+}
+
+fn if_not_present<T>(


That's a weird name… I'd probably write an fn get_dotenv_or_err_with(&str, AuthenticationError) that also includes the dotenv::var. Making this a very generic function doesn't really help here, as it internally depends on dotenv::Error anyway.

killercup · 2018-01-01T15:04:49Z

examples/postgres/advanced-blog-cli/src/auth.rs

+use schema::users;
+
+#[derive(Debug)]
+pub enum AuthenticationError {


I'd move this (and the From impl) just above the helper functions (that start with find_user).

killercup

Very nice, the comments here conclude my review.

Do the other examples have README.md files? Maybe we can add one here. It doesn't really map 1:1 to a guide (yet), and pointing out a few interesting aspects couldn't hurt.

killercup · 2018-01-01T16:35:00Z

examples/postgres/advanced-blog-cli/src/pagination.rs

+use diesel::pg::Pg;
+use diesel::types::BigInt;
+
+pub trait Paginate: Sized {


Not that it is particularly useful here, but in the 'leading by example' sense we should probably add some doc comments to the public items in this module. At least, we should add a module level doc comment that links to the #1437 guide (once it is online)

I agree. I'm going to merge without doing this so I can publish a guide referencing code here, but I will make sure to come back and do this after we ship 1.0

killercup · 2018-01-01T16:39:57Z

examples/postgres/advanced-blog-cli/src/post.rs

+    pub status: Status,
+}
+
+pub enum Status {


I'd call more attention to this enum here and its Queryable impl as it's not just boilerplate but actually one of the 'advanced' features :) So maybe add a doc comment that describes how this is used to map NULL to Draft, and how it's a good idea to do this instead of just using Option<NaiveDateTime>.

Advanced querying guide will

killercup · 2018-01-01T16:41:21Z

examples/postgres/advanced-blog-cli/src/schema.rs

@@ -0,0 +1,38 @@
+table! {


Maybe add

// generated by `diesel print-schema`

But then I can't do diesel print-schema > src/schema.rs

This app is eventually going to be used as part of the advanced querying guide. Unlike the getting started guide, that guide will not be a step by step "building this app" style guide, but will instead refer to some of the code in this example for its code examples, as I want to have them presented with broader context if the reader wants it. Since this example is meant to be separate from the guide, I figured it made sense to submit it on its own. Originally I chose a CLI blog for the getting started guide because I wanted the example purely focused on Diesel, with little to no noise from CLI stuff or a web framework. Clearly that is not the case here. In fact, a web app probably would be a better example. However, I'm so amused by the idea of a "CLI blog" that I decided to double down on it and make a multi-tenant blog wiht commenting functionality and pagination. Of course this is a pointless exercise, since having auth logic makes no sense when the client requires a direct database connection... Anyway, this example is meant to provide some examples for the following more complex use cases: - Various types of joins and associations. Demonstrating data with multiple associations that go to the same table multiple times, and is difficult to describe unambiguously - When to use joins vs `belonging_to` - Nesting queryables (see the structs used in auth) - Dealing with structs that don't contain all fields from a table - Demonstrating that `Queryable` represents the results of a query, not a single table - I want to restructure how `all_posts` works. I really want to have a struct that is used for "comment with username" and "comment with post title" but that doesn't work well today. I'm going to revisit for 1.1 - Real world use of `returning` - Real world constraint error handling (I may change this to be `.on_conflict(username).do_nothing()` and handle it there so this maps more easily to SQLite and MySQL. If we're being pedantic I should be checking the constraint name in that match arm) - Showing how to deal with "sometimes update this field" without using `AsChangeset`. - Showing that various query builder methods compose together - Generally just having more examples of non-trivial queries.

Structopt allows generating clap-based CLI arg parsers by using derives on structs/enums. Crucially, it also handles converting arguments to their expected types. My goal here was to reduce the CLI parsing boilerplate (this code lives in Diesel's example directory and should thus focus on Diesel) while also switching to a style that will most likely be used by the next version of clap itself. There still is more boilerplate[^1] than I'd like to have, but at least it's now a well-typed enum, and we can skip all the type conversion steps. Also note that the line count is slightly skewed by my additional help texts. [^1]: For example: If there was a "convert enum variant name to kebab-case[^2] option I'd love to use it instead of all these `name = "foo_bar"` attributes. [^2]: Yes we should totally use kebab-case and not snake_case here.

Add a more "advanced" example

sgrif requested a review from a team December 20, 2017 21:10

This was referenced Dec 22, 2017

Simplify advanced blog CLI using structopt #1433

Merged

Print with newline edge cases rust-lang/rust-clippy#2295

Closed

killercup reviewed Jan 1, 2018

View reviewed changes

killercup mentioned this pull request Jan 2, 2018

Add comment to diesel_initial_setup/down.sql #1445

Merged

sgrif and others added 4 commits January 2, 2018 14:44

Advanced blog: Fix formatting, add help text

7804bb4

Sort dependencies

59a4fee

sgrif force-pushed the sg-advanced-blog-cli branch from e173651 to 59a4fee Compare January 2, 2018 21:45

sgrif merged commit 746a419 into master Jan 2, 2018

sgrif deleted the sg-advanced-blog-cli branch January 2, 2018 21:47

sgrif added a commit that referenced this pull request Jan 2, 2018

Merge pull request #1428 from diesel-rs/sg-advanced-blog-cli

0432e09

Add a more "advanced" example

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a more "advanced" example #1428

Add a more "advanced" example #1428

sgrif commented Dec 20, 2017

killercup left a comment

killercup Jan 1, 2018 •

edited

Loading

killercup Jan 1, 2018

sgrif Jan 2, 2018

killercup Jan 1, 2018

killercup Jan 1, 2018

killercup left a comment

killercup Jan 1, 2018

sgrif Jan 2, 2018

killercup Jan 1, 2018

sgrif Jan 2, 2018

killercup Jan 1, 2018

sgrif Jan 2, 2018

		@@ -0,0 +1,2 @@
		DROP FUNCTION IF EXISTS diesel_manage_updated_at(_tbl regclass);

Add a more "advanced" example #1428

Add a more "advanced" example #1428

Conversation

sgrif commented Dec 20, 2017

killercup left a comment

Choose a reason for hiding this comment

killercup Jan 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

killercup left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

killercup Jan 1, 2018 •

edited

Loading