heimdall-agent 1.0.0 → 1.1.0
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/README.md +57 -26
- package/README.pt-BR.md +429 -0
- package/agents/cloud-engineer.md +77 -0
- package/agents/code-sentinel.md +66 -35
- package/agents/database-architect.md +31 -25
- package/agents/frontend-designer.md +30 -28
- package/agents/mobile-designer.md +25 -24
- package/agents/modernizer.md +66 -0
- package/agents/orchestrator.md +94 -93
- package/agents/reviewer.md +100 -71
- package/agents/security-auditor.md +27 -27
- package/agents/tester.md +97 -90
- package/commands/grill-me.md +20 -4
- package/commands/orchestrate.md +16 -0
- package/commands/orchestrator.md +16 -0
- package/commands/plan.md +17 -1
- package/config/agents.json +21 -3
- package/config/mcp.json +72 -0
- package/config/models.json +26 -16
- package/config/profiles.json +2 -4
- package/config/skills.json +210 -100
- package/docs/SKILLS.md +341 -245
- package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
- package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
- package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
- package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
- package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
- package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
- package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
- package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
- package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
- package/docs/runs/skill-audit/customization-report.json +380 -0
- package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
- package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
- package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
- package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
- package/docs/runs/skill-audit/inventory.json +308 -0
- package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
- package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
- package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
- package/docs/runs/skill-audit/probe.ps1 +16 -0
- package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
- package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
- package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
- package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
- package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
- package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
- package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
- package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
- package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
- package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
- package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
- package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
- package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
- package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
- package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
- package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
- package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
- package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
- package/docs/runs/skill-audit/update-manifest.md +88 -0
- package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
- package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
- package/docs/runs/skill-audit/upstream-status.json +563 -0
- package/docs/runs/skill-audit/verification-results.json +252 -0
- package/doctrine/AGENTS.md +39 -77
- package/hooks/git/pre-commit +11 -0
- package/hooks/heimdall-hook.cjs +81 -2
- package/hooks/herdr-agent-state.ps1 +55 -0
- package/hooks/hooks.json +0 -11
- package/lib/catalog-sync.cjs +162 -0
- package/lib/hermes-context.cjs +57 -0
- package/lib/model-context.cjs +123 -0
- package/lib/path-discovery.cjs +94 -0
- package/package.json +7 -3
- package/playbooks/01-interactive-grilling-gate.md +14 -1
- package/playbooks/02-fast-code-deep-verification.md +3 -2
- package/playbooks/03-adversarial-code-review.md +3 -3
- package/playbooks/05-canonical-plan-template.md +32 -18
- package/playbooks/06-model-registry-matrix.md +24 -13
- package/playbooks/07-legacy-code-modernization.md +74 -0
- package/playbooks/08-backlog-and-change-request-flow.md +122 -0
- package/setup.mjs +592 -172
- package/skills/antislop/SKILL.md +76 -56
- package/skills/antislop/VERSION +1 -0
- package/skills/antislop-copywriting/SKILL.md +372 -372
- package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-human/SKILL.md +204 -147
- package/skills/antislop-human/contrast-check.py +168 -165
- package/skills/antislop-human/contrast-mcp.py +6 -3
- package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
- package/skills/antislop-human/references/WCAG.md +127 -0
- package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-ui/SKILL.md +344 -304
- package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
- package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
- package/skills/brainstorming/SKILL.md +274 -265
- package/skills/brainstorming/builder-check-prompt.md +23 -0
- package/skills/brainstorming/scripts/frame-template.html +213 -213
- package/skills/brainstorming/scripts/server.cjs +723 -723
- package/skills/brandkit/SKILL.md +798 -798
- package/skills/brutalist-skill/SKILL.md +93 -92
- package/skills/caveman/README.md +68 -0
- package/skills/caveman/SKILL.md +73 -38
- package/skills/claude-collaborator/SKILL.md +24 -44
- package/skills/clean-code/SKILL.md +152 -0
- package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
- package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
- package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
- package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
- package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
- package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
- package/skills/cloudflare-security-audit/HUNTING.md +251 -251
- package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
- package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
- package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
- package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
- package/skills/cloudflare-security-audit/SKILL.md +192 -192
- package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
- package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
- package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
- package/skills/cloudflare-security-audit/report-schema.json +461 -461
- package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
- package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
- package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
- package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
- package/skills/codex-collaborator/SKILL.md +24 -45
- package/skills/communication-doctrine/SKILL.md +89 -0
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/executing-plans/SKILL.md +0 -52
- package/skills/executing-plans/scripts/task-done +52 -52
- package/skills/executing-plans/scripts/task-start +28 -28
- package/skills/gemini-collaborator/SKILL.md +24 -56
- package/skills/herdr/SKILL.md +243 -0
- package/skills/image-to-code-skill/SKILL.md +1228 -1228
- package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
- package/skills/imagegen-frontend-web/SKILL.md +987 -987
- package/skills/karpathy-guidelines/SKILL.md +67 -67
- package/skills/mcp-engineering/SKILL.md +74 -0
- package/skills/minimalist-skill/SKILL.md +87 -85
- package/skills/output-skill/SKILL.md +49 -49
- package/skills/ponytail/SKILL.md +36 -52
- package/skills/postgres-best-practices/SKILL.md +30 -52
- package/skills/postgres-best-practices/references/backup-restore.md +372 -0
- package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
- package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
- package/skills/postgres-best-practices/references/hot-standby.md +221 -0
- package/skills/postgres-best-practices/references/indexing.md +318 -0
- package/skills/postgres-best-practices/references/logical-replication.md +610 -0
- package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
- package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
- package/skills/postgres-best-practices/references/query-optimization.md +294 -0
- package/skills/postgres-best-practices/references/query-patterns.md +566 -0
- package/skills/postgres-best-practices/references/schema-design.md +362 -0
- package/skills/postgres-best-practices/references/security-roles.md +489 -0
- package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
- package/skills/progressive-disclosure/SKILL.md +68 -0
- package/skills/pstack-discipline/SKILL.md +40 -0
- package/skills/receiving-code-review/SKILL.md +2 -23
- package/skills/requesting-code-review/SKILL.md +7 -36
- package/skills/soft-skill/SKILL.md +99 -98
- package/skills/stitch-skill/DESIGN.md +121 -121
- package/skills/stitch-skill/SKILL.md +185 -184
- package/skills/strix-security/SKILL.md +54 -53
- package/skills/subagent-driven-development/SKILL.md +28 -260
- package/skills/subagent-driven-development/references/batching.md +11 -0
- package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/skills/subagent-driven-development/references/final-review.md +47 -0
- package/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/skills/subagent-driven-development/references/preflight.md +26 -0
- package/skills/subagent-driven-development/references/resuming.md +12 -0
- package/skills/subagent-driven-development/scripts/review-package +53 -53
- package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
- package/skills/subagent-driven-development/scripts/task-brief +43 -43
- package/skills/systematic-debugging/SKILL.md +283 -306
- package/skills/taste-skill/SKILL.md +542 -1206
- package/skills/taste-skill/references/app-screens.md +1199 -0
- package/skills/taste-skill/references/colour.md +141 -0
- package/skills/taste-skill/references/copy.md +177 -0
- package/skills/taste-skill/references/critique.md +182 -0
- package/skills/taste-skill/references/imagery.md +791 -0
- package/skills/taste-skill/references/layout.md +292 -0
- package/skills/taste-skill/references/motion.md +980 -0
- package/skills/taste-skill/references/research.md +356 -0
- package/skills/taste-skill/references/scenes.md +174 -0
- package/skills/taste-skill/references/tells.md +115 -0
- package/skills/taste-skill/references/type.md +170 -0
- package/skills/test-driven-development/SKILL.md +330 -337
- package/skills/thermo/SKILL.md +67 -0
- package/skills/threat-modeling/SKILL.md +55 -0
- package/skills/trailofbits-audit-context/SKILL.md +72 -72
- package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
- package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
- package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
- package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
- package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
- package/skills/verification-before-completion/SKILL.md +0 -14
- package/skills/writing-plans/SKILL.md +11 -15
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
- package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
- package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
- package/skills/gpt-tasteskill/SKILL.md +0 -74
- package/skills/taste-skill-v1/SKILL.md +0 -226
- /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
- /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
- /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
- /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
- /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
- /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
- /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
- /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
package/skills/ponytail/SKILL.md
CHANGED
|
@@ -1,68 +1,52 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ponytail
|
|
3
3
|
description: >
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
4
|
+
Lazy senior dev mode: the smallest change that fully solves the task, and a
|
|
5
|
+
reply a busy human understands in one read. Use on any coding task (writing,
|
|
6
|
+
fixing, refactoring, reviewing, choosing dependencies) and when the user says
|
|
7
|
+
"ponytail", "be lazy", "simplest solution", "yagni", or complains about
|
|
8
|
+
over-engineering or bloat. Levels: lite, full (default), ultra.
|
|
9
|
+
argument-hint: "[lite|full|ultra|off]"
|
|
10
|
+
license: MIT
|
|
9
11
|
---
|
|
10
12
|
|
|
11
|
-
# Ponytail
|
|
13
|
+
# Ponytail
|
|
12
14
|
|
|
13
|
-
You are
|
|
15
|
+
You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## 1. The Decision Ladder
|
|
19
|
+
## Before you write
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
- Reject unrequested features, premature config toggles, speculative plugin architectures, and "just-in-case" parameter options.
|
|
25
|
-
- If the requirement does not explicitly ask for it, do not build it.
|
|
26
|
-
2. **Does it already exist in this codebase? (Research & Reuse First)**
|
|
27
|
-
- Search the repository before creating a new utility, helper, type, or component.
|
|
28
|
-
- Check standard library primitives (`crypto`, `fs`, `path`, `fetch`, `URL`, `Intl`) and installed dependencies before writing custom code.
|
|
29
|
-
- Reuse existing functions and established patterns. Do not create parallel abstractions or reinvent the wheel.
|
|
30
|
-
3. **Can the standard library do it? (Built-in first)**
|
|
31
|
-
- Prioritize Node.js/browser built-in modules (`crypto`, `fs`, `path`, `fetch`, `URL`, `Intl`) before installing third-party libraries.
|
|
32
|
-
4. **Is there a native platform feature for it? (Platform primitives)**
|
|
33
|
-
- Use semantic HTML and native browser capabilities (e.g. `<input type="date">`, `<dialog>`, CSS flex/grid, CSS `:has()`) instead of installing heavy UI packages or state wrappers.
|
|
34
|
-
5. **Does an already-installed dependency solve it?**
|
|
35
|
-
- Check `package.json` for existing tools before proposing new dependencies.
|
|
36
|
-
6. **Can it be written in one line?**
|
|
37
|
-
- Prefer concise standard idioms over 30-line boilerplate wrappers.
|
|
38
|
-
7. **Only then: Write the minimum custom code that works.**
|
|
39
|
-
- Simple, readable, surgical, and clear.
|
|
23
|
+
## The smallest complete change
|
|
40
24
|
|
|
41
|
-
|
|
25
|
+
Take the first option that fully works:
|
|
42
26
|
|
|
43
|
-
|
|
27
|
+
1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
|
|
28
|
+
2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
|
|
29
|
+
3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
|
|
30
|
+
4. An installed dependency? Use it. Never add a dependency for a few lines.
|
|
31
|
+
5. Can it be one line a reader gets at a glance? One line.
|
|
32
|
+
6. Otherwise: the minimum code that works.
|
|
44
33
|
|
|
45
|
-
|
|
34
|
+
- Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
|
|
35
|
+
- No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
|
|
36
|
+
- The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
|
|
37
|
+
- Comment only the why the code cannot show, in one line.
|
|
38
|
+
- Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
|
|
39
|
+
- Code you move or merge keeps its error handling and validation.
|
|
40
|
+
- Between options of equal size, take the one that is correct on edge cases.
|
|
41
|
+
- Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
|
|
42
|
+
- A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
|
|
46
43
|
|
|
47
|
-
|
|
48
|
-
- **Trust Boundaries & Input Validation**: Always validate external inputs, API parameters, and environment data.
|
|
49
|
-
- **Security & Permissions**: Never bypass authentication, authorization, or sanitize checks.
|
|
50
|
-
- **Data-Loss Prevention**: Never execute destructive operations without verified safety gates.
|
|
51
|
-
- **Error Handling**: Never catch and swallow exceptions with empty handlers. Handle failures gracefully.
|
|
52
|
-
- **Accessibility & Contrast**: Never sacrifice semantic structure or visual usability.
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## 3. Intensity Levels
|
|
57
|
-
|
|
58
|
-
- **Lite**: Polite nudge to question unnecessary dependencies and prefer standard library methods.
|
|
59
|
-
- **Full (Default)**: Strictly halts at the first rung of the Decision Ladder that solves the problem.
|
|
60
|
-
- **Ultra**: Ruthlessly strips all boilerplate, rejects any wrapper that only has one callsite, and deletes dead code on sight.
|
|
61
|
-
|
|
62
|
-
---
|
|
44
|
+
Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
|
|
63
45
|
|
|
64
|
-
##
|
|
46
|
+
## Levels
|
|
65
47
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
48
|
+
| Level | Behavior |
|
|
49
|
+
|-------|----------|
|
|
50
|
+
| **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
|
|
51
|
+
| **full** | The rules above. Default. |
|
|
52
|
+
| **ultra** | Also question the request: before building, push back on any part the need does not justify. |
|
|
@@ -1,64 +1,42 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
3
|
-
description:
|
|
4
|
-
license: MIT
|
|
5
|
-
metadata:
|
|
6
|
-
author: supabase
|
|
7
|
-
version: "1.1.1"
|
|
8
|
-
organization: Supabase
|
|
9
|
-
date: January 2026
|
|
10
|
-
abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
|
|
2
|
+
name: postgres-best-practices
|
|
3
|
+
description: Best practices and guidelines for working with Postgres. Covers schema design, indexing strategies, query optimization, migrations, and common pitfalls. Use when writing SQL, designing database schemas, optimizing queries, or setting up a Postgres database.
|
|
11
4
|
---
|
|
12
5
|
|
|
13
|
-
#
|
|
6
|
+
# Postgres Best Practices
|
|
14
7
|
|
|
15
|
-
|
|
8
|
+
Guidelines and best practices for working with Postgres, covering schema design, indexing, query optimization, and common pitfalls.
|
|
16
9
|
|
|
17
|
-
##
|
|
10
|
+
## Supported Versions
|
|
18
11
|
|
|
19
|
-
|
|
20
|
-
- Writing SQL queries or designing schemas
|
|
21
|
-
- Implementing indexes or query optimization
|
|
22
|
-
- Reviewing database performance issues
|
|
23
|
-
- Configuring connection pooling or scaling
|
|
24
|
-
- Optimizing for Postgres-specific features
|
|
25
|
-
- Working with Row-Level Security (RLS)
|
|
12
|
+
This skill covers PostgreSQL 14 through 18. Version-specific features are tagged (e.g., `[PG15+]`, `[PG18+]`); environment-dependent examples identify required privileges, extensions, or multi-node setup.
|
|
26
13
|
|
|
27
|
-
|
|
14
|
+
PostgreSQL provides 5 years of support per major version. Always run the latest minor release.
|
|
28
15
|
|
|
29
|
-
|
|
|
30
|
-
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
|
|
|
36
|
-
| 6 | Data Access Patterns | MEDIUM | `data-` |
|
|
37
|
-
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
|
|
38
|
-
| 8 | Advanced Features | LOW | `advanced-` |
|
|
16
|
+
| Version | Initial Release | End of Life |
|
|
17
|
+
| ------- | ------------------ | ------------------ |
|
|
18
|
+
| 18 | September 2025 | November 2030 |
|
|
19
|
+
| 17 | September 2024 | November 2029 |
|
|
20
|
+
| 16 | September 2023 | November 2028 |
|
|
21
|
+
| 15 | October 2022 | November 2027 |
|
|
22
|
+
| 14 | September 2021 | November 2026 |
|
|
39
23
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
Read individual rule files for detailed explanations and SQL examples:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
references/query-missing-indexes.md
|
|
46
|
-
references/query-partial-indexes.md
|
|
47
|
-
references/_sections.md
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Each rule file contains:
|
|
51
|
-
- Brief explanation of why it matters
|
|
52
|
-
- Incorrect SQL example with explanation
|
|
53
|
-
- Correct SQL example with explanation
|
|
54
|
-
- Optional EXPLAIN output or metrics
|
|
55
|
-
- Additional context and references
|
|
56
|
-
- Supabase-specific notes (when applicable)
|
|
24
|
+
Source: [postgresql.org/support/versioning](https://www.postgresql.org/support/versioning/)
|
|
57
25
|
|
|
58
26
|
## References
|
|
59
27
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
-
|
|
63
|
-
|
|
64
|
-
|
|
28
|
+
| Area | Resource | When to Use |
|
|
29
|
+
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------ |
|
|
30
|
+
| Schema Design | `references/schema-design.md` | Designing tables, choosing data types, normalizing, partitioning |
|
|
31
|
+
| Indexing | `references/indexing.md` | Choosing index types, composite indexes, partial/covering indexes |
|
|
32
|
+
| Query Optimization | `references/query-optimization.md` | Reading EXPLAIN ANALYZE, fixing bottlenecks, planner tuning |
|
|
33
|
+
| Query Patterns | `references/query-patterns.md` | CTEs, window functions, lateral joins, UPSERT, JSONB, anti-patterns|
|
|
34
|
+
| Performance Diagnostics | `references/performance-diagnostics.md` | pg_stat views, lock analysis, VACUUM, connection management |
|
|
35
|
+
| Logical Replication | `references/logical-replication.md` | Pub/sub replication, live migrations, CDC |
|
|
36
|
+
| Hot Standby | `references/hot-standby.md` | Streaming replication, read replicas, failover |
|
|
37
|
+
| Transaction Isolation | `references/transaction-isolation.md` | Isolation levels, lost updates, serialization failures, retry logic |
|
|
38
|
+
| Backup & Restore | `references/backup-restore.md` | pg_dump/pg_restore, pg_basebackup, PITR, recovery |
|
|
39
|
+
| Security & Roles | `references/security-roles.md` | Privileges, RLS, pg_hba.conf, authentication, SSL |
|
|
40
|
+
| Bulk Data Loading | `references/bulk-loading.md` | COPY patterns, ETL staging, optimizing large loads, batch ops |
|
|
41
|
+
| Connection Pooling | `references/connection-pooling.md` | PgBouncer config, pool modes, prepared statements, sizing |
|
|
42
|
+
| Major Version Upgrades | `references/major-version-upgrades.md` | pg_upgrade, logical replication migration, pre/post checklists |
|
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
# Backup & Restore Reference
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
- Backup strategy overview
|
|
5
|
+
- Logical backups (pg_dump / pg_restore)
|
|
6
|
+
- Physical backups (pg_basebackup)
|
|
7
|
+
- Point-in-Time Recovery (PITR)
|
|
8
|
+
- Verification and testing
|
|
9
|
+
- Automation patterns
|
|
10
|
+
|
|
11
|
+
## Backup Strategy Overview
|
|
12
|
+
|
|
13
|
+
| Method | What it captures | Granularity | Speed | Use case |
|
|
14
|
+
|--------|-----------------|-------------|-------|----------|
|
|
15
|
+
| `pg_dump` | Logical (SQL/custom) | Per-database, per-table | Slow on large DBs | Dev snapshots, migrations, selective restore |
|
|
16
|
+
| `pg_dumpall` | All databases + globals | Entire cluster | Slow | Full cluster backup including roles/tablespaces |
|
|
17
|
+
| `pg_basebackup` | Physical (file copy) | Entire cluster | Fast | Production backups, PITR base, replica setup |
|
|
18
|
+
| Continuous archiving | WAL segments | Incremental | Continuous | PITR — restore to any point in time |
|
|
19
|
+
|
|
20
|
+
**Production recommendation**: `pg_basebackup` + continuous WAL archiving for PITR capability. Supplement with periodic `pg_dump` for portable, version-independent backups.
|
|
21
|
+
|
|
22
|
+
## Logical Backups (pg_dump / pg_restore)
|
|
23
|
+
|
|
24
|
+
### pg_dump Formats
|
|
25
|
+
|
|
26
|
+
| Format | Flag | Parallel restore? | Selective restore? | Notes |
|
|
27
|
+
|--------|------|-------------------|-------------------|-------|
|
|
28
|
+
| Custom | `-Fc` | Yes | Yes | **Recommended default** — compressed, flexible |
|
|
29
|
+
| Directory | `-Fd` | Yes | Yes | One file per table, good for large DBs |
|
|
30
|
+
| Plain SQL | `-Fp` | No | No (manual editing) | Human-readable, good for version control |
|
|
31
|
+
| Tar | `-Ft` | No | Yes | Compatibility option |
|
|
32
|
+
|
|
33
|
+
### Common pg_dump Patterns
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
# Full database backup (custom format — recommended)
|
|
37
|
+
pg_dump -Fc -f backup.dump mydb
|
|
38
|
+
|
|
39
|
+
# With compression level (0-9, default varies by format)
|
|
40
|
+
pg_dump -Fc -Z 6 -f backup.dump mydb
|
|
41
|
+
|
|
42
|
+
# Parallel dump (directory format only, 4 workers)
|
|
43
|
+
pg_dump -Fd -j 4 -f backup_dir/ mydb
|
|
44
|
+
|
|
45
|
+
# Schema only (no data)
|
|
46
|
+
pg_dump -Fc --schema-only -f schema.dump mydb
|
|
47
|
+
|
|
48
|
+
# Data only (no schema)
|
|
49
|
+
pg_dump -Fc --data-only -f data.dump mydb
|
|
50
|
+
|
|
51
|
+
# Specific tables
|
|
52
|
+
pg_dump -Fc -t orders -t customers -f subset.dump mydb
|
|
53
|
+
|
|
54
|
+
# Specific schema
|
|
55
|
+
pg_dump -Fc -n public -f public_schema.dump mydb
|
|
56
|
+
|
|
57
|
+
# Exclude large tables
|
|
58
|
+
pg_dump -Fc -T audit_log -T event_archive -f without_logs.dump mydb
|
|
59
|
+
|
|
60
|
+
# Include CREATE DATABASE in output
|
|
61
|
+
pg_dump -Fc --create -f backup_with_create.dump mydb
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### pg_restore Patterns
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Restore to an existing (empty) database
|
|
68
|
+
pg_restore -d mydb backup.dump
|
|
69
|
+
|
|
70
|
+
# Parallel restore (4 workers — significantly faster for large DBs)
|
|
71
|
+
pg_restore -d mydb -j 4 backup.dump
|
|
72
|
+
|
|
73
|
+
# Create the database during restore
|
|
74
|
+
pg_restore --create -d postgres backup.dump
|
|
75
|
+
|
|
76
|
+
# List contents of a backup (inspect before restoring)
|
|
77
|
+
pg_restore --list backup.dump
|
|
78
|
+
|
|
79
|
+
# Restore specific tables only
|
|
80
|
+
pg_restore -d mydb -t orders -t customers backup.dump
|
|
81
|
+
|
|
82
|
+
# Schema only
|
|
83
|
+
pg_restore -d mydb --schema-only backup.dump
|
|
84
|
+
|
|
85
|
+
# Data only (schema already exists)
|
|
86
|
+
pg_restore -d mydb --data-only backup.dump
|
|
87
|
+
|
|
88
|
+
# Clean (drop) objects before recreating
|
|
89
|
+
pg_restore -d mydb --clean --if-exists backup.dump
|
|
90
|
+
|
|
91
|
+
# Restore atomically and stop on the first error
|
|
92
|
+
pg_restore -d mydb --single-transaction -j 1 backup.dump
|
|
93
|
+
# Note: --single-transaction is incompatible with -j > 1
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Selective restore patterns do not automatically include dependencies. Schema-qualify table patterns when names may exist in multiple schemas, and verify required types, sequences, constraints, and referenced tables separately.
|
|
97
|
+
|
|
98
|
+
### Restoring Plain SQL Dumps
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# Plain SQL dumps are restored with psql, not pg_restore
|
|
102
|
+
psql -d mydb -f backup.sql
|
|
103
|
+
|
|
104
|
+
# With error handling
|
|
105
|
+
psql -d mydb -v ON_ERROR_STOP=1 -f backup.sql
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### pg_dumpall — Cluster-Wide Backup
|
|
109
|
+
|
|
110
|
+
`pg_dumpall` is the only way to back up global objects (roles, tablespaces):
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Full cluster (all databases + globals) — plain SQL only
|
|
114
|
+
pg_dumpall -f cluster_backup.sql
|
|
115
|
+
|
|
116
|
+
# Globals only (roles, tablespaces) — use alongside per-database pg_dump
|
|
117
|
+
pg_dumpall --globals-only -f globals.sql
|
|
118
|
+
|
|
119
|
+
# Roles only
|
|
120
|
+
pg_dumpall --roles-only -f roles.sql
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**Best practice**: Use `pg_dumpall --globals-only` for roles/tablespaces, then `pg_dump -Fc` per database for data. This gives you parallel restore capability while preserving globals.
|
|
124
|
+
|
|
125
|
+
### Optimizer Statistics in Backups (PG18+)
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Dump optimizer statistics (speeds up post-restore query performance)
|
|
129
|
+
pg_dump -Fc --statistics -f backup.dump mydb
|
|
130
|
+
|
|
131
|
+
# Statistics only (no schema or data)
|
|
132
|
+
pg_dump -Fc --statistics-only -f stats.dump mydb
|
|
133
|
+
|
|
134
|
+
# Skip statistics
|
|
135
|
+
pg_dump -Fc --no-statistics -f backup.dump mydb
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Without statistics, the planner uses default estimates after restore until `ANALYZE` runs on all tables. Dumping statistics avoids the post-restore performance dip.
|
|
139
|
+
|
|
140
|
+
### Performance Tips for Large Databases
|
|
141
|
+
|
|
142
|
+
1. **Use parallel dump/restore** (`-Fd -j N`) — scales well with CPU cores
|
|
143
|
+
2. **Dump to fast storage** — local NVMe, not network mounts
|
|
144
|
+
3. **Increase `maintenance_work_mem`** on the restore target for faster index rebuilds
|
|
145
|
+
4. **Disable triggers during data-only restore**: `pg_restore --disable-triggers` (requires superuser)
|
|
146
|
+
5. **Drop indexes before restore, recreate after** — faster than incremental index maintenance during bulk inserts
|
|
147
|
+
6. **Restore schema first, then data, then indexes**:
|
|
148
|
+
```bash
|
|
149
|
+
pg_restore -d mydb --section=pre-data backup.dump
|
|
150
|
+
pg_restore -d mydb --data-only -j 4 backup.dump
|
|
151
|
+
pg_restore -d mydb --section=post-data -j 4 backup.dump
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Physical Backups (pg_basebackup)
|
|
155
|
+
|
|
156
|
+
`pg_basebackup` creates a byte-for-byte copy of the entire cluster, suitable as a base for PITR or setting up replicas.
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
# Basic backup (plain format)
|
|
160
|
+
pg_basebackup -D /backup/base -Fp -Xs -P
|
|
161
|
+
|
|
162
|
+
# Compressed tar format
|
|
163
|
+
pg_basebackup -D /backup/base -Ft -z -Xs -P
|
|
164
|
+
|
|
165
|
+
# With checkpoint mode (fast = don't wait for next scheduled checkpoint)
|
|
166
|
+
pg_basebackup -D /backup/base -Fp -Xs -P --checkpoint=fast
|
|
167
|
+
|
|
168
|
+
# To a remote server
|
|
169
|
+
pg_basebackup -h primary_host -U repl_user -D /backup/base -Fp -Xs -P
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
| Flag | Meaning |
|
|
173
|
+
|------|---------|
|
|
174
|
+
| `-D` | Target directory |
|
|
175
|
+
| `-Fp` | Plain format (ready-to-use data directory) |
|
|
176
|
+
| `-Ft` | Tar format (one tar per tablespace) |
|
|
177
|
+
| `-z` | Compress (with tar format) |
|
|
178
|
+
| `-Xs` | Stream WAL during backup (ensures consistency) |
|
|
179
|
+
| `-P` | Show progress |
|
|
180
|
+
| `--checkpoint=fast` | Start backup immediately (don't wait for next checkpoint) |
|
|
181
|
+
|
|
182
|
+
### Prerequisites
|
|
183
|
+
|
|
184
|
+
The connection used by `pg_basebackup` must authenticate as a superuser or a role with `REPLICATION` privilege. `max_wal_senders` must also have enough capacity for the backup connection:
|
|
185
|
+
|
|
186
|
+
```sql
|
|
187
|
+
-- On the primary
|
|
188
|
+
CREATE ROLE backup_user WITH REPLICATION LOGIN PASSWORD '...';
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
And `pg_hba.conf` must allow replication connections:
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
host replication backup_user backup_server_ip/32 scram-sha-256
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
[PG15+] `--target=server:/path` writes the backup on the database server. A non-superuser using this target needs both `REPLICATION` privilege for the backup connection and membership in `pg_write_server_files` for the server-side write. `--target` is unavailable in PG14 and cannot be combined with `-Xstream`; use `-Xfetch` or `-Xnone`.
|
|
198
|
+
|
|
199
|
+
## Point-in-Time Recovery (PITR)
|
|
200
|
+
|
|
201
|
+
PITR lets you restore a database to any specific point in time — invaluable for recovering from accidental data deletion or corruption.
|
|
202
|
+
|
|
203
|
+
### How PITR Works
|
|
204
|
+
|
|
205
|
+
1. Take a **base backup** (`pg_basebackup`)
|
|
206
|
+
2. Continuously **archive WAL segments** as they're produced
|
|
207
|
+
3. To recover: restore the base backup, then **replay WAL** up to the target time
|
|
208
|
+
|
|
209
|
+
### Step 1: Configure WAL Archiving
|
|
210
|
+
|
|
211
|
+
In `postgresql.conf`:
|
|
212
|
+
|
|
213
|
+
```
|
|
214
|
+
archive_mode = on
|
|
215
|
+
archive_command = 'cp %p /archive/wal/%f' # or use pgBackRest, barman, etc.
|
|
216
|
+
# archive_library = '' # PG15+: use archive modules instead of shell commands
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Requires a restart after enabling `archive_mode`.
|
|
220
|
+
|
|
221
|
+
Verify archiving is working:
|
|
222
|
+
|
|
223
|
+
```sql
|
|
224
|
+
SELECT * FROM pg_stat_archiver;
|
|
225
|
+
-- Check: archived_count is increasing, last_failed_time is NULL
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Step 2: Take Base Backups Regularly
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
# Weekly base backup (adjust frequency based on WAL volume)
|
|
232
|
+
pg_basebackup -D /backup/base_$(date +%Y%m%d) -Ft -z -Xs -P --checkpoint=fast
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Step 3: Recovery
|
|
236
|
+
|
|
237
|
+
To recover to a specific point in time:
|
|
238
|
+
|
|
239
|
+
1. Stop PostgreSQL
|
|
240
|
+
2. Replace the data directory with the base backup
|
|
241
|
+
3. Create `recovery.signal` (PG12+) or `recovery.conf` (PG11-)
|
|
242
|
+
4. Configure recovery target in `postgresql.conf`:
|
|
243
|
+
|
|
244
|
+
```
|
|
245
|
+
# In postgresql.conf (PG12+):
|
|
246
|
+
restore_command = 'cp /archive/wal/%f %p'
|
|
247
|
+
recovery_target_time = '2024-06-15 14:30:00'
|
|
248
|
+
recovery_target_action = 'promote' # 'pause' to inspect before promoting
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
5. Start PostgreSQL — it replays WAL up to the target time, then promotes to read-write
|
|
252
|
+
|
|
253
|
+
### Recovery Target Options
|
|
254
|
+
|
|
255
|
+
```text
|
|
256
|
+
-- Recover to a specific time
|
|
257
|
+
recovery_target_time = '2024-06-15 14:30:00+00'
|
|
258
|
+
|
|
259
|
+
-- Recover to a specific transaction ID
|
|
260
|
+
recovery_target_xid = '12345678'
|
|
261
|
+
|
|
262
|
+
-- Recover to a named restore point
|
|
263
|
+
recovery_target_name = 'before_migration'
|
|
264
|
+
|
|
265
|
+
-- Stop as soon as a consistent state is reached
|
|
266
|
+
-- (for an online backup, normally the point where the backup ended)
|
|
267
|
+
recovery_target = 'immediate'
|
|
268
|
+
|
|
269
|
+
-- Recover to a specific WAL position
|
|
270
|
+
recovery_target_lsn = '0/1A2B3C4D'
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
To recover through the end of all available WAL, omit every `recovery_target*` setting. `recovery_target = 'immediate'` is an explicit early stopping target, so later available WAL can remain unapplied. PostgreSQL may still replay the WAL required to make an online backup consistent.
|
|
274
|
+
|
|
275
|
+
### Creating Named Restore Points
|
|
276
|
+
|
|
277
|
+
Before risky operations, create a named restore point:
|
|
278
|
+
|
|
279
|
+
```sql
|
|
280
|
+
SELECT pg_create_restore_point('before_schema_migration');
|
|
281
|
+
SELECT pg_create_restore_point('before_bulk_delete');
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
This gives you an exact target to recover to if the operation goes wrong.
|
|
285
|
+
|
|
286
|
+
## Verification and Testing
|
|
287
|
+
|
|
288
|
+
### Verify Backup Integrity
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
# List contents without restoring
|
|
292
|
+
pg_restore --list backup.dump
|
|
293
|
+
|
|
294
|
+
# Verify a plain-format physical backup (PG13+)
|
|
295
|
+
pg_verifybackup /backup/base_20240615
|
|
296
|
+
|
|
297
|
+
# PG18+: verify a tar-format backup directly
|
|
298
|
+
pg_verifybackup --no-parse-wal /backup/base_tar_20240615
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### Test Restores Regularly
|
|
302
|
+
|
|
303
|
+
**A backup that hasn't been tested is not a backup.** Schedule regular restore tests:
|
|
304
|
+
|
|
305
|
+
```bash
|
|
306
|
+
# Restore to a test database
|
|
307
|
+
createdb mydb_restore_test
|
|
308
|
+
pg_restore -d mydb_restore_test backup.dump
|
|
309
|
+
|
|
310
|
+
# Verify row counts
|
|
311
|
+
psql -d mydb_restore_test -c "
|
|
312
|
+
SELECT schemaname, relname, n_live_tup
|
|
313
|
+
FROM pg_stat_user_tables
|
|
314
|
+
ORDER BY n_live_tup DESC;
|
|
315
|
+
"
|
|
316
|
+
|
|
317
|
+
# Clean up
|
|
318
|
+
dropdb mydb_restore_test
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
### Post-Restore Checklist
|
|
322
|
+
|
|
323
|
+
After restoring a backup:
|
|
324
|
+
|
|
325
|
+
1. **Run `ANALYZE`** on all tables — optimizer statistics may be stale or missing
|
|
326
|
+
```sql
|
|
327
|
+
ANALYZE; -- all tables
|
|
328
|
+
```
|
|
329
|
+
2. **Verify sequences** — if restoring data-only, sequences may not match the data
|
|
330
|
+
```sql
|
|
331
|
+
SELECT sequencename, last_value FROM pg_sequences WHERE schemaname = 'public';
|
|
332
|
+
```
|
|
333
|
+
3. **Check for invalid indexes** — concurrent index builds may have been in progress
|
|
334
|
+
```sql
|
|
335
|
+
SELECT indexrelid::regclass, indisvalid FROM pg_index WHERE NOT indisvalid;
|
|
336
|
+
```
|
|
337
|
+
4. **Verify replication slots are clean** — stale slots from the source won't work
|
|
338
|
+
```sql
|
|
339
|
+
SELECT slot_name, active FROM pg_replication_slots;
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## Automation Patterns
|
|
343
|
+
|
|
344
|
+
### Scripted Backup with Retention
|
|
345
|
+
|
|
346
|
+
```bash
|
|
347
|
+
#!/bin/bash
|
|
348
|
+
BACKUP_DIR="/backup/pg"
|
|
349
|
+
RETENTION_DAYS=30
|
|
350
|
+
DB_NAME="mydb"
|
|
351
|
+
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
|
352
|
+
|
|
353
|
+
# Dump
|
|
354
|
+
pg_dump -Fc -Z 6 -f "${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.dump" "${DB_NAME}"
|
|
355
|
+
|
|
356
|
+
# Verify dump was created and is non-empty
|
|
357
|
+
if [ ! -s "${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.dump" ]; then
|
|
358
|
+
echo "ERROR: Backup file is empty or missing" >&2
|
|
359
|
+
exit 1
|
|
360
|
+
fi
|
|
361
|
+
|
|
362
|
+
# Clean old backups
|
|
363
|
+
find "${BACKUP_DIR}" -name "${DB_NAME}_*.dump" -mtime +${RETENTION_DAYS} -delete
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### Dedicated Backup Tools
|
|
367
|
+
|
|
368
|
+
For production environments, consider purpose-built tools that handle scheduling, retention, compression, and PITR:
|
|
369
|
+
|
|
370
|
+
- **pgBackRest** — parallel backup/restore, incremental backups, S3/GCS/Azure support, built-in PITR
|
|
371
|
+
- **Barman** — backup management with retention policies, remote backup, WAL archiving
|
|
372
|
+
- **pg_probackup** — incremental backups with page-level tracking, merge, validation
|