vouchington-tooling 2.0.2 → 3.0.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 +2 -2
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/manifest.json +15 -202
- package/skills/organize-github-issues/SKILL.md +20 -3
- package/skills/pr-description/SKILL.md +9 -65
- package/skills/retrospective/SKILL.md +16 -1
- package/skills/retrospective-distill/SKILL.md +1 -1
- package/skills/retrospective-distill/references/issue-body.md +6 -1
- package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
- package/skills/triage-loop/SKILL.md +111 -34
- package/skills/triage-prs/SKILL.md +26 -28
- package/skills/triage-prs/references/feedback.md +14 -2
- package/skills/triage-prs/references/rubric.md +4 -4
- package/skills/triage-sweep/SKILL.md +26 -23
- package/skills/agent-workflow/SKILL.md +0 -72
- package/skills/agent-workflow/references/evidence-sweep.md +0 -12
- package/skills/agent-workflow/references/four-refs.md +0 -74
- package/skills/agent-workflow/references/implementation-and-review.md +0 -4
- package/skills/agent-workflow/references/implementation.md +0 -20
- package/skills/agent-workflow/references/review-response.md +0 -49
- package/skills/agent-workflow/references/review.md +0 -10
- package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
- package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
- package/skills/bounded-iteration/SKILL.md +0 -92
- package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
- package/skills/dependabot/SKILL.md +0 -117
- package/skills/dotnet-test-authoring/SKILL.md +0 -24
- package/skills/git-commit-checklist/SKILL.md +0 -29
- package/skills/github-actions-authoring/SKILL.md +0 -63
- package/skills/github-actions-checklist/SKILL.md +0 -118
- package/skills/github-issue/SKILL.md +0 -121
- package/skills/glide-mq/SKILL.md +0 -52
- package/skills/glide-mq/references/lease-patterns.md +0 -44
- package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
- package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
- package/skills/npm-publishing/SKILL.md +0 -72
- package/skills/package-json-checklist/SKILL.md +0 -31
- package/skills/planning/SKILL.md +0 -37
- package/skills/planning/references/impact-discovery.md +0 -11
- package/skills/playwright-authoring/SKILL.md +0 -23
- package/skills/playwright-authoring/references/browser-reliability.md +0 -9
- package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
- package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
- package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
- package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
- package/skills/postgres-schema-design/SKILL.md +0 -31
- package/skills/postgres-schema-design/references/naming.md +0 -34
- package/skills/postgres-schema-design/references/relations.md +0 -66
- package/skills/postgres-schema-design/references/table-shapes.md +0 -78
- package/skills/pr-description/references/examples.md +0 -189
- package/skills/review-ci-logs/SKILL.md +0 -44
- package/skills/revisit-followups/SKILL.md +0 -47
- package/skills/stacked-prs/SKILL.md +0 -98
- package/skills/stacked-prs/references/drain.md +0 -177
- package/skills/stacked-prs/references/gh-stack.md +0 -147
- package/skills/static-analysis-checklist/SKILL.md +0 -32
- package/skills/storybook-authoring/SKILL.md +0 -22
- package/skills/storybook-authoring/references/component-coverage.md +0 -9
- package/skills/swift-test-authoring/SKILL.md +0 -23
- package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
- package/skills/test-authoring/SKILL.md +0 -27
- package/skills/test-authoring/references/core-practice.md +0 -16
- package/skills/test-authoring/references/dependency-boundaries.md +0 -38
- package/skills/test-authoring/references/tautological-tests.md +0 -47
- package/skills/triage-loop/references/shepherd.md +0 -64
- package/skills/vitest-test-authoring/SKILL.md +0 -22
- package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
|
@@ -1,72 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: npm-publishing
|
|
3
|
-
description: Prepare npm bootstrap and trusted publishing commands for a human.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# npm publishing bootstrap
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/npm-publishing/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Prepare the local package. Leave public registry writes and trusted-publisher mutations to the
|
|
13
|
-
human. Read every applicable `AGENTS.md` from the repository root through the
|
|
14
|
-
package. Repository-local policy and the consumer wrapper own the package path and name, npm scope,
|
|
15
|
-
GitHub repository, release workflow, build commands, and whether a laptop may publish.
|
|
16
|
-
|
|
17
|
-
## Prepare the package
|
|
18
|
-
|
|
19
|
-
- Resolve the absolute repository root, the package directory relative to that root, the exact npm
|
|
20
|
-
package name, `owner/repository`, and the release workflow filename. The workflow value is the
|
|
21
|
-
case-sensitive filename under `.github/workflows`, not a path. Leave no placeholders in the final
|
|
22
|
-
commands.
|
|
23
|
-
- Confirm npm 11.15 or newer, account-level two-factor authentication, and write access to the
|
|
24
|
-
package or scope.
|
|
25
|
-
- On the default branch, the workflow must grant `id-token: write`, use a supported runner, install
|
|
26
|
-
an npm version that can trusted-publish, and publish this package.
|
|
27
|
-
- When the package does not exist in the registry, create the smallest useful stub in its intended
|
|
28
|
-
directory. Follow neighboring packages for metadata, source, exports, types, license, README,
|
|
29
|
-
build output, and workspace registration.
|
|
30
|
-
- Do not replace an existing module with a stub. Do not publish a version already in the registry.
|
|
31
|
-
- Build the package, then inspect the payload with
|
|
32
|
-
`npm publish <package-directory> --access public --dry-run`. Stop if it includes secrets,
|
|
33
|
-
environment files, source maps, unrelated workspace files, or a missing runtime or type
|
|
34
|
-
entrypoint. The dry run must include `prepublishOnly`. A pack-only check misses that script.
|
|
35
|
-
- If the package already exists, have the human run `npm trust list <package-name>` before any
|
|
36
|
-
mutation. Omit the initial publish command. If trust already exists, report it and omit trust
|
|
37
|
-
creation. Do not revoke or replace it.
|
|
38
|
-
|
|
39
|
-
## Hand off the mutations
|
|
40
|
-
|
|
41
|
-
- Do not run a real `npm publish` or a mutating `npm trust` subcommand.
|
|
42
|
-
- Say that the first command creates an externally visible, effectively irreversible package
|
|
43
|
-
version, and the second grants the named workflow publish authority.
|
|
44
|
-
- Include the publish command only when bootstrapping a package that does not exist. An existing
|
|
45
|
-
package with an empty trust list goes straight to trust setup.
|
|
46
|
-
- Tell the human to append a current one-time password after each final `--otp=` and not to share
|
|
47
|
-
or record it. Warn that `--otp=` can expose the OTP in shell history and process arguments, and
|
|
48
|
-
to follow local secret-handling policy.
|
|
49
|
-
- Give the applicable commands with resolved values, in this order:
|
|
50
|
-
|
|
51
|
-
```sh
|
|
52
|
-
cd /absolute/repository/root
|
|
53
|
-
npm publish ./relative/package-directory --access public --otp=
|
|
54
|
-
npm trust github @scope/package \
|
|
55
|
-
--repo owner/repository \
|
|
56
|
-
--file release.yml \
|
|
57
|
-
--allow-publish \
|
|
58
|
-
--yes \
|
|
59
|
-
--otp=
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
- The `cd` target is the directory from which the relative publish path resolves.
|
|
63
|
-
- If local policy prohibits publishing from this machine, say so and name the approved environment.
|
|
64
|
-
Keep the same command order.
|
|
65
|
-
- Ask the human to confirm the payload, package name, repository, workflow filename, and publish
|
|
66
|
-
permission immediately before running the commands.
|
|
67
|
-
- Afterward, have the human verify any newly published version and run `npm trust list` again.
|
|
68
|
-
- Do not retry an authorization or registry failure blindly. Do not fall back to a long-lived npm
|
|
69
|
-
token without explicit direction.
|
|
70
|
-
|
|
71
|
-
Consumer wrapper owns: package path and name, npm scope, GitHub repository, release workflow, build
|
|
72
|
-
commands, and whether a laptop may publish.
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: package-json-checklist
|
|
3
|
-
description: Check package metadata, dependencies, entrypoints, and lockfiles.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Package metadata checklist
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/package-json-checklist/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use before changing `package.json`, a lockfile, workspace metadata, or a package entrypoint. Read
|
|
13
|
-
every applicable `AGENTS.md` from the repository root through the owning package,
|
|
14
|
-
applying the closest file only when rules conflict. Those instructions own package-manager version,
|
|
15
|
-
dependency age/version policy, registry, release process, and package layout.
|
|
16
|
-
|
|
17
|
-
1. Identify the owning package and every consumer of the changed script, dependency, export, or
|
|
18
|
-
binary. Prefer existing workspace utilities before adding a dependency.
|
|
19
|
-
2. Use the repository's package manager for dependency changes. Update the lockfile when it records
|
|
20
|
-
the affected metadata; avoid lockfile churn for metadata-only edits it does not record. Keep
|
|
21
|
-
peer,
|
|
22
|
-
optional, development, and runtime dependencies in their intended sections.
|
|
23
|
-
3. For a published package, verify exports, types, files, binaries, and build output match the
|
|
24
|
-
package's supported import and installation paths.
|
|
25
|
-
4. Run the package manager's integrity check, focused tests, typecheck, build, and local policy
|
|
26
|
-
checks required by the affected package. Do not publish or alter registry state without explicit
|
|
27
|
-
authorization.
|
|
28
|
-
5. Review the lockfile and generated metadata for unrelated churn before committing.
|
|
29
|
-
|
|
30
|
-
Local instructions or the consumer wrapper own: version range, workspace topology, registry,
|
|
31
|
-
package-manager command, and release convention.
|
package/skills/planning/SKILL.md
DELETED
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: planning
|
|
3
|
-
description: Plan a repository change and save the decision outside Git.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Planning
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/planning/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use when a task needs a plan. Scale detail to uncertainty and impact; no fixed headings, tables,
|
|
13
|
-
diagram, independent reviewer, or separate issue are required by this skill.
|
|
14
|
-
|
|
15
|
-
1. State the desired outcome and compare no change, reuse, and alternative approaches. Choose the
|
|
16
|
-
smallest durable option; ask before treating an unresolved product choice as settled.
|
|
17
|
-
2. Read applicable instructions, documentation, current code, tests, and recent changes from a
|
|
18
|
-
fresh base. Record which evidence supports each proposed path.
|
|
19
|
-
3. Map affected owners, contracts, operational boundaries, and tests. Use independent review or
|
|
20
|
-
exploration when the change is cross-cutting or uncertain and local policy calls for it.
|
|
21
|
-
4. Record the chosen approach, steps, validation, and unresolved decisions. Mark which steps run
|
|
22
|
-
concurrently and name the dependency that serializes each remaining step. Add rollout details
|
|
23
|
-
only when an established deployment contract requires them.
|
|
24
|
-
5. Save the plan once outside Git: an existing issue, a PR description, or a durable native plan
|
|
25
|
-
file outside the repository. Do not commit task plans or count temporary scratch files as saved
|
|
26
|
-
plans. If no durable record is available, use an issue through the local issue workflow. Link
|
|
27
|
-
the record from the handoff instead of duplicating it. When creating a plan issue from a source issue
|
|
28
|
-
that already has a milestone or project, apply that same existing milestone or project through
|
|
29
|
-
[github-issue](../github-issue/SKILL.md).
|
|
30
|
-
|
|
31
|
-
For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
|
|
32
|
-
tests or concluding that a surface has no dependents.
|
|
33
|
-
|
|
34
|
-
On a `/plan` comment, the triage loop's subagent drafts the plan, the loop asks the human its
|
|
35
|
-
open questions, then posts the plan on the source issue or PR as the durable record.
|
|
36
|
-
|
|
37
|
-
Consumer wrapper owns: durable plan storage, repository, taxonomy, discovery tools, and approval.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
# Impact discovery
|
|
2
|
-
|
|
3
|
-
Start from the changed surface and trace imports, callers, configuration, generated artifacts, and
|
|
4
|
-
tests. Use the repository's graph or search tools where available; otherwise record the evidence
|
|
5
|
-
used and the uncertainty that remains. Select focused tests from real dependents, then include
|
|
6
|
-
broader validation when a shared contract, package boundary, or generated artifact changes.
|
|
7
|
-
|
|
8
|
-
Check source-issue paths against current source before relying on them; issue text is a snapshot.
|
|
9
|
-
|
|
10
|
-
Do not treat a tool's incomplete graph as proof that no dependent exists. Escalate uncertain
|
|
11
|
-
high-risk boundaries for independent review or a broader test selection.
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: playwright-authoring
|
|
3
|
-
description: Author reliable Playwright flows, fixtures, and assertions.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Playwright authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/playwright-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Apply [test-authoring](../test-authoring/SKILL.md).
|
|
13
|
-
|
|
14
|
-
- Use a stable, accessible locator. Assert a user-observable outcome.
|
|
15
|
-
- Establish data, authentication, and server state through a supported fixture or API.
|
|
16
|
-
- Do not rely on test order or an arbitrary wait.
|
|
17
|
-
- Keep each scenario independently repeatable. Use an auto-waiting assertion. Capture diagnostics
|
|
18
|
-
on failure.
|
|
19
|
-
- Use the browser for a real browser interaction. Do not repeat a unit test there.
|
|
20
|
-
- Read [browser reliability](references/browser-reliability.md) for locator, waiting, state, and
|
|
21
|
-
network rules.
|
|
22
|
-
|
|
23
|
-
Consumer wrapper owns: environments, credentials, personas, fixtures, and suite commands.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# Browser reliability
|
|
2
|
-
|
|
3
|
-
Use the browser only for browser-owned behavior. Prefer stable accessibility or test-id locators,
|
|
4
|
-
scope repeated content, and assert visible outcomes. Never use arbitrary sleeps; wait for a precise
|
|
5
|
-
URL, request, response, DOM state, or user-visible completion signal.
|
|
6
|
-
|
|
7
|
-
Seed deterministic data and establish authentication through supported fixtures. Mock network only
|
|
8
|
-
for third-party behavior, fault injection, streaming, or conditions impossible to seed. Register
|
|
9
|
-
response waits before triggering mutations, and make each scenario independent of prior state.
|
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: postgres-node-performance-tuning
|
|
3
|
-
description: Measure and improve PostgreSQL queries in Node.js services.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# PostgreSQL and Node.js performance
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/postgres-node-performance-tuning/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Measure the query plan and the workload shape before changing code.
|
|
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
|
-
|
|
20
|
-
- Select only the required columns.
|
|
21
|
-
- Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
|
|
22
|
-
the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
|
|
23
|
-
- Batch writes inside an explicit transaction limit.
|
|
24
|
-
- Keep connection-pool usage bounded.
|
|
25
|
-
- Validate a query change at representative cardinality. Watch latency, memory, lock time, and
|
|
26
|
-
connection pressure together.
|
|
27
|
-
- Cut round trips without weakening correctness: fold dependent reads, batch per-item lookups, and
|
|
28
|
-
overlap independent reads; see
|
|
29
|
-
[round trips](references/performance-patterns.md#round-trips).
|
|
30
|
-
- Read the plan for hidden per-row work before trusting a change; see
|
|
31
|
-
[reading plans](references/reading-plans.md).
|
|
32
|
-
- Read [performance patterns](references/performance-patterns.md) before changing a high-volume
|
|
33
|
-
path.
|
|
34
|
-
|
|
35
|
-
Consumer wrapper owns: schema ownership, operational thresholds, pooling configuration, and rollout.
|
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
# Performance patterns
|
|
2
|
-
|
|
3
|
-
Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
|
|
4
|
-
Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
|
|
5
|
-
transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
|
|
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
|
-
renewal fails, and guard any write a stale owner could make with the token.
|
|
9
|
-
|
|
10
|
-
For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
|
|
11
|
-
For writes, prefer set-based batches such as UNNEST or COPY when they preserve validation and error
|
|
12
|
-
handling. Do large list diffs and dedupes in the worker as a streaming comparison of sorted
|
|
13
|
-
inputs, not as writer-side set operations. Measure query plans with representative cardinality
|
|
14
|
-
before changing an index or query. Adding an index for a measured plan is a default: do not ask
|
|
15
|
-
first and do not make it a spec stop condition.
|
|
16
|
-
|
|
17
|
-
Check query predicates, joins, ordering, and selected columns against index shape. Use EXPLAIN
|
|
18
|
-
evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
|
|
19
|
-
correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
|
|
20
|
-
data, but it does not replace suitable local indexes or predicates that permit pruning.
|
|
21
|
-
|
|
22
|
-
## Query shapes
|
|
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
|
-
|
|
37
|
-
Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
|
|
38
|
-
`NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
|
|
39
|
-
UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
|
|
40
|
-
Read and return tables with explicit columns: no `SELECT *`, `alias.*`, or `RETURNING *`.
|
|
41
|
-
A view may use `*` when its reviewed column list is the reader contract.
|
|
42
|
-
|
|
43
|
-
Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CTE, not
|
|
44
|
-
`OFFSET 0`. The fence keeps the outer query's filters and ordering away from the CTE's indexes.
|
|
45
|
-
The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
|
|
46
|
-
reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
|
|
47
|
-
`LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
|
|
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
|
|
50
|
-
cross-partition query. Choose the partition key from dominant access patterns; a hot reader
|
|
51
|
-
of `RANGE (id)` needs an id or time bound.
|
|
52
|
-
|
|
53
|
-
For a `RANGE (id)` child read by parent id, a shared lower-bound helper equivalent to
|
|
54
|
-
`id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` prunes earlier
|
|
55
|
-
partitions; the overlap allows clock skew. It is safe only when every writer sets the parent at
|
|
56
|
-
insert to an existing parent, never re-points it to a newer parent, and nothing mints child ids
|
|
57
|
-
from a historical time; see
|
|
58
|
-
[parent lower bound](../../postgres-partitioning-uuid-v7/references/partition-lifecycle.md#parent-lower-bound).
|
|
59
|
-
Rate limits query an actor-keyed table rather than
|
|
60
|
-
recipient-keyed fan-out rows. Verify actual pruning with EXPLAIN.
|
|
61
|
-
|
|
62
|
-
Generic `jonathanong/no-mistakes` checks include `postgres-no-offset`; inspect available rules
|
|
63
|
-
and configure reviewed cross-partition exceptions rather than treating a rule as plan evidence.
|
|
64
|
-
|
|
65
|
-
## Volatile functions in predicates
|
|
66
|
-
|
|
67
|
-
`uuidv7(interval)` and `random()` are volatile: PostgreSQL evaluates them for every row, so
|
|
68
|
-
`WHERE id >= uuidv7(INTERVAL '-30 days')` is a `Filter`, cannot be an `Index Cond`, and blocks
|
|
69
|
-
partition pruning. Compute the bound once per statement and compare against that. A bind
|
|
70
|
-
parameter works, as does a stable expression such as `now() - INTERVAL '30 days'` fed to a stable
|
|
71
|
-
or immutable bound helper. A stable bound can be an index condition, and a partitioned table
|
|
72
|
-
prunes at executor start. Confirm `Index Cond` and `Subplans Removed` in the plan.
|
|
73
|
-
|
|
74
|
-
```sql
|
|
75
|
-
-- evaluated per row
|
|
76
|
-
SELECT id FROM events WHERE id >= uuidv7(INTERVAL '-30 days');
|
|
77
|
-
-- bound computed once by the caller
|
|
78
|
-
SELECT id FROM events WHERE id >= $1;
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## Function inlining
|
|
82
|
-
|
|
83
|
-
PostgreSQL inlines a simple scalar SQL function into the calling query, so its body is planned
|
|
84
|
-
with the outer query and its predicates can become index conditions. A SQL function whose body
|
|
85
|
-
contains a subquery (for example `EXISTS`) is never inlined as a scalar call; a set-returning SQL
|
|
86
|
-
function in `FROM` follows a separate inlining path. Functions with `SECURITY DEFINER` or
|
|
87
|
-
a `SET` clause, and PL/pgSQL functions, are not inlined either, nor is a body that is not a single
|
|
88
|
-
simple expression. When the function is not inlined, the plan shows only `fn_x(col)` in a `Filter`
|
|
89
|
-
or output, and none of the queries it runs per row.
|
|
90
|
-
|
|
91
|
-
```sql
|
|
92
|
-
-- not inlined: the EXISTS runs once per orders row
|
|
93
|
-
CREATE FUNCTION fn_has_events(order_id uuid) RETURNS boolean
|
|
94
|
-
LANGUAGE sql STABLE AS $$ SELECT EXISTS (SELECT 1 FROM events e WHERE e.order_id = $1) $$;
|
|
95
|
-
SELECT id FROM orders WHERE fn_has_events(id);
|
|
96
|
-
-- plannable: write the semi-join in the query
|
|
97
|
-
SELECT o.id FROM orders o WHERE EXISTS (SELECT 1 FROM events e WHERE e.order_id = o.id);
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Tell from the plan: a function name in `Filter` or output with no matching scan nodes. Count calls
|
|
101
|
-
with `SET LOCAL track_functions = 'all'` and `pg_stat_xact_user_functions` in the same transaction;
|
|
102
|
-
inlined functions are not counted. See [reading plans](reading-plans.md#opaque-function-calls).
|
|
103
|
-
Put per-row logic in the query as a join or `EXISTS`, or keep the function a plain expression.
|
|
104
|
-
|
|
105
|
-
## Reading views by key
|
|
106
|
-
|
|
107
|
-
PostgreSQL expands a view into the calling query, and a simple view lets the outer filter push
|
|
108
|
-
down into its base tables. A view that cannot be flattened (aggregation, `DISTINCT`, `LIMIT`,
|
|
109
|
-
set operations, window functions, volatile target-list expressions, a security barrier) is built
|
|
110
|
-
before a filter on a value it derives (such as an aggregate) applies, and before a sort, page, or
|
|
111
|
-
count over its output. A restriction on a grouping column can still be pushed below an aggregate,
|
|
112
|
-
so let the plan decide. Confirm from the
|
|
113
|
-
plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
|
|
114
|
-
base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
|
|
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
|
|
117
|
-
a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
|
|
118
|
-
against the base tables instead. A plain join to the page is a join clause, not a restriction
|
|
119
|
-
inside the view, so the planner can still build the whole aggregate first.
|
|
120
|
-
|
|
121
|
-
```sql
|
|
122
|
-
-- order_summaries aggregates events, so event_count is built for every order, then filtered
|
|
123
|
-
SELECT * FROM order_summaries WHERE event_count > 3 ORDER BY id LIMIT 50;
|
|
124
|
-
-- choose ids from base tables with an equivalent predicate, then read the view by key
|
|
125
|
-
WITH page AS (
|
|
126
|
-
SELECT o.id FROM orders o
|
|
127
|
-
WHERE (SELECT count(*) FROM events e WHERE e.order_id = o.id) > 3
|
|
128
|
-
ORDER BY o.id LIMIT 50
|
|
129
|
-
)
|
|
130
|
-
SELECT s.id, s.total_cents, s.event_count
|
|
131
|
-
FROM page
|
|
132
|
-
CROSS JOIN LATERAL (
|
|
133
|
-
SELECT * FROM order_summaries WHERE id = page.id
|
|
134
|
-
) s
|
|
135
|
-
ORDER BY s.id;
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
Filter and sort on indexed base-table columns, and read only the view columns the page needs.
|
|
139
|
-
Confirm in the plan that the view's inner nodes run with `Actual Loops` equal to the page size and
|
|
140
|
-
read only that page's rows.
|
|
141
|
-
|
|
142
|
-
## Round trips
|
|
143
|
-
|
|
144
|
-
Sequential queries can add network round trips when the client waits between statements, and planning
|
|
145
|
-
can add latency when PostgreSQL does not reuse a prepared plan; count round trips per request before
|
|
146
|
-
tuning individual statements.
|
|
147
|
-
|
|
148
|
-
Load a parent and the viewer's relation to it in one query: join the membership row, or use a
|
|
149
|
-
lateral subquery, rather than reading the parent and then the relation.
|
|
150
|
-
|
|
151
|
-
`Promise.all` over statements on one transaction client is still serial, because one connection
|
|
152
|
-
runs one statement at a time. Merge them instead: CTEs, `UNNEST`, or one multi-row statement.
|
|
153
|
-
|
|
154
|
-
Write the batch implementation first: it takes an array of keys and returns a keyed map. The
|
|
155
|
-
single-item function is a thin wrapper over it (`addUrl(url)` calls `addUrls([url])`), with no
|
|
156
|
-
parallel per-item SQL path, for lookups and mutations alike. The batch must give a one-item array the
|
|
157
|
-
same atomicity, partial-failure, ordering, duplicate-key, and result-shape semantics as the single
|
|
158
|
-
call; if it doesn't, fix the batch rather than keep a per-item path. Call the batch from loops, `.map`
|
|
159
|
-
callbacks, and `Promise.all` fan-outs. `no-await-in-loop` misses a helper that queries internally
|
|
160
|
-
and `Promise.all(items.map(helper))`; review those call sites by hand.
|
|
161
|
-
|
|
162
|
-
Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rate-limiter check
|
|
163
|
-
alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
|
|
164
|
-
sequential-await lint only when each step consumes the previous step's result; a shared
|
|
165
|
-
transaction client or lock ordering is not a data dependency. A lock that must be taken first
|
|
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.
|
|
169
|
-
|
|
170
|
-
Correctness comes before round trips. Before folding a statement away, state the guarantee it
|
|
171
|
-
gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
|
|
172
|
-
inside a `FOR UPDATE` statement reads a snapshot taken before the lock wait, so it can be stale.
|
|
173
|
-
|
|
174
|
-
Run a symmetric check, such as "is either party blocking the other", as one query with an `OR`
|
|
175
|
-
or both-direction predicate, not twice with the arguments swapped.
|
|
@@ -1,111 +0,0 @@
|
|
|
1
|
-
# Reading plans
|
|
2
|
-
|
|
3
|
-
Run `EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON)` at representative cardinality, in a transaction you
|
|
4
|
-
roll back when the statement writes. `ANALYZE` executes the statement, and a rollback does not
|
|
5
|
-
undo non-transactional effects such as sequence advancement from `nextval()`. Calls that reach
|
|
6
|
-
outside the database (requests, messages) still happen even in a disposable database, so use plain
|
|
7
|
-
`EXPLAIN` for statements that trigger them, or disable the integrations first. A glance at the top node hides most of the problems below;
|
|
8
|
-
walk every node. `VERBOSE` adds each node's `Output` expressions, which is where a select-list
|
|
9
|
-
function call shows. In JSON, `Actual Rows`, `Actual Startup Time`, `Actual Total Time`,
|
|
10
|
-
`Rows Removed by Filter`, `Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` are
|
|
11
|
-
per-loop averages, so multiply each by `Actual Loops` for the total.
|
|
12
|
-
|
|
13
|
-
## Red flags
|
|
14
|
-
|
|
15
|
-
### Rows read per row returned
|
|
16
|
-
|
|
17
|
-
A node that reads far more rows than it passes up is doing hidden work. Compare
|
|
18
|
-
`Actual Rows` x `Actual Loops` with the rows the parent keeps, and read `Rows Removed by Filter`
|
|
19
|
-
`Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` (lossy GiST, BRIN, Bloom, or
|
|
20
|
-
bitmap pages; `Actual Rows` is counted after the recheck), each x `Actual Loops`. Millions removed to return tens means the predicate is not an
|
|
21
|
-
index condition, the index has the wrong leading columns, or a join filters after it multiplies.
|
|
22
|
-
Fix the index or the predicate shape, or filter before joining.
|
|
23
|
-
|
|
24
|
-
### SubPlans whose loops equal the outer row count
|
|
25
|
-
|
|
26
|
-
A node with `"Parent Relationship": "SubPlan"` and `Actual Loops` equal to the outer row count
|
|
27
|
-
runs once per outer row. Correlated subqueries in the select list or in a `Filter` look like
|
|
28
|
-
this. The statements inside a non-inlined function do not appear as SubPlans; see opaque function
|
|
29
|
-
calls below. Rewrite as a join, a `LATERAL` with a limit, or a
|
|
30
|
-
set-based aggregate computed once. An uncorrelated `InitPlan` runs once, but check its own time, rows, and buffers: one large scan,
|
|
31
|
-
sort, or expensive call can still dominate the statement.
|
|
32
|
-
|
|
33
|
-
### `Filter` where an `Index Cond` was expected
|
|
34
|
-
|
|
35
|
-
An `Index Cond` narrows the index scan; a `Filter` runs on every row the scan returns. If a
|
|
36
|
-
column you expected in `Index Cond` appears in `Filter`, check for a volatile function, a cast or
|
|
37
|
-
function wrapping the column, a type or collation mismatch, or a column outside the index's
|
|
38
|
-
leading keys. See
|
|
39
|
-
[volatile functions in predicates](performance-patterns.md#volatile-functions-in-predicates).
|
|
40
|
-
|
|
41
|
-
A partitioned parent whose plan lists every child and shows no `Subplans Removed` may not have
|
|
42
|
-
been pruned at plan or executor start. Pruning on an execution-time parameter, such as a value
|
|
43
|
-
from the outer side of a nested loop, keeps every child in the plan; check the children's loops,
|
|
44
|
-
where children pruned every time show `(never executed)`, and children visited only sometimes
|
|
45
|
-
show loops lower than the containing loop count. Constrain the partition key with a constant, a
|
|
46
|
-
parameter, or a once-per-statement stable expression; the bound must not be a volatile call.
|
|
47
|
-
|
|
48
|
-
### Opaque function calls
|
|
49
|
-
|
|
50
|
-
A plan shows `fn_x(col)` in a `Filter` or output column and nothing about the queries the
|
|
51
|
-
function runs. A scalar SQL function whose body contains a subquery, such as `EXISTS`, is never inlined,
|
|
52
|
-
so those queries run per row and stay invisible. Count the calls in one transaction:
|
|
53
|
-
|
|
54
|
-
```sql
|
|
55
|
-
BEGIN;
|
|
56
|
-
SET LOCAL track_functions = 'all'; -- needs superuser or a granted SET privilege
|
|
57
|
-
SELECT count(*) FROM orders WHERE fn_is_visible(orders.id);
|
|
58
|
-
SELECT funcname, calls FROM pg_stat_xact_user_functions;
|
|
59
|
-
ROLLBACK;
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
A positive call count proves the function was not inlined. Inlined functions are not counted, but
|
|
63
|
-
a missing row is only suggestive: a query that returns no rows or short-circuits the predicate also
|
|
64
|
-
never calls the function, so confirm the function body shape before concluding it was inlined.
|
|
65
|
-
Tested on
|
|
66
|
-
PostgreSQL 18.6: an `EXISTS`-bodied function was counted 90 times for 90 rows, and a
|
|
67
|
-
plain-expression function was inlined and not counted. `track_functions = 'pl'` skips
|
|
68
|
-
SQL-language functions; use `'all'`. See
|
|
69
|
-
[function inlining](performance-patterns.md#function-inlining).
|
|
70
|
-
|
|
71
|
-
### Text join and index conditions
|
|
72
|
-
|
|
73
|
-
`Hash Cond`, `Merge Cond`, `Join Filter`, or a join's `Index Cond` comparing `text` or `varchar`
|
|
74
|
-
columns (often shown with `::text` casts) means the key is compared under collation and stored in every
|
|
75
|
-
referencing row and index. Join on ids and keep the string in a unique column; see
|
|
76
|
-
[join on ids](../../postgres-schema-design/references/relations.md#join-on-ids-never-on-text).
|
|
77
|
-
|
|
78
|
-
### Generic plans worse than custom plans
|
|
79
|
-
|
|
80
|
-
A prepared statement can switch to a generic plan after several executions, planned without the
|
|
81
|
-
parameter values. If a statement is fast in `psql` with literals but slow from the application,
|
|
82
|
-
compare `EXPLAIN (GENERIC_PLAN)` for the statement with the plan for a real value. Estimates alone
|
|
83
|
-
can hide the problem, and `GENERIC_PLAN` cannot be combined with `ANALYZE`; prepare the statement
|
|
84
|
-
and compare `EXPLAIN (ANALYZE, BUFFERS) EXECUTE` for the same skewed value under
|
|
85
|
-
`plan_cache_mode = force_generic_plan` and `force_custom_plan`. When the generic plan is much worse, fix the statistics or query shape first; set
|
|
86
|
-
`plan_cache_mode = force_custom_plan` for that statement or role only with measured evidence.
|
|
87
|
-
|
|
88
|
-
### Large sequential scans and bad estimates
|
|
89
|
-
|
|
90
|
-
A `Seq Scan` over a large table that returns few rows and reads many buffers or removes many rows
|
|
91
|
-
by filter is usually a missing or unusable index. A sequential scan on a small table, one that
|
|
92
|
-
returns most rows, or one a parent `LIMIT` or `EXISTS` stops early (check the buffers) is fine. Compare `Plan Rows`
|
|
93
|
-
with `Actual Rows` on every executed node (`Actual Loops` above zero; a never-executed node has no
|
|
94
|
-
observed cardinality) that decides a join (scan inputs and join outputs): an estimate
|
|
95
|
-
off by 10x or more can pick the wrong join type or order. Run `ANALYZE`, then consider a higher
|
|
96
|
-
statistics target, or extended statistics for correlated columns within one table; extended
|
|
97
|
-
statistics do not improve join selectivity, so for a join misestimate look at the join keys'
|
|
98
|
-
statistics, the filters feeding the join, or the query shape before changing the query.
|
|
99
|
-
|
|
100
|
-
## Checklist
|
|
101
|
-
|
|
102
|
-
1. Total rows per node versus rows kept; `Rows Removed by ...`.
|
|
103
|
-
2. Any SubPlan with loops equal to the outer rows.
|
|
104
|
-
3. `Filter` that should be `Index Cond`; partition pruning (`Subplans Removed`).
|
|
105
|
-
4. Function calls in `Filter` or output; count them with `pg_stat_xact_user_functions`.
|
|
106
|
-
5. Text keys in join and index conditions.
|
|
107
|
-
6. Generic versus custom plan for prepared statements.
|
|
108
|
-
7. Estimate versus actual on join-deciding nodes.
|
|
109
|
-
8. `Buffers` shared hit plus read totals against the rows returned; the split separates cache
|
|
110
|
-
pressure from reads that missed PostgreSQL's shared buffers; use OS or storage metrics
|
|
111
|
-
to judge physical I/O, since the OS cache may serve a shared read.
|
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: postgres-partitioning-uuid-v7
|
|
3
|
-
description: Design PostgreSQL partitions and pruning around UUIDv7.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# PostgreSQL partitioning with UUIDv7
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/postgres-partitioning-uuid-v7/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
For schema names, references, and canonical table shapes, read
|
|
13
|
-
[postgres-schema-design](../postgres-schema-design/SKILL.md).
|
|
14
|
-
|
|
15
|
-
Partition only after lifecycle, retention, and query predicates show that it helps.
|
|
16
|
-
|
|
17
|
-
- Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.
|
|
18
|
-
- Align the partition key, primary key, indexes, constraints, and query predicates so partition
|
|
19
|
-
pruning is observable.
|
|
20
|
-
- Add a parent lower bound to a read of a `RANGE (id)` child table by its parent's UUIDv7 id
|
|
21
|
-
(`id >= min_uuidv7(parent time - skew)`) only when both hold: every writer sets the parent column
|
|
22
|
-
at insert, to a parent that already exists, and never re-points it to a newer parent; and nothing
|
|
23
|
-
mints child ids from a historical time (imports, backfills, seeds). Counterexample: articles
|
|
24
|
-
clustered into a story created later are older than their parent, and the bound silently drops
|
|
25
|
-
them. See [parent lower bound](references/partition-lifecycle.md#parent-lower-bound).
|
|
26
|
-
- A statement that must read every partition declares that, with a reason, on the statement. Do not
|
|
27
|
-
use a table-wide exemption: it also silences every future query on that table. See
|
|
28
|
-
[cross-partition reads](references/partition-lifecycle.md#declaring-cross-partition-reads).
|
|
29
|
-
- Plan creation, retention, migration, and verification as one deployable lifecycle. Include
|
|
30
|
-
rollback and independent-reader compatibility.
|
|
31
|
-
- Read [partition lifecycle](references/partition-lifecycle.md) before a schema or retention
|
|
32
|
-
migration.
|
|
33
|
-
|
|
34
|
-
Consumer wrapper owns: partition intervals, migration tooling, retention policy, and deploy
|
|
35
|
-
sequencing.
|
|
@@ -1,53 +0,0 @@
|
|
|
1
|
-
# Partition lifecycle
|
|
2
|
-
|
|
3
|
-
UUIDv7 ordering supports range bounds and index-friendly time windows. Generate bounds from time
|
|
4
|
-
instead of extracting timestamps in predicates; use a generated timestamp only when application
|
|
5
|
-
semantics require one. Partition on the range key that queries and retention actually constrain.
|
|
6
|
-
|
|
7
|
-
Choose a lifecycle. Pre-create future ranges before writes need them, or use on-demand ranges:
|
|
8
|
-
`RANGE (id)` with a DEFAULT partition, split into explicit ranges on demand, and a guarded drop
|
|
9
|
-
that refuses drops inside the retention window or under legal hold. Move or check rows in the
|
|
10
|
-
DEFAULT partition that belong to the range before dropping it. Maintain a default partition
|
|
11
|
-
only with an explicit attachment plan. Before attaching a populated range, prove the default partition excludes that range
|
|
12
|
-
or move conflicting rows; otherwise attachment can scan and lock the default partition.
|
|
13
|
-
|
|
14
|
-
Every primary or unique constraint on a partitioned table must include its partition key. Verify
|
|
15
|
-
pruning with predicates on that key, including joins whose other side needs an equivalent range
|
|
16
|
-
condition. UUIDv7 values are time ordered, not a promise that independently generated identifiers
|
|
17
|
-
have a strict ordering relationship.
|
|
18
|
-
|
|
19
|
-
## Parent lower bound
|
|
20
|
-
|
|
21
|
-
A child table partitioned `RANGE (id)` prunes when a reader bounds the child id. A reader that
|
|
22
|
-
starts from the parent can derive that bound from the parent's UUIDv7 id, assuming a child is never
|
|
23
|
-
older than its parent:
|
|
24
|
-
|
|
25
|
-
```sql
|
|
26
|
-
SELECT item.id, item.body
|
|
27
|
-
FROM order_items AS item
|
|
28
|
-
WHERE item.order_id = $1
|
|
29
|
-
AND item.id >= min_uuidv7($2::timestamptz - $3::interval);
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
`$2` is the parent's creation time and `$3` the clock skew allowance. The bound is safe only when
|
|
33
|
-
both hold:
|
|
34
|
-
|
|
35
|
-
- Every writer sets `order_id` at insert, to an order that already exists, and never re-points the
|
|
36
|
-
row to a newer order.
|
|
37
|
-
- Nothing mints child ids from a historical time: imports, backfills, and seeds.
|
|
38
|
-
|
|
39
|
-
Counterexample: `articles` clustered into a `stories` row created later. Each article id is older
|
|
40
|
-
than its story id, so `article.id >= min_uuidv7(story time - skew)` silently drops the older
|
|
41
|
-
articles. Bound such a read by the child's own window instead.
|
|
42
|
-
|
|
43
|
-
## Declaring cross-partition reads
|
|
44
|
-
|
|
45
|
-
A statement that must read every partition says so, with a reason, on the statement itself:
|
|
46
|
-
|
|
47
|
-
```sql
|
|
48
|
-
-- cross-partition: nightly integrity check compares order_items totals with orders
|
|
49
|
-
SELECT order_id, sum(quantity) FROM order_items GROUP BY order_id;
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Do not exempt the whole table. A table-wide exemption also silences the check for every future
|
|
53
|
-
query on that table, including one that forgot its partition key predicate.
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: postgres-schema-design
|
|
3
|
-
description: Design PostgreSQL names, relations, history, work queues, and cursors.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# PostgreSQL schema design
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and the repository's local database adapter when present.
|
|
9
|
-
Local policy overrides these portable conventions.
|
|
10
|
-
|
|
11
|
-
- Names explain the stored thing; read [naming](references/naming.md) when naming schema objects.
|
|
12
|
-
- Columns say their type and FK target; finite sets use enums or lookup tables.
|
|
13
|
-
- Joined identities use foreign keys; read [relations](references/relations.md) before modeling references.
|
|
14
|
-
- Split differing shapes, share identical values, and keep history documents as JSON.
|
|
15
|
-
- Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
|
|
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.
|
|
24
|
-
- Reuse parameterized trigger functions instead of copying bodies.
|
|
25
|
-
- Comment every table, column, and view; document reviewed exceptions explicitly.
|
|
26
|
-
|
|
27
|
-
For query shape, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
28
|
-
For partition lifecycle, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
|
|
29
|
-
For how jobs choose, cap, and resume over work-item and cursor tables, read
|
|
30
|
-
[bounded iteration](../bounded-iteration/SKILL.md).
|
|
31
|
-
Consumer policy owns lifecycle, retention, migration strategy, and enforcement configuration.
|