fix: cargo fmt + harden SQL examples

- cargo fmt --all cleanup across lib.rs / main.rs / bin_smoke.rs /
  benches/contract_assertions.rs (max-line-width drift; CI gate caught it).
  Tests + clippy + 100% coverage all still hold.
- sql/01-fundamentals/01-connect.sql + 02-show-tables.sql: psql backslash
  meta-commands consume the rest of the line, so trailing `-- comment` text
  was leaking into args (`\l: extra argument "list" ignored`,
  `\c: invalid integer value "to" for connection option "port"`). Moved
  every comment onto its own line above the meta-command.
- sql/02-joins/03-explain-analyze.sql: original predicate matched ~99% of
  rows, so the planner stayed on Seq Scan even after the index was created
  — the example claimed a plan flip that didn't happen. Strengthened to
  show wide-vs-narrow predicate side by side: same wide query before/after
  the index (still Seq Scan, still ~2.4 ms) plus a narrow-day query that
  flips to Index Scan in 0.019 ms. Now actually teaches the lesson.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: noahgift

crates/postgres-reports/benches/contract_assertions.rs

@@ -11,7 +11,9 @@ use criterion::{black_box, criterion_group, criterion_main, Criterion};
 // the asserts look at: a sorted, fixed-shape Vec with a numeric metric.
 
 fn synthetic_rows(n: usize) -> Vec<(i32, String, i64)> {
-    (0..n).map(|i| (i as i32 + 1, format!("NAME {i}"), (n - i) as i64)).collect()
+    (0..n)
+        .map(|i| (i as i32 + 1, format!("NAME {i}"), (n - i) as i64))
+        .collect()
 }
 
 fn check_invariants(rows: &[(i32, String, i64)]) {
@@ -31,9 +33,15 @@ fn bench_invariants(c: &mut Criterion) {
     let rows_100 = synthetic_rows(100);
     let rows_1000 = synthetic_rows(1000);
 
-    c.bench_function("invariants_10", |b| b.iter(|| check_invariants(black_box(&rows_10))));
-    c.bench_function("invariants_100", |b| b.iter(|| check_invariants(black_box(&rows_100))));
-    c.bench_function("invariants_1000", |b| b.iter(|| check_invariants(black_box(&rows_1000))));
+    c.bench_function("invariants_10", |b| {
+        b.iter(|| check_invariants(black_box(&rows_10)))
+    });
+    c.bench_function("invariants_100", |b| {
+        b.iter(|| check_invariants(black_box(&rows_100)))
+    });
+    c.bench_function("invariants_1000", |b| {
+        b.iter(|| check_invariants(black_box(&rows_1000)))
+    });
 }
 
 criterion_group!(benches, bench_invariants);

crates/postgres-reports/src/lib.rs

@@ -94,7 +94,10 @@ fn write_to_path(path: &Path, body: &str) -> Result<()> {
 fn assert_well_formed_json(body: &str) {
     let parsed: serde_json::Value =
         serde_json::from_str(body).expect("run-output: rendered JSON must parse");
-    assert!(parsed.is_array(), "run-output: rendered JSON must be an array");
+    assert!(
+        parsed.is_array(),
+        "run-output: rendered JSON must be an array"
+    );
     eprintln!("contract: run-output OK");
 }
 
@@ -247,42 +250,74 @@ pub async fn top_actors(pool: &PgPool, limit: i64) -> Result<Vec<TopActor>> {
 /// the row count matches the requested limit, the leading row's metric is
 /// non-trivial, and the metric is monotonically non-increasing.
 fn assert_topn_invariants<T>(rows: &[T], limit: usize, label: &str, metric: impl Fn(&T) -> i64) {
-    assert_eq!(rows.len(), limit, "{label}-row-count: expected {limit}, got {}", rows.len());
+    assert_eq!(
+        rows.len(),
+        limit,
+        "{label}-row-count: expected {limit}, got {}",
+        rows.len()
+    );
     eprintln!("contract: {label}-row-count OK");
 
-    assert!(metric(&rows[0]) >= 1, "{label}-top-nonzero: leading row metric must be >= 1");
+    assert!(
+        metric(&rows[0]) >= 1,
+        "{label}-top-nonzero: leading row metric must be >= 1"
+    );
     eprintln!("contract: {label}-top-nonzero OK");
 
     for w in rows.windows(2) {
-        assert!(metric(&w[0]) >= metric(&w[1]), "{label}-monotonic: ORDER BY DESC violated");
+        assert!(
+            metric(&w[0]) >= metric(&w[1]),
+            "{label}-monotonic: ORDER BY DESC violated"
+        );
     }
     eprintln!("contract: {label}-monotonic OK");
 }
 
 fn assert_contracts_customers(rows: &[TopCustomer], limit: usize) {
     assert_topn_invariants(rows, limit, "customers", |r| r.rental_count);
     for r in rows {
-        assert!(r.customer_id > 0, "customers-row-shape: customer_id must be positive (got {})", r.customer_id);
-        assert!(r.name.contains(' '), "customers-row-shape: name must be 'First Last' (got {:?})", r.name);
+        assert!(
+            r.customer_id > 0,
+            "customers-row-shape: customer_id must be positive (got {})",
+            r.customer_id
+        );
+        assert!(
+            r.name.contains(' '),
+            "customers-row-shape: name must be 'First Last' (got {:?})",
+            r.name
+        );
     }
     eprintln!("contract: customers-row-shape OK");
 }
 
 fn assert_contracts_films(rows: &[TopFilm], limit: usize) {
     assert_topn_invariants(rows, limit, "films", |r| r.rental_count);
     for r in rows {
-        assert!(r.film_id > 0, "films-row-shape: film_id must be positive (got {})", r.film_id);
-        assert!(!r.title.is_empty(), "films-row-shape: title must be non-empty");
+        assert!(
+            r.film_id > 0,
+            "films-row-shape: film_id must be positive (got {})",
+            r.film_id
+        );
+        assert!(
+            !r.title.is_empty(),
+            "films-row-shape: title must be non-empty"
+        );
     }
     eprintln!("contract: films-row-shape OK");
 }
 
 fn assert_contracts_actors(rows: &[TopActor], limit: usize) {
     assert_topn_invariants(rows, limit, "actors", |r| r.film_count);
     for r in rows {
-        assert!(r.actor_id > 0, "actors-row-shape: actor_id must be positive (got {})", r.actor_id);
-        assert!(!r.first_name.is_empty() && !r.last_name.is_empty(),
-                "actors-row-shape: first/last name must be non-empty");
+        assert!(
+            r.actor_id > 0,
+            "actors-row-shape: actor_id must be positive (got {})",
+            r.actor_id
+        );
+        assert!(
+            !r.first_name.is_empty() && !r.last_name.is_empty(),
+            "actors-row-shape: first/last name must be non-empty"
+        );
     }
     eprintln!("contract: actors-row-shape OK");
 }
@@ -292,13 +327,27 @@ mod tests {
     use super::*;
 
     fn customer(id: i32, name: &str, count: i64) -> TopCustomer {
-        TopCustomer { customer_id: id, name: name.into(), rental_count: count, email: None }
+        TopCustomer {
+            customer_id: id,
+            name: name.into(),
+            rental_count: count,
+            email: None,
+        }
     }
     fn film(id: i32, title: &str, count: i64) -> TopFilm {
-        TopFilm { film_id: id, title: title.into(), rental_count: count }
+        TopFilm {
+            film_id: id,
+            title: title.into(),
+            rental_count: count,
+        }
     }
     fn actor(id: i32, first: &str, last: &str, count: i64) -> TopActor {
-        TopActor { actor_id: id, first_name: first.into(), last_name: last.into(), film_count: count }
+        TopActor {
+            actor_id: id,
+            first_name: first.into(),
+            last_name: last.into(),
+            film_count: count,
+        }
     }
 
     #[test]
@@ -340,7 +389,10 @@ mod tests {
 
     #[test]
     fn films_contracts_pass_on_well_formed_rows() {
-        let rows = vec![film(1, "BUCKET BROTHERHOOD", 34), film(2, "ROCKETEER MOTHER", 33)];
+        let rows = vec![
+            film(1, "BUCKET BROTHERHOOD", 34),
+            film(2, "ROCKETEER MOTHER", 33),
+        ];
         assert_contracts_films(&rows, 2);
     }
 
@@ -376,7 +428,10 @@ mod tests {
 
     #[test]
     fn actors_contracts_pass_on_well_formed_rows() {
-        let rows = vec![actor(1, "GINA", "DEGENERES", 42), actor(2, "WALTER", "TORN", 41)];
+        let rows = vec![
+            actor(1, "GINA", "DEGENERES", 42),
+            actor(2, "WALTER", "TORN", 41),
+        ];
         assert_contracts_actors(&rows, 2);
     }
 
@@ -419,7 +474,10 @@ mod tests {
     #[tokio::test]
     async fn pool_returns_error_for_unreachable_url() {
         let result = pool("postgres://nobody@127.0.0.1:1/none").await;
-        assert!(result.is_err(), "unreachable URL must return Err, not panic");
+        assert!(
+            result.is_err(),
+            "unreachable URL must return Err, not panic"
+        );
     }
 
     #[test]
@@ -458,9 +516,18 @@ mod tests {
         std::fs::write(&blocker, "i am a file, not a directory").expect("seed blocker");
         let target = blocker.join("inner.json");
         let result = write_to_path(&target, "[]");
-        assert!(result.is_err(), "create_dir_all must fail under a regular file");
-        let msg = format!("{:?}", result.expect_err("create_dir_all should have failed"));
-        assert!(msg.contains("failed to create directory"), "unexpected error: {msg}");
+        assert!(
+            result.is_err(),
+            "create_dir_all must fail under a regular file"
+        );
+        let msg = format!(
+            "{:?}",
+            result.expect_err("create_dir_all should have failed")
+        );
+        assert!(
+            msg.contains("failed to create directory"),
+            "unexpected error: {msg}"
+        );
         std::fs::remove_file(&blocker).ok();
     }
 

crates/postgres-reports/src/main.rs

@@ -9,7 +9,11 @@ use clap::{Parser, ValueEnum};
 use postgres_reports::{pool, run, Report, RunOptions};
 
 #[derive(Parser, Debug)]
-#[command(name = "postgres-reports", version, about = "Sakila reports via sqlx + Postgres")]
+#[command(
+    name = "postgres-reports",
+    version,
+    about = "Sakila reports via sqlx + Postgres"
+)]
 struct Cli {
     #[arg(long, value_enum, default_value_t = ReportArg::Customers)]
     report: ReportArg,
@@ -20,8 +24,11 @@ struct Cli {
     #[arg(long)]
     out: Option<std::path::PathBuf>,
 
-    #[arg(long, env = "DATABASE_URL",
-          default_value = "postgres://postgres:postgres@localhost:5432/pagila")]
+    #[arg(
+        long,
+        env = "DATABASE_URL",
+        default_value = "postgres://postgres:postgres@localhost:5432/pagila"
+    )]
     database_url: String,
 }
 

crates/postgres-reports/tests/bin_smoke.rs

@@ -76,7 +76,10 @@ fn binary_errors_on_unreachable_database() {
         .env("DATABASE_URL", "postgres://nobody@127.0.0.1:1/none")
         .output()
         .expect("spawn binary");
-    assert!(!output.status.success(), "binary should fail with unreachable DB");
+    assert!(
+        !output.status.success(),
+        "binary should fail with unreachable DB"
+    );
 }
 
 #[test]

sql/01-fundamentals/01-connect.sql

@@ -1,7 +1,17 @@
 -- The first commands you run after `psql -d pagila`. Module 1.1.
-\l                    -- list databases
-\c pagila             -- connect to pagila
-\dt                   -- list tables in current database
-\d film               -- describe the film table
+-- Note: psql backslash commands consume the rest of the line, so put
+-- comments on their own line above each command — never trailing.
+
+-- list databases
+\l
+
+-- connect to pagila
+\c pagila
+
+-- list tables in current database
+\dt
+
+-- describe the film table
+\d film
 
 SELECT version();

sql/01-fundamentals/02-show-tables.sql

@@ -1,8 +1,16 @@
 -- The Postgres equivalents of MySQL's SHOW commands. Module 1.2.
-\dt                   -- list tables (\dt+ adds size, owner)
-\dn                   -- list schemas
-\du                   -- list roles (users + groups)
-\df                   -- list functions
+
+-- list tables (\dt+ adds size, owner)
+\dt
+
+-- list schemas
+\dn
+
+-- list roles (users + groups)
+\du
+
+-- list functions
+\df
 
 -- Information_schema is the SQL-standard alternative.
 SELECT table_name

sql/02-joins/03-explain-analyze.sql

@@ -1,15 +1,26 @@
 -- EXPLAIN (ANALYZE, BUFFERS) reveals what the planner actually did.
 -- Look for "Seq Scan" (full table) vs "Index Scan" / "Bitmap Heap Scan".
 
+-- Wide predicate: 16k rows, ~99% match. Even after we add the index,
+-- the planner stays on Seq Scan because reading the whole table
+-- sequentially is faster than chasing index pointers for that many rows.
 EXPLAIN (ANALYZE, BUFFERS)
 SELECT customer_id, COUNT(*) FROM rental
 WHERE rental_date >= '2022-04-01'
 GROUP BY customer_id;
 
--- Build an index, re-run, watch the plan flip.
 CREATE INDEX IF NOT EXISTS idx_rental_date ON rental (rental_date);
 
+-- Same query, post-index: still Seq Scan. The index didn't help here.
+-- Lesson: indexes earn their cost when the predicate is selective.
 EXPLAIN (ANALYZE, BUFFERS)
 SELECT customer_id, COUNT(*) FROM rental
 WHERE rental_date >= '2022-04-01'
 GROUP BY customer_id;
+
+-- Narrow predicate: a single day's worth of rentals (a few rows out of
+-- 16k). Now the plan flips to Index Scan / Bitmap Heap Scan and the
+-- index pays for itself.
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM rental
+WHERE rental_date BETWEEN '2022-05-25' AND '2022-05-26';