Merge pull request #61 from kaaveland/structured-hint-examples

Introduce structure to the examples and demo each lint

Cargo.toml

@@ -22,6 +22,9 @@ chrono = "0.4.38"
 itertools = "0.12.1"
 pg_query = "5.1.0"
 
+[dev-dependencies]
+rayon = "1.10.0"
+
 [dev-dependencies.uuid]
 version = "1.8.0"
 features = ["v4"]

README.md

@@ -257,14 +257,8 @@ where the table was created in the same transaction.
 
 ## Tests
 
-Tests are welcome and come in two flavors:
-
-1. Unit tests go in the same file as the code they test. They are allowed to use a database connection, corresponding
-   to the [docker-compose](https://github.com/kaaveland/eugene/blob/main/docker-compose.yml) setup or the 
-   [github workflow](https://github.com/kaaveland/eugene/blob/main/.github/workflows/run_tests.yml) for the tests  
-2. Integration tests go in the `tests` directory. These can only access public interfaces and therefore would the
-   the right place to gauge how dependents would see the tool. In particular, we take snapshots of markdown reports
-   that go in the examples directory, which we can use to track changes in the output format.
+Unit tests go in the same file as the code they test. They are allowed to use a database connection, corresponding
+to the [docker-compose](https://github.com/kaaveland/eugene/blob/main/docker-compose.yml) setup or the [github workflow](https://github.com/kaaveland/eugene/blob/main/.github/workflows/run_tests.yml) for the tests.
 
 ## Migration tool
 

examples/E1/bad/1.sql

@@ -0,0 +1 @@
+create table authors(id integer generated always as identity primary key, name text);

examples/E1/bad/2.sql

@@ -0,0 +1,2 @@
+set local lock_timeout = '2s';
+alter table authors add constraint name_not_null check (name is not null);

examples/E1/bad_lint.md

@@ -0,0 +1,51 @@
+# Eugene 🔒 lint report of `examples/E1/bad/1.sql`
+
+This is a human readable SQL script safety report generated by [eugene](https://github.com/kaaveland/eugene). Keep in mind that lints can be ignored by adding a `-- eugene: ignore E123` comment to the SQL statement or by passing --ignore E123 on the command line.
+
+The migration script passed all the checks ✅
+
+## Statement number 1
+
+### SQL
+
+```sql
+create table authors(id integer generated always as identity primary key, name text)
+```
+
+No checks matched for this statement. ✅
+
+
+# Eugene 🔒 lint report of `examples/E1/bad/2.sql`
+
+This is a human readable SQL script safety report generated by [eugene](https://github.com/kaaveland/eugene). Keep in mind that lints can be ignored by adding a `-- eugene: ignore E123` comment to the SQL statement or by passing --ignore E123 on the command line.
+
+The migration script did not pass all the checks ❌
+
+## Statement number 1
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+No checks matched for this statement. ✅
+
+## Statement number 2
+
+### SQL
+
+```sql
+alter table authors add constraint name_not_null check (name is not null)
+```
+
+### Lints
+
+#### Validating table with a new constraint
+
+ID: `E1`
+
+A new constraint was added and it is already `VALID`. This blocks all table access until all rows are validated. A safer way is: Add the constraint as `NOT VALID` and validate it with `ALTER TABLE ... VALIDATE CONSTRAINT` later.
+
+Statement takes `AccessExclusiveLock` on `public.authors`, blocking reads until constraint `name_not_null` is validated
+

examples/E1/bad_trace.md

@@ -0,0 +1,67 @@
+# Eugene 🔒 trace report of `examples/E1/bad/1.sql`
+
+## Statement number 1 for 10 ms
+
+### SQL
+
+```sql
+create table authors(id integer generated always as identity primary key, name text)
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+
+
+# Eugene 🔒 trace report of `examples/E1/bad/2.sql`
+
+## Statement number 1 for 10 ms
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+
+## Statement number 2 for 10 ms
+
+### SQL
+
+```sql
+alter table authors add constraint name_not_null check (name is not null)
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+| Schema | Object | Mode | Relkind | OID | Safe |
+|--------|--------|------|---------|-----|------|
+| `public` | `authors` | `AccessExclusiveLock` | Table | 1 | ❌ |
+
+### Hints
+
+#### Validating table with a new constraint
+
+ID: `E1`
+
+A new constraint was added and it is already `VALID`. This blocks all table access until all rows are validated. A safer way is: Add the constraint as `NOT VALID` and validate it with `ALTER TABLE ... VALIDATE CONSTRAINT` later.
+
+A new constraint `name_not_null` of type `CHECK` was added to the table `public.authors` as `VALID`. Constraints that are `NOT VALID` can be made `VALID` by `ALTER TABLE public.authors VALIDATE CONSTRAINT name_not_null` which takes a lesser lock.
+

examples/E1/good/1.sql

@@ -0,0 +1 @@
+create table authors(id integer generated always as identity primary key, name text);

examples/E1/good/2.sql

@@ -0,0 +1,2 @@
+set local lock_timeout = '2s';
+alter table authors add constraint name_not_null check (name is not null) not valid;

examples/E1/good/3.sql

@@ -0,0 +1,2 @@
+set local lock_timeout = '2s';
+alter table authors validate constraint name_not_null;

examples/E1/good_lint.md

@@ -0,0 +1,70 @@
+# Eugene 🔒 lint report of `examples/E1/good/1.sql`
+
+This is a human readable SQL script safety report generated by [eugene](https://github.com/kaaveland/eugene). Keep in mind that lints can be ignored by adding a `-- eugene: ignore E123` comment to the SQL statement or by passing --ignore E123 on the command line.
+
+The migration script passed all the checks ✅
+
+## Statement number 1
+
+### SQL
+
+```sql
+create table authors(id integer generated always as identity primary key, name text)
+```
+
+No checks matched for this statement. ✅
+
+
+# Eugene 🔒 lint report of `examples/E1/good/2.sql`
+
+This is a human readable SQL script safety report generated by [eugene](https://github.com/kaaveland/eugene). Keep in mind that lints can be ignored by adding a `-- eugene: ignore E123` comment to the SQL statement or by passing --ignore E123 on the command line.
+
+The migration script passed all the checks ✅
+
+## Statement number 1
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+No checks matched for this statement. ✅
+
+## Statement number 2
+
+### SQL
+
+```sql
+alter table authors add constraint name_not_null check (name is not null) not valid
+```
+
+No checks matched for this statement. ✅
+
+
+# Eugene 🔒 lint report of `examples/E1/good/3.sql`
+
+This is a human readable SQL script safety report generated by [eugene](https://github.com/kaaveland/eugene). Keep in mind that lints can be ignored by adding a `-- eugene: ignore E123` comment to the SQL statement or by passing --ignore E123 on the command line.
+
+The migration script passed all the checks ✅
+
+## Statement number 1
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+No checks matched for this statement. ✅
+
+## Statement number 2
+
+### SQL
+
+```sql
+alter table authors validate constraint name_not_null
+```
+
+No checks matched for this statement. ✅
+

examples/E1/good_trace.md

@@ -0,0 +1,94 @@
+# Eugene 🔒 trace report of `examples/E1/good/1.sql`
+
+## Statement number 1 for 10 ms
+
+### SQL
+
+```sql
+create table authors(id integer generated always as identity primary key, name text)
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+
+
+# Eugene 🔒 trace report of `examples/E1/good/2.sql`
+
+## Statement number 1 for 10 ms
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+
+## Statement number 2 for 10 ms
+
+### SQL
+
+```sql
+alter table authors add constraint name_not_null check (name is not null) not valid
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+| Schema | Object | Mode | Relkind | OID | Safe |
+|--------|--------|------|---------|-----|------|
+| `public` | `authors` | `AccessExclusiveLock` | Table | 1 | ❌ |
+
+
+# Eugene 🔒 trace report of `examples/E1/good/3.sql`
+
+## Statement number 1 for 10 ms
+
+### SQL
+
+```sql
+set local lock_timeout = '2s'
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+
+## Statement number 2 for 10 ms
+
+### SQL
+
+```sql
+alter table authors validate constraint name_not_null
+```
+
+### Locks at start
+
+No locks held at the start of this statement.
+
+### New locks taken
+
+No new locks taken by this statement.
+
+

examples/E10/bad/1.sql

@@ -0,0 +1,2 @@
+create table prices (id integer generated always as identity primary key, price int not null);
+create table authors (id integer generated always as identity primary key, name text not null);