eugene 0.8.3

Careful with That Lock, Eugene
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

## {{#if passed_all_checks}}✅{{else}}❌{{/if}} Eugene trace report

{{#if name}}
Script name: `{{name}}`
{{/if}}

{{#unless skip_summary}}
This is a human-readable lock tracing and migration report generated by [eugene](https://github.com/kaaveland/eugene).
It can assist you in writing safer database migration scripts.

Here are some tips for reading it:

- A lock is called **dangerous** ❌ if it will cause concurrent queries to **wait** for the migration to complete
- You read that right, once a lock is acquired, it is only released at the end of the script
- Eugene will tell you what kinds of queries **dangerous** locks would block in a summary
- **Hints** can sometimes help you avoid dangerous locks, or hold them for a shorter time
- It is hard to avoid dangerous locks, but we should minimize time spent while holding them
- Sometimes seemingly fast migration scripts cause long outages because of lock queues,
  [here is an example scenario](https://kaveland.no/careful-with-that-lock-eugene.html)

There is a summary section for the entire script at the start of the report
and then a section for each statement in the script, that goes over the state of the database
at the time the script was executed, as well as effects or hints specific to that particular
statement.

### Overall Summary

| Started at | Total duration (ms) | Number of dangerous locks |
|------------|----------------------|--------------------------|
| {{start_time}} | {{total_duration_millis}} | {{dangerous_locks_count}} {{#if dangerous_locks_count gt 0 }}❌{{else}}✅{{/if}}|

  {{#unless all_locks_acquired}}
No locks acquired on database objects that already exist.
  {{else}}
#### All locks found
  {{#with all_locks_acquired}}
{{> locks_table_md}}
  {{/with}}
  {{/unless}}

  {{#if dangerous_locks_count gt 0}}
#### Dangerous locks found
    {{#each all_locks_acquired}}
      {{#if this.maybe_dangerous}}
- `{{this.mode}}` would block the following operations on `{{ this.schema }}.{{ this.object_name }}`:
        {{#each this.blocked_queries}}
  + `{{this}}`
        {{/each}}
      {{/if}}
    {{/each}}
  {{/if}}
{{/unless}}
{{#each statements}}

### {{#if this.triggered_rules}}❌{{else}}✅{{/if}} Statement number {{ this.statement_number_in_transaction}} for {{ this.duration_millis }}ms

```sql
{{this.sql}}
```

#### Locks at start

  {{#if this.locks_at_start}}
    {{#with this.locks_at_start}}
{{> locks_table_md}}
    {{/with}}
  {{else}}
No locks held at the start of this statement.
  {{/if}}

#### New locks taken

  {{#if this.new_locks_taken}}
    {{#with this.new_locks_taken}}
{{> locks_table_md}}
    {{/with}}
  {{else}}
No new locks taken by this statement.
  {{/if}}

  {{#if this.triggered_rules}}
#### Triggered rules
    {{#each this.triggered_rules}}

##### `{{this.id}}`: [{{this.name}}]({{this.url}})

{{this.help}}
    {{/each}}
  {{/if}}
{{/each}}