vouchington-tooling 0.86.0 → 0.86.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.86.0",
3
+ "version": "0.86.1",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -44,11 +44,13 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
44
44
  continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
45
45
  or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
46
46
  reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
47
- sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. No
48
- candidate pools: no capped or `MATERIALIZED` CTE over the listed entity that is filtered or
49
- limited afterward, no window loops or resume probes, no proof state in the cursor, and no
50
- runtime-config fields that exist only to cap a read. A page is never short or empty while
51
- `has_next_page` is true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
47
+ sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
48
+ simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
49
+ ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
50
+ `MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
51
+ or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
52
+ cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
53
+ with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
52
54
  memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
53
55
  list-read change against the plain single walk, not only against the base branch. See
54
56
  [`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
@@ -342,6 +342,9 @@ CROSS JOIN LATERAL (
342
342
  ) due;
343
343
  ```
344
344
 
345
+ This is a complex shape: keep it only with `EXPLAIN ANALYZE` plans showing it beats the plain
346
+ query.
347
+
345
348
  The loose scan beats a small thresholds table here because the intervals are chosen per row and
346
349
  there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
347
350
  thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
@@ -44,7 +44,8 @@ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
44
44
 
45
45
  Dispatchers, paged fan-out, and job-id deduplication follow
46
46
  [bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
47
- replaces holding a PostgreSQL transaction or advisory lock open across it; see
47
+ replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
48
+ used; see
48
49
  [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
49
50
 
50
51
  Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
@@ -30,7 +30,7 @@
30
30
  {
31
31
  "name": "bounded-iteration",
32
32
  "plugin": "vouchington-database",
33
- "pluginVersion": "0.10.0",
33
+ "pluginVersion": "0.11.0",
34
34
  "path": "bounded-iteration/SKILL.md"
35
35
  },
36
36
  {
@@ -81,7 +81,7 @@
81
81
  {
82
82
  "name": "glide-mq",
83
83
  "plugin": "vouchington-database",
84
- "pluginVersion": "0.10.0",
84
+ "pluginVersion": "0.11.0",
85
85
  "path": "glide-mq/SKILL.md"
86
86
  },
87
87
  {
@@ -127,19 +127,19 @@
127
127
  {
128
128
  "name": "postgres-node-performance-tuning",
129
129
  "plugin": "vouchington-database",
130
- "pluginVersion": "0.10.0",
130
+ "pluginVersion": "0.11.0",
131
131
  "path": "postgres-node-performance-tuning/SKILL.md"
132
132
  },
133
133
  {
134
134
  "name": "postgres-partitioning-uuid-v7",
135
135
  "plugin": "vouchington-database",
136
- "pluginVersion": "0.10.0",
136
+ "pluginVersion": "0.11.0",
137
137
  "path": "postgres-partitioning-uuid-v7/SKILL.md"
138
138
  },
139
139
  {
140
140
  "name": "postgres-schema-design",
141
141
  "plugin": "vouchington-database",
142
- "pluginVersion": "0.10.0",
142
+ "pluginVersion": "0.11.0",
143
143
  "path": "postgres-schema-design/SKILL.md"
144
144
  },
145
145
  {
@@ -11,6 +11,12 @@ Local policy overrides these defaults; do not reload an already-read adapter or
11
11
 
12
12
  Measure the query plan and the workload shape before changing code.
13
13
 
14
+ Owner's principle: "the basic premise is to use the simplest query, and making it more complex
15
+ requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
16
+ subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
17
+ it beats that simple query, not merely the previous version; see
18
+ [simplest query first](references/performance-patterns.md#simplest-query-first).
19
+
14
20
  - Select only the required columns.
15
21
  - Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
16
22
  the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
@@ -3,8 +3,8 @@
3
3
  Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
4
4
  Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
5
5
  transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
6
- Never hold a transaction, connection, or advisory lock across an external call; take a token lease
7
- in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
6
+ Never use advisory locks, and never hold a transaction or connection across an external call; take
7
+ a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
8
8
  renewal fails, and guard any write a stale owner could make with the token.
9
9
 
10
10
  For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
@@ -21,6 +21,19 @@ data, but it does not replace suitable local indexes or predicates that permit p
21
21
 
22
22
  ## Query shapes
23
23
 
24
+ ### Simplest query first
25
+
26
+ Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
27
+ entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
28
+ join, or subquery; then `ORDER BY` and `LIMIT`.
29
+
30
+ These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
31
+ query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
32
+ capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
33
+ fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
34
+ candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
35
+ continuation cursor is fine.
36
+
24
37
  Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
25
38
  `NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
26
39
  UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
@@ -32,7 +45,8 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
32
45
  The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
33
46
  reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
34
47
  `LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
35
- viewer-scoped set. Never use it as a candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
48
+ viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
49
+ candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
36
50
  cross-partition query. Choose the partition key from dominant access patterns; a hot reader
37
51
  of `RANGE (id)` needs an id or time bound.
38
52
 
@@ -98,7 +112,8 @@ count over its output. A restriction on a grouping column can still be pushed be
98
112
  so let the plan decide. Confirm from the
99
113
  plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
100
114
  base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
101
- restriction can reach inside the view. This works for an aggregate or `GROUP BY` view whose key is
115
+ restriction can reach inside the view. Reach for this only after the plan shows the simple
116
+ query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
102
117
  a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
103
118
  against the base tables instead. A plain join to the page is a join clause, not a restriction
104
119
  inside the view, so the planner can still build the whole aggregate first.
@@ -148,7 +163,9 @@ Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rat
148
163
  alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
149
164
  sequential-await lint only when each step consumes the previous step's result; a shared
150
165
  transaction client or lock ordering is not a data dependency. A lock that must be taken first
151
- stays a separate, earlier statement; never reorder or parallelize it. Audit every added suppression.
166
+ stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
167
+ because it exists: one that fails the lock rule in
168
+ [schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
152
169
 
153
170
  Correctness comes before round trips. Before folding a statement away, state the guarantee it
154
171
  gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
@@ -14,6 +14,13 @@ Local policy overrides these portable conventions.
14
14
  - Split differing shapes, share identical values, and keep history documents as JSON.
15
15
  - Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
16
16
  - Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
17
+ - No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
18
+ have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
19
+ concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
20
+ parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
21
+ effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
22
+ slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
23
+ deleting it, not by swapping in another serializer.
17
24
  - Reuse parameterized trigger functions instead of copying bodies.
18
25
  - Comment every table, column, and view; document reviewed exceptions explicitly.
19
26
 
@@ -29,7 +29,9 @@ Default to a queue job whose job id is the durable row id, enqueued after commit
29
29
  sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
30
30
  backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
31
31
  reason: legal or payment records, old values that vanish at commit, or an outcome that must
32
- commit with domain rows.
32
+ commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
33
+ for a cap; count up to the cap and write, as in the lock rule in
34
+ [schema design](../SKILL.md).
33
35
 
34
36
  When a table is justified, fence with one compare-and-set on the outcome or a generation
35
37
  (`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.